toolkit_zero/location/mod.rs
1//! Geographic location acquisition API.
2//!
3//! This module serves as the authoritative entry point for all geographic
4//! coordinate retrieval within the toolkit. It is structured around the
5//! concept of interchangeable *acquisition strategies*: each sub-module
6//! implements a self-contained mechanism for obtaining location data,
7//! allowing new strategies to be introduced incrementally without disrupting
8//! the existing public interface.
9//!
10//! # Acquisition strategies
11//!
12//! | Sub-module | Mechanism | Platform support |
13//! |---|---|---|
14//! | [`browser`] | Instantiates a transient local HTTP server and directs the
15//! system's default browser to a consent page, which acquires coordinates
16//! through the standardised [Web Geolocation API]. | Platform-independent |
17//!
18//! [Web Geolocation API]: https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API
19//!
20//! # Attribute macro
21//!
22//! The [`browser::browser`] attribute macro wraps the call to
23//! [`browser::__location__`] or [`browser::__location_async__`] and builds the
24//! [`browser::PageTemplate`] for you.
25//!
26//! ```rust,ignore
27//! use toolkit_zero::location::browser::{browser, LocationData, LocationError};
28//!
29//! async fn run() -> Result<LocationData, LocationError> {
30//! #[browser(title = "My App")]
31//! fn loc() {}
32//! Ok(loc)
33//! }
34//! ```
35//!
36//! # Feature flag
37//!
38//! This module is compiled when the `location` (or `location-browser`) feature is enabled:
39//!
40//! ```toml
41//! [dependencies]
42//! toolkit-zero = { version = "...", features = ["location"] }
43//! ```
44
45#[cfg(feature = "location-browser")]
46pub mod browser;
47
48#[cfg(feature = "backend-deps")]
49pub mod backend_deps;