@chaosity/location-client-react 0.4.0 → 0.5.0

package/dist/cjs/hooks/useMapLanguage.d.ts

@@ -0,0 +1,16 @@
+import type { MapLike } from '@chaosity/location-client';
+/**
+ * React hook that keeps map label language in sync with the `language` prop.
+ *
+ * Registers a persistent `style.load` listener so language is automatically
+ * reapplied whenever `map.setStyle()` is called (e.g. style or color scheme change).
+ * Also applies immediately if the style is already loaded.
+ *
+ * @param map - MapLibre Map instance, or null while the map is initializing
+ * @param language - ISO 639-1 language code (e.g. 'en', 'fr', 'de', 'ja')
+ *
+ * @example
+ * const [mapInstance, setMapInstance] = useState<maplibregl.Map | null>(null)
+ * useMapLanguage(mapInstance, language)
+ */
+export declare function useMapLanguage(map: MapLike | null, language: string): void;

package/dist/cjs/hooks/useMapLanguage.js

@@ -0,0 +1,34 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useMapLanguage = useMapLanguage;
+const location_client_1 = require("@chaosity/location-client");
+const react_1 = require("react");
+/**
+ * React hook that keeps map label language in sync with the `language` prop.
+ *
+ * Registers a persistent `style.load` listener so language is automatically
+ * reapplied whenever `map.setStyle()` is called (e.g. style or color scheme change).
+ * Also applies immediately if the style is already loaded.
+ *
+ * @param map - MapLibre Map instance, or null while the map is initializing
+ * @param language - ISO 639-1 language code (e.g. 'en', 'fr', 'de', 'ja')
+ *
+ * @example
+ * const [mapInstance, setMapInstance] = useState<maplibregl.Map | null>(null)
+ * useMapLanguage(mapInstance, language)
+ */
+function useMapLanguage(map, language) {
+    (0, react_1.useEffect)(() => {
+        if (!map)
+            return;
+        const applyFn = () => (0, location_client_1.applyMapLanguage)(map, language);
+        if (map.isStyleLoaded()) {
+            applyFn();
+        }
+        map.on('style.load', applyFn);
+        return () => {
+            map.off('style.load', applyFn);
+        };
+    }, [map, language]);
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,3 @@
+export { LocationClientProvider, useLocationClient, } from './provider/LocationClientProvider.js';
+export type { LocationClient, LocationClientProviderProps, SendOptions, } from './provider/LocationClientProvider.js';
+export { useMapLanguage } from './hooks/useMapLanguage.js';

package/dist/cjs/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useMapLanguage = exports.useLocationClient = exports.LocationClientProvider = void 0;
+var LocationClientProvider_js_1 = require("./provider/LocationClientProvider.js");
+Object.defineProperty(exports, "LocationClientProvider", { enumerable: true, get: function () { return LocationClientProvider_js_1.LocationClientProvider; } });
+Object.defineProperty(exports, "useLocationClient", { enumerable: true, get: function () { return LocationClientProvider_js_1.useLocationClient; } });
+var useMapLanguage_js_1 = require("./hooks/useMapLanguage.js");
+Object.defineProperty(exports, "useMapLanguage", { enumerable: true, get: function () { return useMapLanguage_js_1.useMapLanguage; } });

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/cjs/provider/LocationClientProvider.d.ts

@@ -0,0 +1,63 @@
+import type { ClientConfig } from '@chaosity/location-client';
+import { type AppConfigClaims } from '@chaosity/location-client';
+import type { ReactNode } from 'react';
+/**
+ * Per-request transport options.
+ *
+ * Declared structurally rather than imported so this package builds against the
+ * currently published client; it matches `SendOptions` there exactly.
+ */
+export interface SendOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    retry?: false | {
+        maxAttempts?: number;
+    };
+}
+/**
+ * What the provider hands out.
+ *
+ * An interface rather than `GeoPlacesClient` because the provider wraps the
+ * real client to refresh tokens first, and a class with private fields is not
+ * structurally assignable — which is why this used to be an `Object.create`
+ * prototype hack.
+ */
+export interface LocationClient {
+    readonly config: {
+        serviceId: string;
+    };
+    send<TInput, TOutput>(command: TInput, options?: SendOptions): Promise<TOutput>;
+    /**
+     * This application's own configuration, read from the access token —
+     * bias precision, and the countries it is scoped to (api#65).
+     *
+     * Here so a React app can SHOW its own settings: populate a country
+     * selector with the markets it serves, label a settings screen. Being a
+     * few minutes stale is cosmetic for that.
+     *
+     * It is not an entitlement check, and the `countries` value must not be
+     * used to shape requests. The token is a snapshot; the API reads the scope
+     * fresh from the application row on every call. Injecting a stale scope
+     * turns a request that would have succeeded into a 400. See
+     * `AppConfigClaims` in @chaosity/location-client for the measurement.
+     *
+     * Returns `{}` when the token carries no application config, which is the
+     * case until one is set in the portal.
+     */
+    getAppConfig(): AppConfigClaims;
+}
+interface LocationClientContextValue {
+    client: LocationClient | null;
+    getToken: () => string | undefined;
+    loading: boolean;
+    error: string | null;
+}
+export interface LocationClientProviderProps {
+    children: ReactNode;
+    getConfig: () => Promise<ClientConfig & {
+        expiresAt?: number;
+    }>;
+}
+export declare function LocationClientProvider({ children, getConfig, }: LocationClientProviderProps): import("react").JSX.Element;
+export declare function useLocationClient(): LocationClientContextValue;
+export {};

package/dist/cjs/provider/LocationClientProvider.js

@@ -0,0 +1,215 @@
+"use strict";
+'use client';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocationClientProvider = LocationClientProvider;
+exports.useLocationClient = useLocationClient;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const location_client_1 = require("@chaosity/location-client");
+const debug_1 = __importDefault(require("debug"));
+const react_1 = require("react");
+const log = (0, debug_1.default)('location-client-react:provider');
+const LocationClientContext = (0, react_1.createContext)(undefined);
+const DEFAULT_LIFETIME_MS = 900000;
+/**
+ * When this token needs replacing.
+ *
+ * The `exp` claim first — it is the only value that cannot disagree with what
+ * the API will accept, and the server-side TokenProvider reads the same one.
+ * `expiresAt` is whatever `getConfig` chose to report, and the final fallback
+ * is a guess used only when the token cannot be parsed at all.
+ */
+function expiryOf(cfg) {
+    return ((0, location_client_1.readTokenExpiry)(cfg.token) ??
+        cfg.expiresAt ??
+        Date.now() + DEFAULT_LIFETIME_MS);
+}
+function LocationClientProvider({ children, getConfig, }) {
+    const [client, setClient] = (0, react_1.useState)(null);
+    const [loading, setLoading] = (0, react_1.useState)(true);
+    const [error, setError] = (0, react_1.useState)(null);
+    const tokenRef = (0, react_1.useRef)(undefined);
+    const expiresAtRef = (0, react_1.useRef)(null);
+    const getConfigRef = (0, react_1.useRef)(getConfig);
+    const refreshPromiseRef = (0, react_1.useRef)(null);
+    const timerRef = (0, react_1.useRef)(null);
+    const mountedRef = (0, react_1.useRef)(true);
+    (0, react_1.useEffect)(() => {
+        getConfigRef.current = getConfig;
+    }, [getConfig]);
+    const isTokenExpired = (0, react_1.useCallback)(() => {
+        if (!expiresAtRef.current)
+            return true;
+        return (Date.now() >= expiresAtRef.current - location_client_1.TOKEN_REFRESH_BUFFER_SECONDS * 1000);
+    }, []);
+    /**
+     * Refresh once, however many callers ask at the same moment.
+     *
+     * REJECTS on failure. It used to swallow the error into state and resolve,
+     * so `send` carried on with the token it already had — guaranteeing a 401 on
+     * the very next call and reporting it as an API error rather than a refresh
+     * failure.
+     */
+    const refreshToken = (0, react_1.useCallback)(async () => {
+        if (refreshPromiseRef.current)
+            return refreshPromiseRef.current;
+        refreshPromiseRef.current = (async () => {
+            const cfg = await getConfigRef.current();
+            tokenRef.current = cfg.token;
+            expiresAtRef.current = expiryOf(cfg);
+            log('Token refreshed (expires in %ds)', Math.floor((expiresAtRef.current - Date.now()) / 1000));
+            if (mountedRef.current)
+                setError(null);
+        })();
+        try {
+            await refreshPromiseRef.current;
+            scheduleRefreshRef.current();
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Failed to refresh token';
+            log('Token refresh failed: %s', message);
+            if (mountedRef.current)
+                setError(message);
+            throw err;
+        }
+        finally {
+            refreshPromiseRef.current = null;
+        }
+    }, []);
+    /**
+     * Refresh AHEAD of expiry, on a timer.
+     *
+     * This is the whole fix for the map path. MapLibre's `transformRequest` is
+     * synchronous by contract, so `getToken` cannot await anything — the token it
+     * reads has to be valid already. Refresh used to happen only inside the `send`
+     * wrapper, which the map never calls: it requests tiles, glyphs and sprites
+     * directly. So after 15 minutes every map request failed, for as long as the
+     * page stayed open, and no amount of panning recovered it.
+     */
+    const scheduleRefresh = (0, react_1.useCallback)(() => {
+        if (timerRef.current)
+            clearTimeout(timerRef.current);
+        if (!expiresAtRef.current)
+            return;
+        const delay = Math.max(0, expiresAtRef.current - location_client_1.TOKEN_REFRESH_BUFFER_SECONDS * 1000 - Date.now());
+        log('Next refresh in %ds', Math.floor(delay / 1000));
+        timerRef.current = setTimeout(() => {
+            // Errors are already surfaced onto state by refreshToken; swallow here so
+            // a failed background refresh cannot become an unhandled rejection.
+            void refreshToken().catch(() => { });
+        }, delay);
+    }, [refreshToken]);
+    // refreshToken and scheduleRefresh reference each other; a ref breaks the cycle
+    // without recreating either callback on every render.
+    const scheduleRefreshRef = (0, react_1.useRef)(() => { });
+    (0, react_1.useEffect)(() => {
+        scheduleRefreshRef.current = scheduleRefresh;
+    }, [scheduleRefresh]);
+    /**
+     * Synchronous read for the map path.
+     *
+     * If the token is already stale — a timer that never fired because the tab was
+     * backgrounded and throttled — this kicks off a refresh but cannot wait for it.
+     * The current read still returns the stale value; the point is that the NEXT
+     * one will not.
+     */
+    const getToken = (0, react_1.useCallback)(() => {
+        // `tokenRef.current` guards the pre-initialisation window: until the first
+        // config load lands there is no expiry to judge, and firing here would race
+        // the initial fetch and request a second token nobody asked for.
+        if (tokenRef.current && isTokenExpired() && !refreshPromiseRef.current) {
+            log('Stale token read — refreshing in the background');
+            void refreshToken().catch(() => { });
+        }
+        return tokenRef.current;
+    }, [isTokenExpired, refreshToken]);
+    const ensureValidToken = (0, react_1.useCallback)(async () => {
+        if (!isTokenExpired())
+            return;
+        await refreshToken();
+    }, [isTokenExpired, refreshToken]);
+    const ensureValidTokenRef = (0, react_1.useRef)(ensureValidToken);
+    (0, react_1.useEffect)(() => {
+        ensureValidTokenRef.current = ensureValidToken;
+    }, [ensureValidToken]);
+    /**
+     * A backgrounded tab has its timers throttled, so the scheduled refresh can be
+     * arbitrarily late. Refresh on the way back in, before the user touches the map.
+     */
+    (0, react_1.useEffect)(() => {
+        if (typeof document === 'undefined')
+            return;
+        const onVisible = () => {
+            if (document.visibilityState === 'visible' &&
+                tokenRef.current &&
+                isTokenExpired()) {
+                log('Tab visible again with a stale token — refreshing');
+                void refreshToken().catch(() => { });
+            }
+        };
+        document.addEventListener('visibilitychange', onVisible);
+        return () => document.removeEventListener('visibilitychange', onVisible);
+    }, [isTokenExpired, refreshToken]);
+    (0, react_1.useEffect)(() => {
+        mountedRef.current = true;
+        log('Initializing LocationClientProvider');
+        getConfigRef
+            .current()
+            .then((cfg) => {
+            if (!mountedRef.current)
+                return;
+            tokenRef.current = cfg.token;
+            expiresAtRef.current = expiryOf(cfg);
+            const baseClient = new location_client_1.GeoPlacesClient({
+                apiUrl: cfg.apiUrl,
+                token: cfg.token,
+                getToken,
+            });
+            // A plain object, not Object.create(baseClient): the prototype hack was
+            // opaque, and its `send` dropped the second argument entirely — so once
+            // the client gained `signal`/`timeoutMs`, every option passed through
+            // this provider would have been silently discarded.
+            const refreshing = {
+                config: baseClient.config,
+                async send(command, options) {
+                    await ensureValidTokenRef.current();
+                    return baseClient.send(command, options);
+                },
+                // Reads whatever token the client currently holds. Deliberately not
+                // awaiting a refresh: this is display data, callers expect it to be
+                // synchronous, and a token that is minutes from expiry carries the
+                // same application config as its replacement will.
+                getAppConfig() {
+                    return baseClient.getAppConfig();
+                },
+            };
+            setClient(refreshing);
+            scheduleRefreshRef.current();
+            log('Client initialized (token expires in %ds)', Math.floor((expiresAtRef.current - Date.now()) / 1000));
+            setLoading(false);
+        })
+            .catch((err) => {
+            if (!mountedRef.current)
+                return;
+            const message = err instanceof Error ? err.message : 'Failed to initialize client';
+            log('Initialization failed: %s', message);
+            setError(message);
+            setLoading(false);
+        });
+        return () => {
+            mountedRef.current = false;
+            if (timerRef.current)
+                clearTimeout(timerRef.current);
+        };
+    }, [getToken]);
+    return ((0, jsx_runtime_1.jsx)(LocationClientContext.Provider, { value: { client, getToken, loading, error }, children: children }));
+}
+function useLocationClient() {
+    const context = (0, react_1.useContext)(LocationClientContext);
+    if (context === undefined) {
+        throw new Error('useLocationClient must be used within LocationClientProvider');
+    }
+    return context;
+}

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { LocationClientProvider, useLocationClient, } from './provider/LocationClientProvider';
-export type { LocationClient, LocationClientProviderProps, SendOptions, } from './provider/LocationClientProvider';
-export { useMapLanguage } from './hooks/useMapLanguage';
+export { LocationClientProvider, useLocationClient, } from './provider/LocationClientProvider.js';
+export type { LocationClient, LocationClientProviderProps, SendOptions, } from './provider/LocationClientProvider.js';
+export { useMapLanguage } from './hooks/useMapLanguage.js';

package/dist/index.js

@@ -1,2 +1,2 @@
-export { LocationClientProvider, useLocationClient, } from './provider/LocationClientProvider';
-export { useMapLanguage } from './hooks/useMapLanguage';
+export { LocationClientProvider, useLocationClient, } from './provider/LocationClientProvider.js';
+export { useMapLanguage } from './hooks/useMapLanguage.js';

package/package.json

@@ -1,20 +1,21 @@
 {
   "name": "@chaosity/location-client-react",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "React bindings for Chaosity Location Service client",
   "type": "module",
-  "main": "dist/index.js",
+  "main": "dist/cjs/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && tsc -p tsconfig.cjs.json && node scripts/finish-cjs.mjs",
     "dev": "tsc --watch",
     "lint": "eslint . && prettier --check .",
     "lint:fix": "eslint --fix . && prettier --write .",
     "format": "prettier --write .",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "npm run build",
-    "prepare": "husky"
+    "prepublishOnly": "npm run build && npm run smoke",
+    "prepare": "husky",
+    "smoke": "node scripts/smoke.mjs"
   },
   "keywords": [
     "react",
@@ -47,7 +48,7 @@
     }
   },
   "devDependencies": {
-    "@chaosity/location-client": "^0.4.0",
+    "@chaosity/location-client": "^0.6.0",
     "@eslint/js": "^10.0.1",
     "@testing-library/react": "^16.0.0",
     "@testing-library/user-event": "^14.0.0",
@@ -71,5 +72,22 @@
   "files": [
     "dist",
     "README.md"
-  ]
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "module": "dist/index.js",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  }
 }