@minmaps-dev/mm-web-sdk 1.0.0-rc.35 → 1.0.0-rc.37

package/dist/index.d.ts

@@ -80,6 +80,12 @@ interface POI {
     /** For kiosk POIs only: compass heading the device physically faces, in
      *  degrees clockwise from north. Sourced from JACS `Device.heading`. */
     heading?: number | null;
+    /** Per-instance name for this specific placement of an amenity (e.g.
+     *  "Parking Lot A" for a "Parking" amenity), resolved from the waypoint's
+     *  `amenityAssociations`. Distinct from `name`, which is the amenity's
+     *  type-level name shared by every instance — see `Amenity.name`. Amenities
+     *  only, and only set when JACS actually returned an instance name. */
+    instanceName?: string;
 }
 /**
  * Amenity - a specific type of POI (facilities, services)
@@ -185,6 +191,15 @@ interface Waypoint {
      *  link between a location and its department — read at runtime across the
      *  data provider (see the package CLAUDE.md zone landmine). */
     zoneId?: string | number;
+    /** Per-instance names JACS attaches to this waypoint's amenities (e.g. a
+     *  "Parking" amenity placed twice as "Parking Lot A" / "Parking Lot B").
+     *  `id` matches an `Amenity.id`, not this waypoint — a waypoint can carry
+     *  more than one amenity, so a consumer must find the entry for the
+     *  specific amenity it's rendering rather than assuming index 0. */
+    amenityAssociations?: Array<{
+        id: string | number;
+        name: string;
+    }>;
 }
 /**
  * Amenity enriched with the floor it belongs to
@@ -381,6 +396,11 @@ type AmenityBadgeStyle = {
     ringColor?: string;
     /** Ring width in logical px. Default `2`. */
     ringWidth?: number;
+    /** Extra inset between the icon and the badge's inner edge, in logical px
+     *  (applied on all sides). Default `0` — the icon fills ~85% of the disc
+     *  as before. Raise this if an icon's own artwork reaches close to its
+     *  viewBox edges and ends up touching the ring. */
+    padding?: number;
 };
 interface SDKOptions {
     debug?: boolean;
@@ -437,18 +457,43 @@ interface SDKOptions {
     customSprite?: string;
     minIndoorZoom?: number;
     /**
-     * Interior unit-wall thickness in feet (default 1). Each wall is built by
-     * insetting a ring into each unit by `wallThickness / 2`, so adjacent units
-     * share a wall (their rings abut at the common edge). Floored at 0.5 — a
-     * thinner value collapses the negative buffer and drops the wall.
+     * How far, in **metres** (default `0.3`, ≈1 ft), extruded interior polygons
+     * (restrooms, back-of-house, obstacles, connectors) are inset so their edges
+     * don't z-fight the neighbouring room block. A polygon too thin to survive
+     * the inset (it would keep under half its area, e.g. a ~0.3 m back-of-house
+     * perimeter band) is left at its original size rather than erased. Metres to match the theme's
+     * `fill-extrusion-height` values, which MapLibre defines in metres — unlike
+     * the distances shown to visitors, which are in feet. Was feet before this
+     * option changed units; a value of `1` is now ~3.3× thicker.
      */
     wallThickness?: number;
+    /**
+     * How much costlier a candidate on a **different floor** from the kiosk is
+     * treated when choosing the closest instance of an amenity (default `1.5`).
+     * Used by `findClosestByWalkTime`, and so by `navigateFromKioskToClosestAmenity`
+     * and `highlightAmenity`.
+     *
+     * A multiplier on the trip's effort — walk time plus the elevator wait — not
+     * a distance: `1.5` means another floor's instance has to be a third cheaper
+     * to beat one on the kiosk's floor. It is a *preference* for not making the
+     * visitor change floors, layered on top of the physical cost of doing so
+     * (which is already in the effort). `1` turns it off and ranks by effort
+     * alone; a value below `1` is treated as `1`. It only affects which instance
+     * is chosen — never a route.
+     *
+     * For scale: at the Las Vegas VA the nearest other-floor Lactation Pod costs
+     * ~400 ft-equivalent against ~530 for the one on the kiosk's floor, so it
+     * takes a value above ~1.32 to keep the visitor on their floor.
+     */
+    otherFloorPenalty?: number;
     boundsPadding?: BoundsPadding;
     /**
      * Caps how far a visitor can pan/zoom out. By default the SDK derives this
      * from the venue's own bounds, scaled to 3x its width/height around the
      * same center — enough room to pan around the building without drifting
-     * into an empty, un-tiled region. Pass a number to use a different
+     * into an empty, un-tiled region. The default box is never smaller than
+     * ~3.7 km a side, so a small venue isn't forced to zoom in tighter than a
+     * large one. Pass a number to use a different
      * multiplier (e.g. `1.5` for a tighter leash), explicit `[[west, south],
      * [east, north]]` bounds to override entirely, or `false` to disable
      * max-bounds clamping.
@@ -474,6 +519,16 @@ interface SDKOptions {
      * massing/region. `0` locks zoom-out exactly to the opening view.
      */
     minZoomBelowInitialFit?: number;
+    /**
+     * Zoom-out floor expressed as ground scale: the most metres one CSS pixel
+     * may span. The SDK converts it to a `minZoom` at the venue's latitude, so
+     * every venue shows the same amount of surrounding map when fully zoomed
+     * out — a plain zoom number doesn't, because Web Mercator shows less ground
+     * per zoom level the further a venue is from the equator. Takes precedence
+     * over `minZoomBelowInitialFit`. For scale, `1.207` is zoom 15.8 at Orlando
+     * (about 2.3 km x 1.3 km on a 1920x1080 screen).
+     */
+    minZoomMetersPerPixel?: number;
     /**
      * Override the colour the SDK recolours every amenity SVG to before it
      * composites the badge. `none` / `transparent` fills are preserved so
@@ -519,6 +574,22 @@ interface SDKOptions {
      * (matches `informationBadge`'s default green disc).
      */
     informationIconColor?: string;
+    /**
+     * Badge for the end-of-route flag (`poi-route-end-flag`) shown in place of a
+     * destination's dot while a route to it is displayed. Has its own defaults
+     * (green disc, white ring) that don't follow `amenityBadge`. Pass an object
+     * to tune the disc / ring, or `false` for the bare flag glyph with no badge.
+     * When `amenityBadge` is `false`, the flag is badge-less too unless this is
+     * set explicitly. Under the high-contrast theme the disc colour is forced to
+     * the high-contrast amenity yellow, like the amenity and connector badges.
+     */
+    routeEndBadge?: AmenityBadgeStyle | false;
+    /**
+     * Flag glyph colour on the end-of-route badge. Default white (contrasts the
+     * default green disc); doesn't follow `amenityIconColor`. Ignored under the
+     * high-contrast theme, which forces its own glyph colour.
+     */
+    routeEndIconColor?: string;
     styleMode?: 'venueStyleUrl' | 'sdkTemplate';
     templateOverrideMode?: 'colorsOnly' | 'colorsAndConstants' | 'all';
 }
@@ -1044,11 +1115,15 @@ declare class MinuteMaps {
     private debugGlobalKey;
     private defaultCamera;
     /** This venue's opening zoom, captured once after the initial fit resolves.
-     *  Anchors `applyRelativeIconZoomRanges` so icon/label reveal thresholds
-     *  are relative to this venue's own opening view rather than an absolute
-     *  MapLibre zoom — re-applied after every `setTheme()` swap too, since
-     *  `setStyle({ diff: false })` recreates layers from the pristine theme. */
+     *  Anchors the pinned zoom profile's icon/label reveal thresholds (idle
+     *  spotlight, active route) to this venue's own opening view rather than an
+     *  absolute MapLibre zoom, and the roof fill's fade-in. See `zoomViews`. */
     private iconZoomBase;
+    /** Which layers show at which zoom: the Campus / Building / Kiosk views, or
+     *  the pinned profile while the idle spotlight or a route is up. Re-applied
+     *  after every `setTheme()` swap, since `setStyle({ diff: false })`
+     *  recreates layers from the pristine theme. */
+    private zoomViews;
     private viewModes;
     /** Mirror of `config.options.reducedMotion`, mutable via `setReducedMotion`. */
     private reducedMotion;
@@ -1081,6 +1156,14 @@ declare class MinuteMaps {
      *  *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;
+    /** The predicate currently narrowing the POI marker layers to a curated set,
+     *  or `null` when no spotlight is active. See `setPOISpotlight`. Held as the
+     *  predicate, not a resolved id list, so a floor change or locale redraw can
+     *  re-resolve it against the POIs now on screen. */
+    private poiSpotlight;
+    /** Layer filters as they were before the spotlight narrowed them, put back
+     *  verbatim when it releases. `null` when no spotlight filter is applied. */
+    private poiSpotlightRestore;
     /** Coordinates of the current tap/Info selection, or `null` when nothing is
      *  selected. `easeToSelection` reads `getBoundsPadding()` at the moment a
      *  selection is made, which is often *before* the consumer's info card has
@@ -1133,7 +1216,20 @@ declare class MinuteMaps {
      *  `poi-highlight-*` layers — are intentionally unaffected; they're
      *  anchors or transient focus state, not categorical content. */
     private static readonly POI_CATEGORY_LAYERS;
+    /** Marker layers `setPOISpotlight` narrows. Every categorical POI layer
+     *  except `poi-other-amenity-icons`, whose filter the restroom-group manager
+     *  and the zoom-range pass rewrite as the camera moves — a spotlight
+     *  narrowing would be silently overwritten mid-orbit — plus the per-instance
+     *  amenity label, which is a marker in every sense but isn't a category. */
+    private static readonly POI_SPOTLIGHT_LAYERS;
     private poiVisibleTypes;
+    /** Independent show/hide state for destination dots and name labels, set
+     *  by `setDestinationCirclesVisible`/`setDestinationLabelsVisible`. Kept
+     *  separate from `poiVisibleTypes` so the two controls compose instead of
+     *  clobbering each other — `applyPOIFilter` and `applyDestinationDisplay`
+     *  each own one paint/layout axis of the same layers. */
+    private destinationCirclesVisible;
+    private destinationLabelsVisible;
     constructor(config: SDKConfig);
     init(): Promise<void>;
     /**
@@ -1463,8 +1559,14 @@ declare class MinuteMaps {
      * `{ id, mapId? }` shape. Returns `null` when the kiosk isn't anchored,
      * the target waypoint isn't on the graph, or no path resolves.
      *
-     * Walking speed defaults to 1.2 m/s (indoor wayfinding norm). Pass
-     * `walkingSpeedMps` to estimate for accessibility (e.g. 0.9).
+     * Walking speed defaults to 2.953 ft/s (0.9 m/s, average adult walking speed —
+     * PMC2967707). Pass `walkingSpeedFps` to estimate for accessibility (e.g. 2).
+     *
+     * `feet` / `seconds` are the *physical* walk — horizontal legs only, what a
+     * visitor is shown. `effortSeconds` adds the router's charge for each floor
+     * change (the elevator wait) and is what to *rank* candidates by; see
+     * `findClosestByWalkTime`. Pass `avoidStairs` to price the path as a route
+     * with that option would be.
      */
     getWalkTimeFromKiosk(target: number | string | {
         id?: number | string;
@@ -1474,10 +1576,12 @@ declare class MinuteMaps {
             id?: number | string;
         }>;
     }, opts?: {
-        walkingSpeedMps?: number;
+        walkingSpeedFps?: number;
+        avoidStairs?: boolean;
     }): {
-        meters: number;
+        feet: number;
         seconds: number;
+        effortSeconds: number;
         pathNodeCount: number;
     } | null;
     /**
@@ -1562,6 +1666,18 @@ declare class MinuteMaps {
     private writeActiveStepHighlight;
     private clearActiveStepHighlight;
     clearRoute(): void;
+    /**
+     * Put the end-of-route marker on `poi`, or take it down (`null`).
+     *
+     * A destination gets a flag in place of its dot; an amenity instance gets an
+     * enlarged copy of its own icon (`map/routeEnd.ts`). Both are drawn from a
+     * source of their own, so this never touches the POI layers — clearing the
+     * route empties the source and the ordinary dot / icon are what remain.
+     *
+     * The routed restroom is also kept out of restroom grouping while the marker
+     * is up; see `RestroomGroupManager.setExcludedKey`.
+     */
+    private setRouteEnd;
     /**
      * Highlight a single POI on the map — a pulsing ring — and bring it into
      * view. Resolves the POI across all floors, switching the active floor if
@@ -1641,6 +1757,25 @@ declare class MinuteMaps {
      * survive.
      */
     private setDestinationFocus;
+    /**
+     * Select every destination inside a tapped cluster bubble, so a consumer's
+     * multi-place card lists them — the same `poiSelected` a tap on stacked pins
+     * emits.
+     *
+     * Unlike `emitPoiSelected` this raises no room and narrows no markers. A
+     * cluster spans rooms, so there is no one unit to raise or dim around, and
+     * the destination focus would filter out the bubble that was just tapped
+     * (its features carry no `id`) and the members hidden inside it with it.
+     * Any earlier selection is cleared first, so a room left raised by the last
+     * tap doesn't outlive this one. `clearHighlight` afterwards is a harmless
+     * no-op for the consumer to call on dismiss.
+     *
+     * The leaves are read back from the cluster source (`getClusterLeaves`: a
+     * promise on MapLibre v5, a callback on v4 — `peerDependencies` allows both)
+     * and resolved against the floor's POIs, since a source feature only carries
+     * enough identity to look the full POI (with its waypoint) back up.
+     */
+    private selectCluster;
     /** 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,
@@ -1661,7 +1796,69 @@ declare class MinuteMaps {
     setPOIFilter(types: Array<'amenity' | 'destination'>): void;
     /** Restore the default — every POI category renders. */
     clearPOIFilter(): void;
+    /**
+     * Narrow the POI markers to a curated set: only POIs for which `match`
+     * returns true keep their icon and label, every other pin on the categorical
+     * marker layers (destinations, entrances, parking, bus, connectors,
+     * information, and the per-instance amenity names) is filtered out. Built for
+     * an attract loop that wants a few chosen places on screen instead of either
+     * every marker or none.
+     *
+     * `match` runs against the current floor's POIs — the same objects
+     * `getAllPOIs()` returns, `instanceName` and `amenityCategory` included — and
+     * is re-run on every floor change, theme swap and locale redraw, so the
+     * spotlight follows the map rather than the floor it was set on. Kiosk
+     * "You are here" is never touched.
+     *
+     * Two things it deliberately leaves alone:
+     * - `poi-other-amenity-icons` and the restroom badge. Their filters are owned
+     *   by the restroom-group manager and rewritten as the camera moves, so a
+     *   narrowing there would not survive a frame. Hide them with `hideLayers`
+     *   if the spotlight should exclude them.
+     * - `setPOIFilter`'s category visibility, which composes: a category the
+     *   filter hides stays hidden whatever `match` says.
+     *
+     * Selecting a place (`selectPOI`, a map tap) releases the spotlight. Pass
+     * `null` — or call `clearPOISpotlight()` — to restore every marker.
+     */
+    setPOISpotlight(match: ((poi: POI) => boolean) | null): void;
+    /** Re-apply the zoom profile if the idle spotlight or a route just changed
+     *  which one is in force, and refresh what hangs off it. */
+    private syncZoomViews;
+    /** Restore every POI marker narrowed by `setPOISpotlight`. */
+    clearPOISpotlight(): void;
+    private applyPOISpotlight;
     private applyPOIFilter;
+    /**
+     * Show or hide destination dots, independently of their name labels and of
+     * `setPOIFilter`'s combined `'destination'` category (which still toggles
+     * both together). Affects every destination dot — both the dot+label
+     * marker on `poi-destination-labels` and the dot-only fallback on
+     * `poi-destination-circles` that a `showLabel: false` POI renders on.
+     *
+     * Implemented as `icon-opacity`, not a layer swap: dot and label are
+     * placed as one collision unit on `poi-destination-labels` (`icon-optional:
+     * false` / `text-optional: true`), which is what guarantees a label never
+     * renders without a dot beneath it. Splitting them into independently
+     * *placed* layers would let MapLibre's collision index resolve each half
+     * on its own, so a label could win placement while its dot lost — the
+     * "floating name" bug this theme's combined layer was built to fix (see
+     * `themes.test.ts` :: "a destination is one marker").
+     */
+    setDestinationCirclesVisible(visible: boolean): void;
+    /**
+     * Show or hide destination name labels, independently of their dots. See
+     * `setDestinationCirclesVisible` for why this is an opacity toggle on the
+     * shared marker layer rather than a separate label layer.
+     *
+     * `visible: true` (the default) doesn't mean "always on" — labels still
+     * fade in only once the visitor has zoomed in past the venue's opening
+     * view (`DESTINATION_LABEL_REVEAL_OFFSET` in `iconZoomRanges.ts`), so a
+     * zoomed-out visitor sees dots without the screen filling with names. Pass
+     * `false` to suppress labels outright regardless of zoom.
+     */
+    setDestinationLabelsVisible(visible: boolean): void;
+    private applyDestinationDisplay;
     /**
      * Return the waypoint in `waypoints` closest to `from`. Useful for
      * "route to the nearest X" against a venue-wide amenity record that has
@@ -1672,24 +1869,48 @@ declare class MinuteMaps {
      * single-venue scale, and avoids a turf dependency on the hot path.
      */
     findClosestWaypoint(waypoints: Waypoint[], from?: [number, number]): Waypoint | null;
+    /**
+     * Pick the candidate cheapest to reach from the kiosk — the one rule for
+     * "closest instance of an amenity". `navigateFromKioskToClosestAmenity` and
+     * `highlightAmenity` use it, and a consumer collapsing a venue-wide amenity
+     * to a single search row should too, so a tap and a search result can never
+     * resolve the same amenity to different floors.
+     *
+     * Each candidate is scored by `getWalkTimeFromKiosk().effortSeconds` — walk
+     * time over the JACS path graph **plus the elevator wait** for any floor
+     * change — and a candidate on a *different floor* from the kiosk has that
+     * score multiplied by `options.otherFloorPenalty` (default `1.5`; `1`
+     * disables it). The wait is the physical cost of leaving the floor; the
+     * multiplier is a preference for not making the visitor do it, and only
+     * applies here — it never changes a route.
+     *
+     * `toWaypoint` maps a candidate to the waypoint it stands for (identity for
+     * a `Waypoint[]`, `poi => poi.waypoint` for a `POI[]`). Candidates whose
+     * waypoint is missing or has no coordinates are ignored, as are waypoints
+     * the graph can't reach from the kiosk. If none resolve a cost, falls back
+     * to the planar `findClosestWaypoint`, **restricted to the kiosk's floor
+     * when any candidate is on it** (planar distance is meaningless across
+     * overlaid floors). Returns `null` for no usable candidate. Pass the same
+     * `avoidStairs` the route will use so the pick and the route agree.
+     */
+    findClosestByWalkTime<T>(items: readonly T[], toWaypoint: (item: T) => Waypoint | null | undefined, opts?: {
+        avoidStairs?: boolean;
+    }): T | null;
     /**
      * Route from the kiosk to the closest physical instance of an amenity.
      * Resolves the amenity venue-wide, picks the instance with the smallest
-     * path-graph walk time from the kiosk (falling back to planar Euclidean
-     * when the walk-time graph can't resolve any waypoint), switches the
+     * path-graph cost from the kiosk (`findClosestByWalkTime`: walk time plus
+     * the elevator wait, with a preference for the kiosk's floor; falling back
+     * to planar Euclidean when the walk-time graph can't resolve any waypoint), switches the
      * active floor if needed, and routes via the same plumbing as
      * `navigateFromKioskToPOI` — so step-by-step directions, the
      * `routeReady` event, and the active-floor camera fit all "just work."
      *
      * Pass `avoidStairs` to hard-filter stairs from the *route* (the SDK's
      * routing engine reads it per call; the CMS's per-path-type weight
-     * otherwise handles accessibility preference automatically). Note:
-     * closest-instance picking itself is currently distance-based and does
-     * not honor `avoidStairs` — the underlying walk-time graph applies
-     * pixel-length only. In practice this matters when an amenity has
-     * multiple instances and the geometrically closest is reachable only
-     * via stairs; the picked instance won't change today, but the *route*
-     * to it will avoid stairs (or fail gracefully) if `avoidStairs` is set.
+     * otherwise handles accessibility preference automatically). The same
+     * flag is passed to the closest-instance pick, so an instance reachable
+     * only by stairs is skipped in favour of one the route can actually reach.
      */
     navigateFromKioskToClosestAmenity(amenityId: string | number, options?: {
         avoidStairs?: boolean;
@@ -1712,6 +1933,32 @@ declare class MinuteMaps {
     private findFloorForWaypoint;
     getCameraPosition(): CameraState | null;
     getMap(): Map | null;
+    /**
+     * Hide one or more layers by id — a public, always-live counterpart to
+     * `debug.hide()` for consumers that want to toggle arbitrary layers
+     * without reaching into the console-facing debug API. Sticky: the
+     * override is re-asserted across floor changes, `setPOIFilter`, view-mode
+     * toggles and theme swaps until `showLayers` undoes it. Ids absent from
+     * the active style are skipped silently. Returns the ids actually found
+     * and hidden.
+     */
+    hideLayers(layerIds: string[]): string[];
+    /**
+     * Undo `hideLayers` for these ids. Each layer returns to whatever
+     * visibility the SDK's own state — current floor, POI filter, view mode —
+     * says it should have; it is **not** forced to `visible`. A layer the SDK
+     * is independently keeping hidden (another floor's layers, an
+     * off-view-mode extrusion) stays hidden rather than being force-revealed.
+     * This is the correct inverse of `hideLayers` (mirrors `debug.restore()` —
+     * see `debugLayers.ts` for why a blanket "show" is usually the wrong
+     * undo). Returns the ids that actually had an override to release.
+     */
+    showLayers(layerIds: string[]): string[];
+    /**
+     * Whether a layer is currently rendering (`visibility !== 'none'`).
+     * `false` for a layer absent from the active style.
+     */
+    isLayerVisible(layerId: string): boolean;
     /**
      * Put this instance on `window` so a kiosk running in a browser can be
      * driven from devtools — `mm.debug.help()`, `mm.getMap()`, `mm.setTheme(…)`.
@@ -1760,6 +2007,12 @@ declare class MinuteMaps {
      * disables it, explicit bounds pass through as-is, and a number (or the
      * unset default of 3) scales the venue's own bounds outward around its
      * center — see `scaleBounds`.
+     *
+     * The unset default is also floored at `DEFAULT_MIN_MAX_BOUNDS_SPAN_M` per
+     * side. MapLibre won't zoom out past the point where `maxBounds` fills the
+     * viewport, so a small venue's 3x box would otherwise raise the effective
+     * zoom-out floor above `minZoom` and show far less surrounding map than a
+     * large venue does. An explicit number is a deliberate leash and is left as-is.
      */
     private getMaxBounds;
     /**