@visns-studio/visns-components 6.24.4 → 6.26.0

package/src/components/mapboxSearchBox.js

@@ -0,0 +1,640 @@
+/**
+ * The address autocomplete's Mapbox layer: URLs, session tokens, and the
+ * adapter that turns a Search Box record back into the Geocoding v5 feature
+ * shape every consuming form already reads.
+ *
+ * Kept React-free so `node --test` can import it. Everything worth pinning
+ * about this feature is in here — the component around it is a text box, a
+ * debounce and a list.
+ *
+ * WHY THE MOVE. `geocoding/v5/mapbox.places` is deprecated, and its POI half
+ * is worse than deprecated: "epiq perth" — a real business at Level 9/16 St
+ * Georges Terrace, Perth 6000 — came back as a handful of Queensland streets.
+ * The same token against `search/searchbox/v1/suggest` returns
+ * `Epiq | Perth 6000 | poi` as the second suggestion, because Search Box POIs
+ * are Foursquare-backed. Businesses by name work now; they did not before.
+ *
+ * WHY AN ADAPTER RATHER THAN A NEW CONTRACT. Every `"address"` field in every
+ * consuming app hands its pick to `Form.jsx`'s `autocompleteSelect`, which
+ * reads v5 keys — `address`, `text`, and a `context` ARRAY whose entries are
+ * typed by a dotted `id` (`postcode.123`, `region.456`). Search Box returns a
+ * context OBJECT keyed by type instead. Rather than edit that consumer and
+ * every form config behind it, the two-step suggest/retrieve result is
+ * translated back into the old shape here, once. Nothing downstream changes.
+ */
+
+const SEARCH_BOX_BASE = 'https://api.mapbox.com/search/searchbox/v1';
+
+export const SUGGEST_URL = `${SEARCH_BOX_BASE}/suggest`;
+export const RETRIEVE_URL = `${SEARCH_BOX_BASE}/retrieve`;
+
+/**
+ * What the dropdown asks for. `address` is the bread and butter; `poi` is the
+ * reason for the upgrade. Both are valid `types` values on suggest — but see
+ * `isTypesParamRejection` below, which exists because that is Mapbox's word
+ * and not ours to assume forever.
+ */
+export const DEFAULT_TYPES = 'address,poi';
+
+/** Six rows is what the dropdown can show without scrolling. Suggest caps at 10. */
+export const DEFAULT_LIMIT = 6;
+
+/* --------------------------------------------------------------- session */
+
+let fallbackTokenCounter = 0;
+
+/**
+ * A session token for one typing session.
+ *
+ * THIS IS MAPBOX'S BILLING UNIT. Every suggest call carrying the same token,
+ * plus the retrieve that ends it, bills as a single session. Mint one per
+ * keystroke and a nine-letter search bills as nine sessions instead of one.
+ *
+ * `crypto.randomUUID` where it exists (every browser this library targets),
+ * then `crypto.getRandomValues` shaped into a v4 UUID, and only then a clock
+ * plus a counter. No `Math.random` at any level — a token that repeats across
+ * two users' sessions is a billing and a correlation problem, and `Math.random`
+ * is the one source here with no guarantee it will not.
+ */
+export const newSessionToken = () => {
+    const source = typeof globalThis === 'undefined' ? undefined : globalThis.crypto;
+
+    if (typeof source?.randomUUID === 'function') {
+        return source.randomUUID();
+    }
+
+    if (typeof source?.getRandomValues === 'function') {
+        const bytes = source.getRandomValues(new Uint8Array(16));
+
+        // RFC 4122 version and variant bits, so the value is a real v4 UUID
+        // rather than 32 hex characters that merely look like one.
+        bytes[6] = (bytes[6] & 0x0f) | 0x40;
+        bytes[8] = (bytes[8] & 0x3f) | 0x80;
+
+        const hex = Array.from(bytes)
+            .map((byte) => byte.toString(16).padStart(2, '0'))
+            .join('');
+
+        return [
+            hex.slice(0, 8),
+            hex.slice(8, 12),
+            hex.slice(12, 16),
+            hex.slice(16, 20),
+            hex.slice(20),
+        ].join('-');
+    }
+
+    fallbackTokenCounter += 1;
+
+    return `visns-${Date.now().toString(16)}-${fallbackTokenCounter.toString(16)}`;
+};
+
+/**
+ * Holds the current session token.
+ *
+ * `current()` mints on first use and then returns the SAME value for every
+ * later keystroke; `consume()` hands it to the retrieve and clears it, so the
+ * next thing typed opens a new session. `reset()` is for abandoning a session
+ * that never reached a retrieve (the field was cleared, autocomplete switched
+ * off) — dropping the token costs nothing, keeping a stale one bills the next
+ * user's search against the previous session.
+ */
+export const createSessionTokenManager = (mint = newSessionToken) => {
+    let token = null;
+
+    return {
+        current() {
+            if (!token) {
+                token = mint();
+            }
+
+            return token;
+        },
+        /** The token without minting one — for tests and for logging. */
+        peek() {
+            return token;
+        },
+        consume() {
+            const current = token || mint();
+            token = null;
+
+            return current;
+        },
+        reset() {
+            token = null;
+        },
+    };
+};
+
+/* ------------------------------------------------------------------ urls */
+
+const appendParam = (params, key, value) => {
+    if (value === undefined || value === null || value === '') {
+        return;
+    }
+
+    params.set(key, String(value));
+};
+
+/**
+ * `GET /search/searchbox/v1/suggest`.
+ *
+ * `proximity` and `bbox` come off the `mapbox` prop exactly as they did under
+ * v5 — same names, same "lon,lat" and "minLon,minLat,maxLon,maxLat" strings —
+ * so a consuming app that biases results towards its own city keeps doing so
+ * without touching its config.
+ */
+export const buildSuggestUrl = ({
+    query,
+    accessToken,
+    sessionToken,
+    country,
+    proximity,
+    bbox,
+    limit = DEFAULT_LIMIT,
+    types = DEFAULT_TYPES,
+} = {}) => {
+    if (!query || !accessToken) {
+        return null;
+    }
+
+    const params = new URLSearchParams();
+
+    // Unlike v5 the query is a query STRING parameter, not a path segment, so
+    // "5/12 Smith St" no longer needs the escaping v5 demanded to stop the
+    // slash splitting the path. URLSearchParams handles it either way.
+    appendParam(params, 'q', query);
+    appendParam(params, 'access_token', accessToken);
+    appendParam(params, 'session_token', sessionToken);
+    appendParam(params, 'country', country);
+    appendParam(params, 'proximity', proximity);
+    appendParam(params, 'bbox', bbox);
+    appendParam(params, 'limit', limit);
+    appendParam(params, 'types', types);
+
+    return `${SUGGEST_URL}?${params.toString()}`;
+};
+
+/**
+ * `GET /search/searchbox/v1/retrieve/{mapbox_id}`.
+ *
+ * MUST carry the same `session_token` the suggest calls used — that is what
+ * closes the session and makes the whole exchange one billable unit.
+ */
+export const buildRetrieveUrl = ({ mapboxId, accessToken, sessionToken } = {}) => {
+    if (!mapboxId || !accessToken) {
+        return null;
+    }
+
+    const params = new URLSearchParams();
+
+    appendParam(params, 'access_token', accessToken);
+    appendParam(params, 'session_token', sessionToken);
+
+    return `${RETRIEVE_URL}/${encodeURIComponent(mapboxId)}?${params.toString()}`;
+};
+
+/* -------------------------------------------------------------- payloads */
+
+/**
+ * Mapbox answers JSON, but the old code guarded against a body arriving as a
+ * string anyway and that guard has earned its keep — keep it.
+ */
+export const parsePayload = (payload) => {
+    if (typeof payload !== 'string') {
+        return payload || null;
+    }
+
+    try {
+        return JSON.parse(payload);
+    } catch {
+        return null;
+    }
+};
+
+/**
+ * Does this error read as Mapbox refusing the `types` parameter?
+ *
+ * The parameter name is `types` per the documentation, but this is the one
+ * thing in the request that is a guess about a moving API rather than a
+ * shape we control — so read the refusal rather than assume, and let the
+ * caller retry once without it. A dropdown that returns addresses and no
+ * businesses beats a dropdown that returns an error.
+ */
+export const isTypesParamRejection = (error) => {
+    const body = error?.response?.data;
+    const message =
+        typeof body === 'string'
+            ? body
+            : body?.message || body?.error || error?.message || '';
+
+    return /\btypes?\b/i.test(String(message));
+};
+
+/* --------------------------------------------------------------- helpers */
+
+const text = (value) =>
+    typeof value === 'string' && value.trim() ? value.trim() : '';
+
+/**
+ * Split a street line into its leading number and the rest.
+ *
+ * Australian addresses arrive as "16", "16A", "5/12" and "12-14" and all four
+ * are the number half. Only used when Mapbox did not break the line up for us.
+ */
+const splitStreetLine = (line) => {
+    const match = text(line).match(
+        /^(\d+[a-zA-Z]?(?:\s*[/-]\s*\d+[a-zA-Z]?)?)\s+(.+)$/
+    );
+
+    if (!match) {
+        return { number: '', street: text(line) };
+    }
+
+    return { number: match[1].replace(/\s+/g, ''), street: match[2].trim() };
+};
+
+/**
+ * The context entries the legacy consumer looks for, narrowest first — the
+ * order v5 used, which is also the order the dropdown's secondary line reads
+ * best in.
+ */
+const CONTEXT_ORDER = [
+    'neighborhood',
+    'locality',
+    'postcode',
+    'place',
+    'district',
+    'region',
+    'country',
+];
+
+/**
+ * Search Box's context OBJECT → v5's context ARRAY.
+ *
+ * The dotted `id` is the load-bearing part: `Form.jsx` types each entry by
+ * `entry.id.split('.')[0]`, so the type has to be the prefix. Mapbox's own
+ * ids are opaque urns with no dot, so they go after ours; when an entry has
+ * no id at all the index keeps the React keys unique.
+ */
+const adaptContext = (context) => {
+    if (!context || typeof context !== 'object') {
+        return [];
+    }
+
+    const entries = [];
+
+    CONTEXT_ORDER.forEach((type) => {
+        const entry = context[type];
+        const name = text(entry?.name);
+
+        if (!name) {
+            return;
+        }
+
+        const adapted = {
+            id: `${type}.${text(entry.id) || entries.length}`,
+            text: name,
+        };
+
+        if (type === 'region') {
+            // v5 gave ISO 3166-2 ("AU-WA"); `Form.jsx` takes the last segment
+            // as the state's initials, so either of Mapbox's two region codes
+            // survives that split intact.
+            const shortCode =
+                text(entry.region_code_full) || text(entry.region_code);
+
+            if (shortCode) {
+                adapted.short_code = shortCode;
+            }
+        }
+
+        if (type === 'country') {
+            // v5 wrote country short codes lowercase.
+            const shortCode = text(entry.country_code);
+
+            if (shortCode) {
+                adapted.short_code = shortCode.toLowerCase();
+            }
+        }
+
+        if (text(entry.wikidata_id)) {
+            adapted.wikidata = text(entry.wikidata_id);
+        }
+
+        entries.push(adapted);
+    });
+
+    // AUSTRALIAN POIs OFTEN ARRIVE WITH NO `region` AT ALL — Epiq in Perth
+    // came back with country/postcode/place/address and nothing naming the
+    // state, which left the form's required State dropdown unfilled (Form.jsx
+    // resolves `state_id` by matching the region's name or initials, so no
+    // region means no match). Australian postcodes map to states
+    // deterministically, so when the country says AU and a postcode is
+    // present, the state is synthesised from it rather than left blank.
+    // AU-only on purpose: no other country's postcodes carry this guarantee.
+    const hasRegion = entries.some((entry) => entry.id.startsWith('region.'));
+    const isAu =
+        text(context.country?.country_code).toUpperCase() === 'AU';
+    const postcodeName = text(context.postcode?.name);
+
+    if (!hasRegion && isAu && postcodeName) {
+        const state = auStateFromPostcode(postcodeName);
+
+        if (state) {
+            const countryIndex = entries.findIndex((entry) =>
+                entry.id.startsWith('country.')
+            );
+            const synthesised = {
+                id: `region.postcode-derived`,
+                text: state.name,
+                short_code: `AU-${state.code}`,
+            };
+
+            // In CONTEXT_ORDER's slot: just before country.
+            if (countryIndex === -1) {
+                entries.push(synthesised);
+            } else {
+                entries.splice(countryIndex, 0, synthesised);
+            }
+        }
+    }
+
+    return entries;
+};
+
+/**
+ * The state an Australian postcode belongs to, or null off the map.
+ *
+ * The ranges are stable public knowledge (Australia Post's allocations,
+ * including the x000/x800 PO-box bands), and the point of hardcoding them is
+ * that they need no network call at pick time. `9/16 St Georges Terrace,
+ * Perth 6000` is Western Australia whether or not Mapbox says so.
+ */
+const auStateFromPostcode = (postcode) => {
+    const value = Number.parseInt(String(postcode).trim(), 10);
+
+    if (!Number.isFinite(value)) {
+        return null;
+    }
+
+    const inAny = (ranges) =>
+        ranges.some(([lo, hi]) => value >= lo && value <= hi);
+
+    if (inAny([[2600, 2618], [2900, 2920], [200, 299]])) {
+        return { code: 'ACT', name: 'Australian Capital Territory' };
+    }
+
+    if (inAny([[1000, 2599], [2619, 2899], [2921, 2999]])) {
+        return { code: 'NSW', name: 'New South Wales' };
+    }
+
+    if (inAny([[800, 999]])) {
+        return { code: 'NT', name: 'Northern Territory' };
+    }
+
+    if (inAny([[4000, 4999], [9000, 9999]])) {
+        return { code: 'QLD', name: 'Queensland' };
+    }
+
+    if (inAny([[5000, 5999]])) {
+        return { code: 'SA', name: 'South Australia' };
+    }
+
+    if (inAny([[7000, 7999]])) {
+        return { code: 'TAS', name: 'Tasmania' };
+    }
+
+    if (inAny([[3000, 3999], [8000, 8999]])) {
+        return { code: 'VIC', name: 'Victoria' };
+    }
+
+    if (inAny([[6000, 6999]])) {
+        return { code: 'WA', name: 'Western Australia' };
+    }
+
+    return null;
+};
+
+/* --------------------------------------------------------------- adapter */
+
+/**
+ * One Search Box record → one Geocoding v5 feature.
+ *
+ * Takes either a retrieve feature's `properties` (with its geometry folded in
+ * by `featureFromRetrieve`) or a raw suggestion — the two carry the same
+ * fields apart from coordinates, which is exactly what makes a suggestion a
+ * usable fallback when a retrieve fails.
+ *
+ * FIELD BY FIELD, and who reads each:
+ *
+ * | legacy key      | built from                                   | read by |
+ * | --------------- | -------------------------------------------- | ------- |
+ * | `id`            | `mapbox_id`                                  | the dropdown's React key |
+ * | `place_name`    | `full_address`, else `name` + `place_formatted` | `Autocomplete` standalone display value |
+ * | `text`          | the street NAME (or the POI name when there is no street) | `Form.autocompleteSelect` → `address1` |
+ * | `address`       | the street NUMBER                            | `Form.autocompleteSelect` → `address1` |
+ * | `context[]`     | the `context` object, typed by dotted id     | `Form.autocompleteSelect` → suburb, postcode, state, `state_id`, country; the dropdown's secondary line |
+ * | `center`        | `[longitude, latitude]`                      | nothing today — v5 parity for consumers that map a pick |
+ * | `geometry`      | the retrieve's Point                         | as above |
+ * | `place_type[]`  | `[feature_type]`                             | as above |
+ * | `properties`    | passed through, with `address` as the street line | v5 POI parity |
+ *
+ * ONE DELIBERATE DIFFERENCE FROM v5. For a POI, v5 put the business name in
+ * `text` — so picking one filed "Epiq" as the street line. Here the street
+ * parts go in `address`/`text` and the name goes in `place_name` and the
+ * dropdown row, so picking a business fills the address field with its
+ * ADDRESS. That was academic under v5, whose POI results never matched
+ * anything anyway; it is the point of the upgrade. A POI Mapbox has no street
+ * for still falls back to the name, which is v5's behaviour exactly.
+ */
+export const adaptToLegacyFeature = (source) => {
+    if (!source || typeof source !== 'object') {
+        return null;
+    }
+
+    const featureType = text(source.feature_type);
+    const name = text(source.name_preferred) || text(source.name);
+    const context = source.context && typeof source.context === 'object'
+        ? source.context
+        : {};
+
+    // The street line, best-cased copy first: `context.address.name` is
+    // "16 St Georges Terrace" where `context.street.name` is "st georges
+    // terrace". An address feature with no context at all still has its line
+    // sitting in `name`.
+    const line =
+        text(context.address?.name) ||
+        text(source.address) ||
+        (featureType === 'address' ? name : '');
+
+    const split = splitStreetLine(line);
+    let number = text(context.address?.address_number) || split.number;
+
+    let street = '';
+
+    if (line) {
+        if (number && line.toLowerCase().startsWith(number.toLowerCase())) {
+            // Strip the number Mapbox gave us off the front of the line
+            // rather than trusting `street.name`'s casing.
+            street = line.slice(number.length).trim();
+        } else if (number && !line.toLowerCase().includes(number.toLowerCase())) {
+            street = split.street || line;
+        } else {
+            // The number Mapbox reports sits somewhere INSIDE the line, not
+            // at its head — "Ste A, Level 9/16 St Georges Terrace" carries
+            // address_number "9/16". The line is already the complete local
+            // address; re-emitting the number separately made the form print
+            // "9/16 Ste A, Level 9/16 St Geor…". The whole line is the
+            // street text and the number field stays empty — the consumer
+            // concatenates `${address} ${text}`, so empty-plus-line is the
+            // line verbatim.
+            street = line;
+            number = '';
+        }
+    }
+
+    if (!street) {
+        street =
+            text(context.street?.name) ||
+            text(context.address?.street_name) ||
+            // No street anywhere: a POI keeps its name in `text`, which is
+            // what v5 did and what leaves the form with something to show.
+            name;
+    }
+
+    const coordinates = (() => {
+        const geometry = source.geometry;
+
+        if (Array.isArray(geometry?.coordinates) && geometry.coordinates.length === 2) {
+            return [geometry.coordinates[0], geometry.coordinates[1]];
+        }
+
+        const point = source.coordinates;
+
+        if (
+            typeof point?.longitude === 'number' &&
+            typeof point?.latitude === 'number'
+        ) {
+            return [point.longitude, point.latitude];
+        }
+
+        return null;
+    })();
+
+    const placeName = (() => {
+        const full = text(source.full_address);
+        const formatted = text(source.place_formatted);
+
+        if (full) {
+            // A POI's full_address is its street address with no business
+            // name on the front — v5's place_name carried both.
+            if (
+                name &&
+                featureType !== 'address' &&
+                !full.toLowerCase().startsWith(name.toLowerCase())
+            ) {
+                return `${name}, ${full}`;
+            }
+
+            return full;
+        }
+
+        if (name && formatted) {
+            return `${name}, ${formatted}`;
+        }
+
+        return name || formatted || '';
+    })();
+
+    const feature = {
+        id: text(source.mapbox_id) || (name ? `mapbox-${name}` : 'mapbox-result'),
+        type: 'Feature',
+        place_type: featureType ? [featureType] : [],
+        place_name: placeName,
+        text: street,
+        address: number,
+        context: adaptContext(context),
+        properties: {
+            ...(source.properties && typeof source.properties === 'object'
+                ? source.properties
+                : {}),
+            address: line || undefined,
+            mapbox_id: text(source.mapbox_id) || undefined,
+            feature_type: featureType || undefined,
+        },
+    };
+
+    if (coordinates) {
+        feature.center = coordinates;
+        feature.geometry = { type: 'Point', coordinates };
+    }
+
+    return feature;
+};
+
+/**
+ * A retrieve response → one legacy feature. Retrieve answers a GeoJSON
+ * FeatureCollection with a single feature; the record lives in `properties`
+ * and only the coordinates live on the geometry, so they are folded together
+ * before adapting.
+ */
+export const featureFromRetrieve = (payload) => {
+    const data = parsePayload(payload);
+    const feature = Array.isArray(data?.features) ? data.features[0] : null;
+
+    if (!feature) {
+        return null;
+    }
+
+    return adaptToLegacyFeature({
+        ...(feature.properties || {}),
+        geometry: feature.geometry,
+    });
+};
+
+/**
+ * A suggest response → the dropdown's rows.
+ *
+ * Rows are NOT features: a suggestion has no coordinates and is not a pick
+ * yet. It carries the `mapbox_id` the retrieve needs, the two strings the row
+ * renders — `name` over `place_formatted`, so "Epiq" sits above "Perth 6000,
+ * Australia" — and the suggestion itself, kept so a failed retrieve can still
+ * be adapted into a usable feature rather than dropping the user's click.
+ */
+export const adaptSuggestions = (payload) => {
+    const data = parsePayload(payload);
+    const suggestions = Array.isArray(data?.suggestions) ? data.suggestions : [];
+
+    return suggestions.map((suggestion, index) => ({
+        id: text(suggestion?.mapbox_id) || `suggestion-${index}`,
+        mapbox_id: text(suggestion?.mapbox_id),
+        name:
+            text(suggestion?.name_preferred) ||
+            text(suggestion?.name) ||
+            text(suggestion?.full_address),
+        place_formatted:
+            text(suggestion?.place_formatted) || text(suggestion?.full_address),
+        feature_type: text(suggestion?.feature_type),
+        suggestion,
+    }));
+};
+
+/* --------------------------------------------------------------- logging */
+
+const warned = new Set();
+
+/**
+ * `console.warn`, but once per reason per page.
+ *
+ * A dropdown that degrades quietly is the goal; a dropdown that degrades
+ * quietly and fills the console with the same line on every keystroke is not.
+ */
+export const warnOnce = (key, ...args) => {
+    if (warned.has(key)) {
+        return;
+    }
+
+    warned.add(key);
+    console.warn(...args);
+};