efficient-shell 4.126.4 → 4.131.0

package/dist/map/index.d.ts

@@ -0,0 +1,329 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { QueryKey } from '@tanstack/react-query';
+import * as _tanstack_query_core from '@tanstack/query-core';
+import * as maplibre_gl from 'maplibre-gl';
+
+/**
+ * Records on a map. One pin per placed record: a button carrying a glyph (or
+ * an icon) and, for a screen reader, the record's name in words, never the
+ * colour alone. The one map every EFFICIENT portal draws — the admin portal's
+ * Customer / Supplier maps and Trip Planner, the dealer portal's Address Book.
+ *
+ * Ported from Foyerboard's leads map, which draws its map the way
+ * whoson.today does: MapLibre over OpenFreeMap's vector tiles — free,
+ * keyless, OpenStreetMap data (the same data the backend geocodes against), a
+ * light and a dark style. The tiles load straight from tiles.openfreemap.org,
+ * so a host with a Content-Security-Policy must allow that origin.
+ *
+ * MapLibre is fetched only once the map mounts (`loadMapLibre`, which also
+ * says how the host serves its worker), and the map is made once per mount;
+ * pins, the selection, the theme and the fitted view are separate effects so
+ * a re-render never rebuilds the map.
+ *
+ * It also draws ROUTES — the Trip Planner's days, each a line under the pins
+ * (solid along the streets, dashed where it is only a straight-line estimate),
+ * again after a theme change, which replaces the style and every layer on it.
+ */
+interface MapPin {
+    key: string;
+    label: string;
+    lat: number;
+    lng: number;
+    /** One or two characters drawn on the pin (when it has no `icon`). */
+    glyph: string;
+    /** An icon drawn instead of the glyph: SVG path data, 24 × 24, stroked —
+     *  the admin Trip Planner's stage icons. */
+    icon?: readonly string[];
+    /** A small tag on the pin's corner — a visit's place in the day's order. */
+    badge?: string;
+    /** Tone classes for the badge; white by default. */
+    badgeTone?: string;
+    /** Tone classes (background + text) — see `pinTone`. */
+    tone: string;
+    /** The pin marks an area, not the address: drawn dashed and faded. */
+    approximate?: boolean;
+    /** Shown for context only (another day's visits on the Trip Planner): drawn faint. */
+    faded?: boolean;
+}
+/** A line on the map: a day's road, or its straight-line estimate. */
+interface MapRoute {
+    key: string;
+    /** [lng, lat] pairs, in order. */
+    coordinates: [number, number][];
+    /** Straight lines between the points, not the road: drawn dashed. */
+    estimate: boolean;
+    /** Context only (another day): drawn faint. */
+    faded?: boolean;
+}
+declare function EntityMap({ pins, selectedKey, focus, onSelect, ariaLabel, className, children, routes, fitTo, attribution, }: {
+    pins: MapPin[];
+    selectedKey: string | null;
+    /** Bump `n` to fly to a pin (the list's "show on map"). */
+    focus: {
+        key: string;
+        n: number;
+    } | null;
+    onSelect: (key: string) => void;
+    ariaLabel: string;
+    className?: string;
+    /** Drawn over the map: the selected record's card, the legend. */
+    children?: ReactNode;
+    /** Lines under the pins — the Trip Planner's day routes. */
+    routes?: MapRoute[];
+    /** Fit the view to these pins only (the day being planned); all pins when unset. */
+    fitTo?: string[] | null;
+    /** Extra credit line for the attribution (HTML), e.g. the router's. Read once, at mount. */
+    attribution?: string;
+}): react_jsx_runtime.JSX.Element;
+
+/**
+ * Map points — the wire shape every EFFICIENT map endpoint answers with, and
+ * the pure logic over it: what a point says about itself, how its pin looks,
+ * and the counts over a list of them. Kept free of React and MapLibre so it is
+ * testable without WebGL.
+ *
+ * The shape is efficient-backend's `logistics.serializers.MapPointsSerializer`
+ * (the `address-geocoding` capability): the admin portal's Customer / Supplier
+ * maps and Trip Planner, and the dealer portal's Address Book. Every record
+ * comes back, pinned or not — a point off the map has null `lat` / `lng` and a
+ * `placement` saying why, so a list beside the map can explain it instead of
+ * silently dropping the row. The backend never makes a request wait on the
+ * geocoder: an address it has not seen is `pending`, and the caller asks again
+ * while `pending > 0` (`mapPointsRefetchInterval`).
+ *
+ * Moved here from the admin portal (`src/components/map/mapPoints.ts`) so the
+ * dealer portal draws the same map rather than a second one.
+ */
+/**
+ * located      — the geocoder matched the street
+ * approximate  — only the suburb / postcode / city matched; the pin marks the area
+ * pending      — still being looked up (poll again)
+ * not_found    — the geocoder found nothing for this address
+ * failed       — the map service could not answer; retried later
+ * no_address   — too little to look up: no city or postcode (and none written into the street)
+ */
+type MapPlacement = 'located' | 'approximate' | 'pending' | 'not_found' | 'failed' | 'no_address';
+/**
+ * One record on (or off) a map. `kind` is the record type the endpoint pinned
+ * (`customer`, `delivery_location`, `supplier`, `warehouse`, the Trip Planner's
+ * `office` / `trip_place` / `trip_stop` …); a portal narrows it to the kinds it
+ * reads with the type parameter.
+ */
+interface MapPoint<K extends string = string> {
+    kind: K;
+    id: string;
+    label: string;
+    /** CID / MID where the record has one. */
+    code: string;
+    /** What the pin is coloured by: the customer type, the supplier type, or the kind. */
+    category: string;
+    /** The address as one line. */
+    address: string;
+    placement: MapPlacement;
+    lat: number | null;
+    lng: number | null;
+    /** What the geocoder matched, when placed. */
+    matched: string;
+}
+interface MapPoints<P extends MapPoint = MapPoint> {
+    points: P[];
+    /** Points still being looked up — poll again while this is above zero. */
+    pending: number;
+}
+/** How often to ask again while addresses are still being located. */
+declare const PENDING_POLL_MS = 3000;
+/** A react-query `refetchInterval` for a map endpoint: every few seconds while
+ *  the backend is still locating addresses, not at all once every point is settled. */
+declare const mapPointsRefetchInterval: (data: Pick<MapPoints, "pending"> | undefined) => number | false;
+/** A point's identity across kinds — a customer and one of its delivery
+ *  locations are different pins even if two ids ever collided. */
+declare const pointKey: (p: Pick<MapPoint, "kind" | "id">) => string;
+/** On the map = placed by the geocoder AND carrying coordinates. */
+declare const isOnMap: <P extends MapPoint>(p: P) => p is P & {
+    lat: number;
+    lng: number;
+};
+/** Why a point is not (exactly) where its address is — null when it is. */
+declare function placementNote(placement: MapPlacement): string | null;
+/** A pin colour and the legend's word for it. */
+interface MapCategory {
+    label: string;
+    /** Tone classes (background + text) for the pin and its legend swatch. */
+    tone: string;
+}
+/**
+ * Pin colours by category. Customers follow the admin Customers list's Type
+ * badge families (importer, dealer purple, retail green); a record's
+ * secondary locations (delivery locations, warehouses) are amber.
+ *
+ * Importer and supplier are SKY, not blue: this package's themes remap
+ * `bg-blue-600` to the theme's accent (themes.css), so in the green theme
+ * importer pins came out the same green as retail. None of the other families
+ * here is remapped — a categorical colour must not follow the accent the way
+ * a button does.
+ *
+ * A portal that names a category differently passes its own map with the same
+ * tones (the dealer's own head office is its "Billing address", not "Dealer").
+ */
+declare const MAP_CATEGORIES: Readonly<Record<string, MapCategory>>;
+/** Suppliers colour by the kind rather than their free-text type (Factory,
+ *  Shipping Forwarder…), which has no fixed palette to map onto. */
+declare function pinCategory(p: Pick<MapPoint, 'kind' | 'category'>): string;
+declare const categoryTone: (category: string, categories?: Readonly<Record<string, MapCategory>>) => string;
+declare const categoryLabel: (category: string, categories?: Readonly<Record<string, MapCategory>>) => string;
+declare const pinTone: (p: Pick<MapPoint, "kind" | "category">, categories?: Readonly<Record<string, MapCategory>>) => string;
+/**
+ * The character on a pin. A profile map numbers its extra locations (1, 2, 3 —
+ * the same numbers the list shows) and marks the head office with its
+ * category's initial; a list-wide map shows each record's category initial.
+ */
+declare function pinGlyph(p: MapPoint, number: number | null, categories?: Readonly<Record<string, MapCategory>>): string;
+/** The kinds a profile map numbers: a record's secondary locations. */
+declare const SECONDARY_KINDS: readonly string[];
+/**
+ * The numbers a profile map gives its secondary locations, in list order; the
+ * record itself gets none. An unplaced location keeps its number, so the list
+ * and the pins never renumber as addresses resolve.
+ */
+declare function locationNumbers(points: MapPoint[], kinds?: readonly string[]): Map<string, number>;
+interface MapSummary {
+    onMap: number;
+    approximate: number;
+    pending: number;
+    off: number;
+}
+declare function summarize(points: MapPoint[]): MapSummary;
+/** "12 on the map · 2 approximate · 3 not on the map" — the list header. */
+declare function summaryText(s: MapSummary): string;
+/** The categories present among the placed points, in a stable order — the
+ *  legend. Categories outside the palette follow, in the order first seen. */
+declare function legendCategories(points: MapPoint[]): string[];
+/**
+ * The records a compact map can't pin, each with its reason, for the notes
+ * drawn over the map (a map with no list beside it). Pending points are left
+ * out — they are counted as "Locating…" instead.
+ */
+declare function offMapNotes(points: MapPoint[], numbers?: ReadonlyMap<string, number>): {
+    key: string;
+    text: string;
+}[];
+
+/**
+ * A record's Locations map — compact, with no list beside it, because the
+ * page it sits on already lists the locations. The admin portal puts it on the
+ * customer / supplier Details tab beside the score (a customer's head office
+ * and delivery locations, a supplier's address and warehouses); the dealer
+ * portal puts it on the Address Book (the billing address and the delivery
+ * addresses). What a list would say lives over the map: the legend,
+ * "Locating…" while addresses are looked up, and a note for each record that
+ * has no pin and why. Clicking a pin shows its card.
+ *
+ * `refreshSignal` changes when the records it pins change elsewhere on the
+ * page (a delivery location added or edited, the address edited), and the
+ * points are asked again; `staleTime: 0` does the same whenever it remounts.
+ *
+ * Moved from the admin portal's `ProfileLocationsMap`.
+ */
+declare function LocationsMap({ queryKey, queryFn, refreshSignal, onOpen, ariaLabel, title, palette, numbers: givenNumbers, className, mapClassName, }: {
+    queryKey: QueryKey;
+    queryFn: () => Promise<MapPoints>;
+    refreshSignal?: unknown;
+    /** Open a point's own page or window; null for points that have none. */
+    onOpen?: (point: MapPoint) => ((() => void) | null);
+    ariaLabel: string;
+    /** The heading over the map. */
+    title?: string;
+    /** How the portal names and colours each category (the legend, the card, the head-office initial). */
+    palette?: Readonly<Record<string, MapCategory>>;
+    /** The number each pin shows, by `pointKey` — the numbers the page's own list
+     *  shows. Unset: the secondary locations numbered in the endpoint's order. */
+    numbers?: ReadonlyMap<string, number>;
+    className?: string;
+    /** Sizing for the map box (it grows to fill the section by default). */
+    mapClassName?: string;
+}): react_jsx_runtime.JSX.Element;
+
+/**
+ * What sits over an `EntityMap` — the legend and the chosen record's card.
+ * Both take the portal's category map (`MAP_CATEGORIES` unless it names a
+ * category its own way), so the legend's words and the card's match the pins.
+ */
+/** Which colour means what; drawn only when the map shows more than one.
+ *  `floating` pins it to the map's top-left corner; off, the caller places it
+ *  (a compact map stacks its notes under it). */
+declare function MapLegend({ categories, palette, floating }: {
+    categories: string[];
+    palette?: Readonly<Record<string, MapCategory>>;
+    floating?: boolean;
+}): react_jsx_runtime.JSX.Element | null;
+/** The chosen record's card, over the map's bottom edge. */
+declare function SelectedCard({ point, number, onOpen, onClose, palette }: {
+    point: MapPoint;
+    number: number | null;
+    /** Open the record's own page or window; null when it has none. */
+    onOpen: (() => void) | null;
+    onClose: () => void;
+    palette?: Readonly<Record<string, MapCategory>>;
+}): react_jsx_runtime.JSX.Element;
+
+/**
+ * A map endpoint's points, asked again every few seconds while the backend is
+ * still locating addresses (`pending > 0`) and not at all once every point is
+ * settled. The backend never makes the request wait on the geocoder, so a
+ * first visit shows the list at once and the pins arrive as they are found.
+ */
+declare function useMapPoints<T extends MapPoints>(queryKey: QueryKey, queryFn: () => Promise<T>, { staleTime }?: {
+    staleTime?: number;
+}): _tanstack_react_query.UseQueryResult<_tanstack_query_core.NoInfer<T>, Error>;
+
+/**
+ * Keep the map's credit line ("OpenFreeMap © OpenMapTiles Data from
+ * OpenStreetMap") folded behind its (i) button until someone clicks it —
+ * expanded, it runs across the bottom of a compact map.
+ *
+ * MapLibre's compact attribution control unfolds ITSELF once: the first time
+ * the attribution text arrives with the style's sources it adds
+ * `maplibregl-compact` together with `maplibregl-compact-show`, which can be
+ * well after the map's `load` (folding on `load` or `idle` lost that race). So
+ * this watches the control and removes `maplibregl-compact-show` the first
+ * time it appears — the same class MapLibre itself drops when the map is
+ * dragged — then stops watching. From then on the (i) toggles the text as
+ * usual: MapLibre only unfolds automatically while the control is not yet
+ * compact, and after this it always is.
+ *
+ * Returns the cleanup that disconnects the watcher if the map unmounts first.
+ */
+declare const COMPACT_SHOW = "maplibregl-compact-show";
+declare function foldAttributionOnce(control: Element | null): () => void;
+
+/**
+ * MapLibre, fetched only when a map is on screen: `EntityMap` calls
+ * `loadMapLibre()` as it mounts, so its ~1 MB (and its stylesheet) never rides
+ * in a page that shows no map. `maplibre-gl` is an OPTIONAL peer of this
+ * package, installed by the portals that draw maps, and it must stay behind
+ * this dynamic import — `scripts/verify-dist.mjs` fails a build that reaches
+ * it statically.
+ *
+ * The worker. MapLibre 6 starts a MODULE worker from a URL it is given, and
+ * that worker (`maplibre-gl-worker.mjs`) imports `./maplibre-gl-shared.mjs`
+ * beside it — so the host serves both files, unhashed, next to each other,
+ * under the installed version:
+ *
+ *   /maplibre-gl/<version>/maplibre-gl-worker.mjs
+ *   /maplibre-gl/<version>/maplibre-gl-shared.mjs
+ *
+ * The versioned path means an upgrade can never pair a cached old worker with
+ * a new main thread. In the Next.js portals that is a static route handler,
+ * `app/maplibre-gl/[version]/[file]/route.ts`, copying the two files verbatim
+ * from `node_modules/maplibre-gl/dist` at export time.
+ */
+type MapLibre = typeof maplibre_gl;
+declare const MAPLIBRE_WORKER_FILE = "maplibre-gl-worker.mjs";
+/** Where the host serves the worker for a given MapLibre version. */
+declare const mapLibreWorkerUrl: (version: string) => string;
+/** MapLibre, loaded once per page; a failed load is retried by the next map. */
+declare function loadMapLibre(): Promise<MapLibre>;
+
+export { COMPACT_SHOW, EntityMap, LocationsMap, MAPLIBRE_WORKER_FILE, MAP_CATEGORIES, type MapCategory, MapLegend, type MapPin, type MapPlacement, type MapPoint, type MapPoints, type MapRoute, type MapSummary, PENDING_POLL_MS, SECONDARY_KINDS, SelectedCard, categoryLabel, categoryTone, foldAttributionOnce, isOnMap, legendCategories, loadMapLibre, locationNumbers, mapLibreWorkerUrl, mapPointsRefetchInterval, offMapNotes, pinCategory, pinGlyph, pinTone, placementNote, pointKey, summarize, summaryText, useMapPoints };