@minmaps-dev/mm-web-sdk 1.0.0-rc.31 → 1.0.0-rc.33

package/dist/index.d.ts

@@ -142,6 +142,10 @@ interface Waypoint {
     floorId?: string | number;
     /** Whether this is the primary/default waypoint */
     isPrimary?: boolean;
+    /** CMS zone (department) this waypoint belongs to, if any. The only backend
+     *  link between a location and its department — read at runtime across the
+     *  data provider (see the package CLAUDE.md zone landmine). */
+    zoneId?: string | number;
 }
 /**
  * Amenity enriched with the floor it belongs to
@@ -277,6 +281,10 @@ type ArriveStep = StepBase & {
 interface MapEvent {
     floor?: Floor;
     poi?: POI;
+    /** All POIs co-located at a clicked point (overlapping pins / a shared
+     *  suite). Emitted by `poiSelected`; length ≥ 1, and `poi` mirrors
+     *  `pois[0]` for single-POI consumers. */
+    pois?: POI[];
     coordinates?: [number, number];
     error?: any;
     venue?: any;
@@ -528,6 +536,23 @@ declare class AmenityManager {
 declare class MinuteMaps {
     private config;
     private map;
+    /**
+     * Generation token for `init()`. Bumped by every `init()` and by `destroy()`,
+     * so an init suspended on a network await can tell it has been superseded and
+     * bail instead of creating a map nobody holds a reference to.
+     *
+     * This is what makes `destroy()` safe *during* init: `destroy()` only removes
+     * `this.map`, which is still null until step 3, so a teardown that lands
+     * mid-fetch has nothing to clean up — and without this token the init would
+     * resume and build a fully live orphan (WebGL context, render loop, map-level
+     * listeners, YAH pulse) that can never be reached to shut down. React
+     * StrictMode's mount → unmount → mount does exactly this on every dev load.
+     *
+     * A counter, not a sticky `destroyed` flag: `destroy()` → `init()` re-init is
+     * a supported lifecycle (see the manager-class note in CLAUDE.md), so the
+     * instance has to stay usable after teardown.
+     */
+    private initGeneration;
     private data;
     private wayfindingProvider;
     private events;
@@ -549,7 +574,47 @@ declare class MinuteMaps {
     private amenityManager;
     private wayfinding;
     private highlightManager;
+    private selectionManager;
+    /** Captured unit paint values to restore when the selection clears, or
+     *  `null` when no room is currently focused. See `UNIT_DIM_TARGETS`. */
+    private unitDimRestore;
+    /** Captured destination-layer filters to restore when the selection clears,
+     *  or `null` when no destination focus is active. See `setDestinationFocus`. */
+    private destFocusRestore;
+    /** The allow-list currently narrowing the destination layers, or `null` when
+     *  no focus is active. Kept alongside `destFocusRestore` (which holds the
+     *  *previous* filters, not the ids) so `setTheme` can re-apply the same focus
+     *  to the new style's layers after a swap discards the old ones. */
+    private destFocusIds;
     private youAreHerePulse;
+    /** Theme layers whose features represent a tappable destination/amenity.
+     *  A click hit-tests these (see `SelectionManager`) → `poiSelected`. The
+     *  "You are here" anchor and the transient highlight layers are excluded;
+     *  a POI drawn across the circle/label/icon layers is de-duped downstream
+     *  in `resolveClickedPOIs`. */
+    private static readonly CLICKABLE_POI_LAYERS;
+    /** Room-body layers that are also tappable: a click on a `Units` polygon
+     *  resolves to the destination pin inside it (see `resolvePOIsFromFeatures`).
+     *  Queried alongside the pin layers so tapping the room or its dot behaves
+     *  identically. Kept separate from the pin list because these carry no POI
+     *  identity of their own — they resolve spatially. */
+    private static readonly CLICKABLE_UNIT_LAYERS;
+    /** While a room is selected, the other units are recolored to a flat, muted
+     *  gray so the raised, full-strength highlight block reads as the focus. We
+     *  recolor rather than lower opacity on purpose: translucent extrusions blend
+     *  through their neighbours and look murky. The blocks stay fully opaque (and
+     *  keep their vertical-gradient shading, so they still read as rooms) — just
+     *  colorless. The selected room's own base grays too, but its highlight cap
+     *  sits opaque and taller on top, so it still stands out. The original paint
+     *  value (the data-driven color expression) is captured at mute time and put
+     *  back on `clearHighlight`, so department tinting returns intact. */
+    private static readonly UNIT_DIM_TARGETS;
+    /** Destination marker layers hidden down to just the selected destination
+     *  while a room is focused, so the map declutters to the one place in view.
+     *  Amenity/connector layers (`poiType: 'amenity'`), the "you are here" anchor,
+     *  and room name labels (`map-labels`) are deliberately absent — they stay
+     *  visible as wayfinding reference. Restored on `clearHighlight`. */
+    private static readonly DESTINATION_FOCUS_LAYERS;
     /** Categorical POI layers in the bundled theme that `setPOIFilter`
      *  toggles. Layers absent from this list — `poi-you-are-here-*`, the
      *  `poi-accessibility-icons` badge, and the `poi-highlight-*` layers —
@@ -559,6 +624,25 @@ declare class MinuteMaps {
     private poiVisibleTypes;
     constructor(config: SDKConfig);
     init(): Promise<void>;
+    /**
+     * Supply an image the current style has requested but doesn't have.
+     *
+     * Every imperatively-registered image is served from here, because a theme
+     * swap (`setStyle` with `diff: false`) drops all of them and the code that
+     * registered them doesn't run again:
+     *
+     * - the **route arrow** isn't in the sprite sheet at all — it's canvas-drawn
+     *   on demand (this was already the case);
+     * - **amenity / destination icons** come back from `iconCache`. Their
+     *   registrars run only during `init`, so before this they went missing on
+     *   the first theme swap and never returned — the map kept the dots and
+     *   labels but lost every badge and logo.
+     *
+     * Serving lazily (rather than re-registering everything on `style.load`)
+     * means only the ids the new style actually asks for are restored, with no
+     * refetch and no re-compositing.
+     */
+    private serveMissingStyleImage;
     on(event: string, cb: (e: MapEvent) => void): void;
     off(event: string, cb?: (e: MapEvent) => void): void;
     addControl(control: IControl, position?: ControlPosition): void;
@@ -642,6 +726,30 @@ declare class MinuteMaps {
     getDefaultFloor(): Floor | null;
     getDestinations(floor?: Floor): Destination[];
     getZones(): Zone[];
+    /** The department (zone) a POI belongs to, resolved via its waypoint's
+     *  `zoneId` — the only backend link between a location and a department
+     *  (see the zone landmine in the package CLAUDE.md). `null` when the POI
+     *  has no waypoint, no zone, or the zone id is unknown. */
+    getZoneForPOI(poi: POI): Zone | null;
+    /** Human-readable detail fields for a POI info popover. Only surfaces
+     *  fields that exist on the current data — `category`, `floorName`,
+     *  `zoneName`, `keywords`, and `description` are each omitted when absent.
+     *  Keeps the display-field derivation (incl. the zone lookup) in the SDK
+     *  so consumers stay thin. */
+    getPOIDetails(poi: POI): {
+        name: string;
+        type: 'amenity' | 'destination' | 'kiosk';
+        category?: string;
+        floorName?: string;
+        zoneName?: string;
+        zoneDescription?: string;
+        keywords?: string[];
+        description?: string;
+    };
+    /** Resolve the source Destination/Amenity record backing a rendered POI,
+     *  for detail fields (category, localized description) that don't live on
+     *  the built POI object. */
+    private getSourceEntity;
     getPolygonLayers(): any[];
     getFloorMapTemplate3d(floorId: string | number): any[];
     getAllPOIs(floor?: Floor): POI[];
@@ -777,8 +885,52 @@ declare class MinuteMaps {
      * it lives on another one. Pass a POI / amenity / destination id.
      */
     highlightPOI(id: string | number): Promise<void>;
-    /** Remove the POI highlight set by `highlightPOI`. */
+    /** Remove the POI highlight set by `highlightPOI`, un-dim the other units,
+     *  and bring back the destination markers hidden by a room selection. */
     clearHighlight(): void;
+    /** Map a click's raw feature hits to the full, de-duplicated POIs at that
+     *  point (see `resolvePOIsFromFeatures`). Injected into `SelectionManager`.
+     *  `getAllPOIs()` is the current floor's rendered POIs — the only clickable
+     *  ones — and carries each POI's `waypoint`, needed for directions. */
+    private resolveClickedPOIs;
+    /** Emit `poiSelected` for the co-located POIs at a clicked point. Focuses the
+     *  selection in place (no recenter — the user already sees where they
+     *  tapped): rings the tapped dot and, when the tap landed in a room, raises
+     *  that room as a highlighted block so the eye goes to the selected unit.
+     *  `clearHighlight` removes both. `poi` mirrors `pois[0]` for single-POI
+     *  consumers. */
+    private emitPoiSelected;
+    /**
+     * Build the room-highlight payload for a selection. The colour comes from the
+     * *clicked* feature (the rendered truth), but the geometry comes from the
+     * floor's full source polygon — the clicked feature is from
+     * `queryRenderedFeatures`, whose geometry is clipped to on-screen tiles, so
+     * highlighting it directly would leave any off-screen part of the room grey
+     * (its base extrusion is muted). Falls back to the clipped geometry if the
+     * full polygon can't be found. Returns `null` for a pin with no room.
+     */
+    private unitHighlightFor;
+    /** The full, unclipped `Units` polygon on the current floor that contains
+     *  `coord`, straight from the floor source (not the tile-clipped render). */
+    private fullUnitPolygonAt;
+    /**
+     * Hide every destination marker except the given ids (pass `null` to
+     * restore all). Narrows each destination layer's own filter with an id
+     * allow-list; amenity/connector/"you are here" layers are untouched, so they
+     * stay on the map as reference. Captures the original filters once and puts
+     * them back verbatim, so the layers' base rules (poiType, showLabel, iconId)
+     * survive.
+     */
+    private setDestinationFocus;
+    /** Gentle pan so the selection sits in the centre of the map area MapLibre
+     *  frames within `boundsPadding` (which the consumer sets to reserve for its
+     *  bottom-docked chrome / info card). A straight `easeTo`, current zoom kept,
+     *  so it reads as a nudge, not a recenter. */
+    private easeToSelection;
+    /** Dim every unit's paint (or restore it) so a selected room reads as the
+     *  focus. Idempotent: capturing only happens on the first activate, and the
+     *  captured originals are put back verbatim on deactivate. */
+    private setUnitFocusDim;
     /**
      * Show only the named POI categories on the map. Pass `['amenity']` to
      * emphasize amenities (e.g. while an Amenities drawer is open) — destination