@goway.to/maps 0.0.0-stage → 0.1.0

package/dist/useUserLocation.js

@@ -0,0 +1,247 @@
+/**
+ * Contextual, non-persisted device location.
+ *
+ * Two statements this hook is the enforcement point for:
+ *
+ *  1. **Opening the map never asks.** Nothing here runs on mount. The
+ *     permission is not even READ until the user invokes a location-dependent
+ *     action, so there is no code path from "app cold-started" to a system
+ *     prompt. `<UserLocation>` correspondingly draws the dot only against a
+ *     permission already granted.
+ *  2. **The coordinate is transient.** It lives in React state for the life of
+ *     the screen and is written to no store, no cache, no query key, no
+ *     AsyncStorage and no backend table. There is deliberately no "last known
+ *     location" to restore: a location history is exactly the artefact the rule
+ *     forbids, and the cheapest way not to have one is not to have a writer.
+ *
+ * ## Failing usefully
+ *
+ * `locate()` resolves `null` for four DIFFERENT reasons, and the difference is
+ * the whole product: "you declined", "your browser will not even ask any more",
+ * "this page is not https" and "the device could not get a fix" need four
+ * different sentences and three different next steps. The reason is therefore
+ * part of the state (`error`), alongside whether asking again could plausibly
+ * prompt (`canAskAgain`) — a caller that shows a spinner and then nothing is
+ * the bug this hook exists to make impossible to write by accident.
+ *
+ * ## Web, where `expo-location` is not enough
+ *
+ * Two web behaviours are corrected here rather than reported as-is:
+ *
+ *  - **A non-secure context.** `navigator.geolocation` EXISTS on an `http://`
+ *    page; it just fails every call with `PERMISSION_DENIED` without ever
+ *    prompting. Reported verbatim that is "the user declined", which is a lie
+ *    about a person who was never asked — and it sends them to look for a
+ *    permission they never set. `window.isSecureContext` is the reliable
+ *    signal, and it is checked BEFORE anything touches the permission.
+ *  - **A durable block.** `expo-location`'s web backend answers `canAskAgain:
+ *    true` unconditionally, including for an origin the browser has blocked, so
+ *    "ask again" silently resolves to the same denial forever. The Permissions
+ *    API knows the truth, so it is consulted directly.
+ */
+import { useCallback, useRef, useState } from 'react';
+import { Platform } from 'react-native';
+import * as Location from 'expo-location';
+import { locationPermission } from './locationStore';
+/** How long to wait for a fix before giving the user their UI back. */
+const FIX_TIMEOUT_MS = 12_000;
+const INITIAL = {
+    status: 'unknown',
+    coordinate: null,
+    isLocating: false,
+    error: null,
+    canAskAgain: true,
+};
+export function useUserLocation() {
+    const [state, setState] = useState(INITIAL);
+    // Coalesce concurrent taps onto one permission prompt + one fix.
+    const inFlight = useRef(null);
+    const locate = useCallback(async () => {
+        if (inFlight.current)
+            return inFlight.current;
+        const run = (async () => {
+            setState((prev) => ({ ...prev, isLocating: true, error: null }));
+            try {
+                // Before the permission, not after it: an http:// page never reaches a
+                // prompt, so attributing the failure to the user would be wrong AND
+                // would point them at a setting that is not the problem.
+                if (isInsecureWebContext()) {
+                    setState({
+                        status: 'unknown',
+                        coordinate: null,
+                        isLocating: false,
+                        error: 'insecureContext',
+                        canAskAgain: false,
+                    });
+                    return null;
+                }
+                // The browser's own record of this origin, which `expo-location` does
+                // not surface. `denied` here means no prompt will appear, whatever we
+                // call next.
+                if ((await webPermissionState()) === 'denied') {
+                    locationPermission.settle('denied');
+                    setState({
+                        status: 'denied',
+                        coordinate: null,
+                        isLocating: false,
+                        error: 'denied',
+                        canAskAgain: false,
+                    });
+                    return null;
+                }
+                // Read first: `getForegroundPermissionsAsync` never prompts, so an
+                // already-granted user is not re-asked, and a previously-denied one is
+                // not re-prompted on every tap on platforms that would allow it.
+                let permission = await Location.getForegroundPermissionsAsync();
+                if (!permission.granted && permission.canAskAgain) {
+                    permission = await Location.requestForegroundPermissionsAsync();
+                }
+                locationPermission.settle(permission.granted ? 'granted' : 'denied');
+                if (!permission.granted) {
+                    setState({
+                        status: 'denied',
+                        coordinate: null,
+                        isLocating: false,
+                        error: 'denied',
+                        canAskAgain: await canAskAgainAfterDenial(permission.canAskAgain),
+                    });
+                    return null;
+                }
+                const position = await withTimeout(Location.getCurrentPositionAsync({ accuracy: Location.Accuracy.Balanced }), FIX_TIMEOUT_MS);
+                if (!position) {
+                    setState((prev) => ({
+                        ...prev,
+                        status: 'granted',
+                        isLocating: false,
+                        error: 'timeout',
+                        canAskAgain: true,
+                    }));
+                    return null;
+                }
+                const coordinate = {
+                    latitude: position.coords.latitude,
+                    longitude: position.coords.longitude,
+                };
+                setState({
+                    status: 'granted',
+                    coordinate,
+                    isLocating: false,
+                    error: null,
+                    canAskAgain: true,
+                });
+                return coordinate;
+            }
+            catch (error) {
+                // Web rejects with a `GeolocationPositionError`, which still separates
+                // "you declined" from "the device has no position" from "it timed out".
+                // Collapsing all three into one sentence is how a user ends up told to
+                // check a permission that was never the problem.
+                const reason = reasonForThrown(error);
+                const canAskAgain = reason === 'denied' ? await canAskAgainAfterDenial(true) : true;
+                setState((prev) => ({
+                    ...prev,
+                    status: reason === 'denied' ? 'denied' : prev.status,
+                    isLocating: false,
+                    error: reason,
+                    canAskAgain,
+                }));
+                return null;
+            }
+            finally {
+                inFlight.current = null;
+            }
+        })();
+        inFlight.current = run;
+        return run;
+    }, []);
+    const forget = useCallback(() => {
+        setState((prev) => ({ ...prev, coordinate: null, error: null }));
+    }, []);
+    return { ...state, locate, forget };
+}
+/**
+ * `true` on a web page the browser will not give geolocation to at all.
+ *
+ * Checked rather than inferred: the failure an insecure origin produces is
+ * indistinguishable, at the call site, from a user pressing "Block".
+ */
+function isInsecureWebContext() {
+    if (Platform.OS !== 'web')
+        return false;
+    if (typeof window === 'undefined')
+        return false;
+    // `undefined` (an old browser that has no such property) is NOT a failure —
+    // only an explicit `false` is.
+    return window.isSecureContext === false;
+}
+/**
+ * The browser's durable answer for this origin, or `'unknown'` off web and
+ * wherever the Permissions API is absent (older Safari, some webviews).
+ *
+ * Deliberately never PROMPTS: `query()` is a read, which is what makes it safe
+ * to call on the way into a user-initiated action.
+ */
+async function webPermissionState() {
+    if (Platform.OS !== 'web')
+        return 'unknown';
+    try {
+        const permissions = globalThis.navigator?.permissions;
+        if (!permissions?.query)
+            return 'unknown';
+        const status = await permissions.query({ name: 'geolocation' });
+        return status.state === 'granted' || status.state === 'denied' || status.state === 'prompt'
+            ? status.state
+            : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * After a decline, whether a further tap could still reach a prompt.
+ *
+ * On native the platform's own `canAskAgain` is the answer. On web it is
+ * hard-coded `true` by `expo-location`, so the Permissions API is re-read: a
+ * decline the browser has turned into a block for this origin flips to `denied`
+ * immediately, and offering "Try again" for that would be offering a button
+ * that provably does nothing.
+ */
+async function canAskAgainAfterDenial(platformAnswer) {
+    if (Platform.OS !== 'web')
+        return platformAnswer;
+    const state = await webPermissionState();
+    // `'unknown'` (no Permissions API) keeps the optimistic answer: a browser
+    // that cannot tell us should not have us telling the user it is hopeless.
+    return state !== 'denied';
+}
+/** A thrown geolocation failure, mapped onto the reason a user can act on. */
+function reasonForThrown(error) {
+    const code = error?.code;
+    if (typeof code === 'number') {
+        // 1 PERMISSION_DENIED, 2 POSITION_UNAVAILABLE, 3 TIMEOUT — the W3C codes,
+        // written out because `GeolocationPositionError` is a web-only global and
+        // this module also runs on native.
+        if (code === 1)
+            return 'denied';
+        if (code === 3)
+            return 'timeout';
+        return 'unavailable';
+    }
+    return 'unavailable';
+}
+/** Resolve `null` instead of hanging forever on a device that never fixes. */
+async function withTimeout(promise, ms) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(null), ms);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/zoom.d.ts

@@ -0,0 +1,2 @@
+export declare const ZoomLevelContext: import("react").Context<number>;
+export declare function useZoomLevel(): number;

package/dist/zoom.js

@@ -0,0 +1,10 @@
+/**
+ * The map's whole zoom level, published to its children. `<Markers>` clusters
+ * by it; it changes only when the camera crosses a level, so a pan re-renders
+ * nothing.
+ */
+import { createContext, useContext } from 'react';
+export const ZoomLevelContext = createContext(0);
+export function useZoomLevel() {
+    return useContext(ZoomLevelContext);
+}

package/metro.cjs

@@ -0,0 +1,70 @@
+/**
+ * `@goway.to/maps/metro` — what a Metro (Expo) web build needs for the map.
+ *
+ *     const { withGoWayMaps } = require('@goway.to/maps/metro');
+ *     module.exports = withGoWayMaps(getDefaultConfig(__dirname));
+ *
+ * maplibre-gl 6 is ESM-only and starts its tile worker BY URL, derived from
+ * `import.meta.url` — which inside a Metro bundle is not the package
+ * directory, so left alone the worker never starts and every tile request
+ * fails silently, with no build error and no failing test. `MapView` on the
+ * web points the worker at `/vendor/maplibre-gl/<version>/` on the page's own
+ * origin; this copies the INSTALLED maplibre-gl's worker modules there, into
+ * the app's `public/`, before Metro serves or exports it. Keyed on the
+ * version, so the worker can never be a different release from the main
+ * thread it talks to (their message protocol is internal and unversioned).
+ *
+ * `public/vendor/` is a verbatim copy of an installed dependency: gitignore it.
+ * Bundlers that understand `new URL(…, import.meta.url)` (Vite, webpack) do
+ * not need this.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+
+/** Files the worker needs, relative to `maplibre-gl/dist/`. */
+const WORKER_FILES = ['maplibre-gl-worker.mjs', 'maplibre-gl-shared.mjs'];
+
+/**
+ * Write the installed maplibre-gl's worker modules to
+ * `<projectRoot>/public/vendor/maplibre-gl/<version>/` and return that
+ * directory.
+ */
+function vendorMaplibreWorker(projectRoot) {
+  const packageJsonPath = require.resolve('maplibre-gl/package.json', { paths: [projectRoot] });
+  const { version } = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  const distDir = path.join(path.dirname(packageJsonPath), 'dist');
+  const vendorRoot = path.join(projectRoot, 'public', 'vendor', 'maplibre-gl');
+  const targetDir = path.join(vendorRoot, version);
+
+  fs.mkdirSync(targetDir, { recursive: true });
+  for (const file of WORKER_FILES) {
+    const source = path.join(distDir, file);
+    const target = path.join(targetDir, file);
+    const bytes = fs.readFileSync(source);
+    // Only on a real difference: Metro watches `public/`, and rewriting
+    // identical bytes on every start would churn the watcher.
+    if (!fs.existsSync(target) || !fs.readFileSync(target).equals(bytes)) {
+      fs.writeFileSync(target, bytes);
+    }
+  }
+
+  // Drop directories left by a previous version, so an old worker is never
+  // exported next to the new one.
+  for (const entry of fs.readdirSync(vendorRoot)) {
+    if (entry !== version)
+      fs.rmSync(path.join(vendorRoot, entry), { recursive: true, force: true });
+  }
+  return targetDir;
+}
+
+/**
+ * Copy the worker for this project, and return the Metro config unchanged.
+ * `projectRoot` defaults to the config's own.
+ */
+function withGoWayMaps(config, options = {}) {
+  const projectRoot = options.projectRoot ?? config.projectRoot ?? process.cwd();
+  vendorMaplibreWorker(projectRoot);
+  return config;
+}
+
+module.exports = { withGoWayMaps, vendorMaplibreWorker, WORKER_FILES };

package/package.json

@@ -1,6 +1,117 @@
 {
   "name": "@goway.to/maps",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "GoWay's maps SDK for React and React Native: one declarative map for web and native — GoWay styles that follow your theme, Bloom markers with clustering, a camera framed by value, user location without a prompt on mount.",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "The Oxy Collective, Inc.",
+  "homepage": "https://github.com/OxyHQ/GoWay/tree/main/packages/maps#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OxyHQ/GoWay.git",
+    "directory": "packages/maps"
+  },
+  "bugs": {
+    "url": "https://github.com/OxyHQ/GoWay/issues"
+  },
+  "keywords": [
+    "goway",
+    "oxy",
+    "maps",
+    "maplibre",
+    "react-native",
+    "expo",
+    "bloom"
+  ],
+  "sideEffects": [
+    "*.css",
+    "./dist/MapView.web.js"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "react-native": "./dist/index.js",
+  "browser": "./dist/index.web.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/index.web.js",
+      "react-native": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./brand": {
+      "types": "./dist/brand/artwork.d.ts",
+      "default": "./dist/brand/artwork.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "default": "./dist/plugin.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    },
+    "./metro": "./metro.cjs",
+    "./app.plugin.js": "./app.plugin.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "metro.cjs",
+    "app.plugin.js",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run typecheck && bun run test && bun run build"
+  },
+  "dependencies": {
+    "supercluster": "^8.0.1"
+  },
+  "peerDependencies": {
+    "@goway.to/sdk": ">=0.6.0",
+    "@maplibre/maplibre-react-native": ">=11.4.0",
+    "@oxy.so/bloom": ">=10.16.0",
+    "expo-location": "*",
+    "maplibre-gl": ">=6.10.0",
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0",
+    "react-native": ">=0.80.0",
+    "react-native-reanimated": ">=4.0.0",
+    "react-native-svg": ">=15.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@maplibre/maplibre-react-native": {
+      "optional": true
+    },
+    "maplibre-gl": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@goway.to/sdk": "0.6.0",
+    "@maplibre/maplibre-react-native": "^11.4.0",
+    "@oxy.so/bloom": "^10.16.1",
+    "@types/react": "^19.2.17",
+    "@types/supercluster": "^7.1.3",
+    "expo-location": "~57.0.19",
+    "maplibre-gl": "6.10.0",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "react-native": "0.86.0",
+    "react-native-reanimated": "4.5.0",
+    "react-native-svg": "15.15.5",
+    "typescript": "^5.9.3"
+  }
+}