Function __location__ 

pub fn __location__(
    template: PageTemplate,
) -> Result<LocationData, LocationError>

Capture the user’s geographic location by opening the browser to a local consent page.

This is a blocking call. It:

1. Binds a temporary HTTP server on a free 127.0.0.1 port.
2. Opens http://127.0.0.1:<port>/ in the system’s default browser.
3. Waits for the browser to POST location data (or an error) back.
4. Shuts the server down and returns the result.

Pass a PageTemplate to control what the user sees in the browser. Use PageTemplate::default() for the built-in single-button consent page.

Errors

Variant	Cause
LocationError::PermissionDenied	User denied the browser prompt.
LocationError::PositionUnavailable	Device cannot determine position.
LocationError::Timeout	No fix within the browser’s 30 s timeout.
LocationError::ServerError	Failed to start the local HTTP server or runtime.

Example

use toolkit_zero::location::browser::{__location__, PageTemplate, LocationError};

// Default built-in page
match __location__(PageTemplate::default()) {
    Ok(data) => println!("lat={:.6} lon={:.6} ±{:.0}m",
                         data.latitude, data.longitude, data.accuracy),
    Err(LocationError::PermissionDenied) => eprintln!("access denied"),
    Err(e) => eprintln!("error: {e}"),
}

// Tickbox page with custom consent label
let _ = __location__(PageTemplate::Tickbox {
    title:        None,
    body_text:    None,
    consent_text: Some("I agree to share my location.".into()),
});

Note on async callers

If you are already inside a Tokio async context (e.g. inside #[tokio::main]), use __location_async__ instead — it is the raw async fn and avoids spawning an extra OS thread.

Examples found in repository

examples/location_browser.rs (line 140)

async fn main() {
    println!("=== location_browser example ===\n");

    // ── 1. Async call (preferred inside #[tokio::main]) ───────────────────────
    println!("Opening browser to acquire location (async)…");
    match __location_async__(PageTemplate::default()).await {
        Ok(data) => print_location("Async result:", &data),
        Err(LocationError::PermissionDenied) => {
            eprintln!("Location permission denied — skipping async call.");
        }
        Err(e) => eprintln!("Async location error: {e}"),
    }

    println!();

    // ── 2. Blocking call (also safe inside #[tokio::main]) ────────────────────
    // __location__ detects the existing Tokio runtime and offloads to a
    // dedicated OS thread automatically — no runtime nesting issue.
    println!("Opening browser to acquire location (blocking)…");
    let template = PageTemplate::Tickbox {
        title:        Some("Confirm Location".into()),
        body_text:    None,
        consent_text: Some("I allow this example to read my location.".into()),
    };
    match __location__(template) {
        Ok(data) => print_location("Blocking result:", &data),
        Err(LocationError::PermissionDenied) => {
            eprintln!("Location permission denied — skipping blocking call.");
        }
        Err(e) => eprintln!("Blocking location error: {e}"),
    }
}