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

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { IControl, ControlPosition, StyleSpecification, Map } from 'maplibre-gl';
+import { Map, IControl, ControlPosition, StyleSpecification } from 'maplibre-gl';
 
 /**
  * Represents a floor in a building
@@ -51,6 +51,12 @@ interface POI {
     floorId: string | number;
     /** Category/type of amenity (e.g., 'restroom', 'elevator') */
     amenityType?: string;
+    /** Which amenity icon layer this POI renders in — `'connector'`,
+     *  `'entrance'`, `'parking'`, `'bus'` or `'other'`. Derived from the
+     *  amenity's connector flag, name, type and keywords; emitted as the
+     *  `amenityCategory` feature property the theme filters on. Amenities
+     *  only. See `amenityCategoryFor`. */
+    amenityCategory?: 'connector' | 'entrance' | 'parking' | 'bus' | 'other';
     /** Search keywords */
     keywords?: string[];
     /** Additional properties */
@@ -115,20 +121,26 @@ interface Destination {
     category?: string;
     /** Additional properties */
     properties?: Record<string, unknown>;
-    /** Uploaded image (e.g. brand/store logo). JACS `/all` fullcall serves this
-     *  as `{ items: [{ resourceType, mimeType, path }] }`; the legacy/basic shape
-     *  is `[{ locales: [{ uriPath }] }]`. `DestinationIcons.register` handles both. */
+    /** The CMS "Location Image" — a photo or logo for the popover, not a map
+     *  marker. JACS `/all` fullcall serves this as
+     *  `{ items: [{ resourceType, mimeType, path }] }`; the legacy/basic shape is
+     *  `[{ locales: [{ uriPath }] }]`. `destinationImageSrc` handles both, and
+     *  surfaces the result on `sdk.getPOIDetails(poi).imageUrl`. */
     uris?: unknown;
-    /** Free-form CMS metadata (reserved for future destination icon options). */
+    /** Inline SVG for the uploaded image, embedded by JACS `/all`. Preferred over
+     *  fetching `uris[].path` — no network round-trip. */
+    svg?: string;
+    /** Free-form CMS metadata. */
     extensors?: Record<string, unknown>;
-    /** Map-manager "Label Display" mode (JACS `displayMode`):
-     *  `0` Hidden (dot only) · `1` Label (dot + text) · `2` Image (uploaded logo).
-     *  Undefined → treated as Label (backwards-compatible default). */
+    /** @deprecated Read by nothing in the SDK as of rc.34.
+     *
+     *  JACS still serves the old map-manager "Label Display" mode
+     *  (`0` Hidden · `1` Label · `2` Image), but the CMS removed the picker and
+     *  pins every write to `1`. Rows authored before that keep a stale `0`/`2`
+     *  the author can no longer change, so honouring the field would hide labels
+     *  with no way to bring them back. Destinations always render dot + text
+     *  label; the uploaded image goes to the popover instead. */
     displayMode?: number;
-    /** Runtime-assigned map-image id, decorated in place by
-     *  `DestinationIcons.register` (only for `displayMode === 2`).
-     *  Read by the POI builder + theme layer. */
-    iconId?: string;
 }
 /**
  * Waypoint - a specific point location
@@ -339,16 +351,16 @@ type AmenityBadgeStyle = {
     /** Ring width in logical px. Default `2`. */
     ringWidth?: number;
 };
-type DestinationChipStyle = {
-    /** Chip fill colour. Default `'#FFFFFF'`. */
-    color?: string;
-    /** Chip border colour. Default navy `'#162e51'`. */
-    borderColor?: string;
-    /** Chip border width in logical px. Default `2`. */
-    borderWidth?: number;
-};
 interface SDKOptions {
     debug?: boolean;
+    /**
+     * `window` key the SDK instance is published under while `debug` is on, so
+     * a running kiosk can be driven from devtools (`mm.debug.hide('labels')`,
+     * `mm.getMap()`). Defaults to `'mm'`. Pass another name to avoid a clash,
+     * or `false` to publish nothing even in debug mode. Ignored entirely when
+     * `debug` is off.
+     */
+    debugGlobal?: string | false;
     /**
      * Initial theme. `'default'` uses the bundled hybrid 3D theme.
      * `'high-contrast'` uses the WCAG-AA tuned theme. Pass a
@@ -437,14 +449,6 @@ interface SDKOptions {
      * unless this is set explicitly.
      */
     connectorBadge?: AmenityBadgeStyle | false;
-    /**
-     * Chip composited behind each destination's uploaded logo. Destinations are
-     * full-colour brand images (not recoloured), so they get a neutral white
-     * rounded chip for legibility instead of the amenity gold badge. Pass `false`
-     * to render the logo bare, or an object to tune the chip fill / border.
-     * Defaults to a white chip with a 2px navy border.
-     */
-    destinationChip?: DestinationChipStyle | false;
     styleMode?: 'venueStyleUrl' | 'sdkTemplate';
     templateOverrideMode?: 'colorsOnly' | 'colorsAndConstants' | 'all';
 }
@@ -497,6 +501,230 @@ type SDKConfig = {
     options?: SDKOptions;
 };
 
+type Visibility = 'visible' | 'none';
+type DebugLayersDeps = {
+    getMap: () => Map | null;
+    /**
+     * Re-assert the visibility the SDK itself owns — floor layers, the POI
+     * category filter, the 2D/3D view mode. Called at the end of `reset()`,
+     * because restoring a captured `visibility` can't distinguish "the theme
+     * ships this visible" from "the SDK hid it because it belongs to another
+     * floor", and the naive restore would reveal every floor at once.
+     */
+    reapplySdkState?: () => void;
+    log?: (...args: unknown[]) => void;
+};
+type LayerRow = {
+    id: string;
+    type: string;
+    visibility: Visibility;
+    /**
+     * What this layer's visibility was before we touched it — i.e. what the
+     * theme and the SDK want it to be. Equal to `visibility` for any layer we
+     * hold no override on. A UI wanting to show "is this group on" should judge
+     * only the layers whose `base` is `'visible'`: the rest (the 3D extrusions
+     * in flat mode, the 2D outlines outside it) aren't rendering by design, so
+     * counting them makes a healthy group look half-off.
+     */
+    base: Visibility;
+};
+/**
+ * Console-facing layer inspector for demos, screenshots and debugging.
+ *
+ * Reachable as `sdk.debug`, and as `window.mm.debug` when
+ * `options.debug` is on (see `options.debugGlobal`).
+ *
+ * Two things make it more than a wrapper around `setLayoutProperty`:
+ *
+ * 1. **Selectors.** `hide('amenities')`, `hide('route-')`, `hide('/^poi-/')`
+ *    and `hide('type:fill-extrusion')` all work, so you don't have to know
+ *    the theme's layer ids to start poking at it.
+ * 2. **Overrides are sticky.** The SDK re-asserts layer visibility on floor
+ *    changes, `setPOIFilter`, flat-mode toggles and theme swaps — all of which
+ *    would otherwise wipe a manual toggle mid-demo. Every override is re-applied
+ *    on `styledata`, so what you hid stays hidden until `reset()`.
+ */
+declare class DebugLayers {
+    private deps;
+    /** layer id → visibility this API is asserting. */
+    private overrides;
+    /** layer id → visibility before we first touched it. */
+    private originals;
+    /** `${layer}|${prop}` → paint value before we first touched it. */
+    private paintOriginals;
+    private sticky;
+    private attachedTo;
+    /** Re-entrancy guard: our own `setLayoutProperty` fires `styledata`. */
+    private applying;
+    private readonly onStyleData;
+    constructor(deps: DebugLayersDeps);
+    /** Begin re-asserting overrides across style/floor changes. */
+    attach(map: Map): void;
+    detach(): void;
+    /**
+     * Every layer in the active style, newest-on-top last, with its current
+     * visibility. Pass a selector to narrow it (same grammar as `hide`).
+     */
+    list(selector?: string): LayerRow[];
+    /** Just the ids currently rendering — the quickest "what am I looking at". */
+    visible(): string[];
+    /** Group name → the ids it resolves to *in the active style*. */
+    groups(): Record<string, string[]>;
+    /** Hide every layer the selectors resolve to. Returns the ids affected. */
+    hide(...selectors: string[]): string[];
+    /**
+     * **Force** every resolved layer visible — including ones the SDK
+     * deliberately keeps off: the 3D extrusions while flat mode is on, the 2D
+     * outlines while it isn't, every floor but the active one. Forcing those
+     * renders two representations of the same geometry at once, or every floor
+     * stacked, and the map looks wrong.
+     *
+     * So this is *not* the way to undo a `hide()` — use `restore()`, which puts
+     * each layer back to what it was rather than blanket-revealing the group.
+     * Reach for `show()` only when you actually mean "reveal this regardless".
+     */
+    show(...selectors: string[]): string[];
+    /**
+     * Undo our overrides on these layers: each goes back to the visibility it
+     * had before we first touched it, and control returns to the SDK (floor
+     * layers, POI filter, view mode re-assert afterwards).
+     *
+     * This is the correct inverse of `hide()`. A group is rarely uniformly
+     * visible to begin with — `rooms` hides either the 2D outline or the 3D
+     * extrusion depending on view mode, and every floor layer but the active
+     * one is off — so `hide()` then `show()` does not round-trip, but `hide()`
+     * then `restore()` does.
+     *
+     * Returns the ids that actually had an override; layers we never touched
+     * are left alone.
+     */
+    restore(...selectors: string[]): string[];
+    /** Flip each resolved layer independently. Returns the ids affected. */
+    toggle(...selectors: string[]): string[];
+    /**
+     * Show only what the selectors resolve to — everything else is hidden
+     * (except `background`, which is just the canvas colour). The one-liner for
+     * "which layer is drawing that thing".
+     *
+     * The kept set is *restored*, not forced: anything we'd previously hidden
+     * comes back, but a layer the theme ships hidden stays hidden. Soloing must
+     * not invent geometry that never renders normally — see `show()`.
+     */
+    solo(...selectors: string[]): string[];
+    /**
+     * Set a paint property — `paint('units-fill', 'fill-color', '#f00')`. The
+     * original value is captured so `reset()` puts it back. Not sticky: unlike
+     * visibility, a theme swap rebuilds paint from the new style and re-applying
+     * a captured expression across themes is exactly the bug `setTheme` had to
+     * fix. Re-run it after a swap if you need it back.
+     */
+    paint(selector: string, prop: string, value: unknown): string[];
+    /**
+     * Drop every override and paint change, then let the SDK re-assert the
+     * visibility it owns (floor layers, POI filter, view mode). Back to the map
+     * you'd have had without touching anything.
+     */
+    reset(): void;
+    /**
+     * Hand the layers we just released back to the SDK, then re-assert whatever
+     * overrides are still standing.
+     *
+     * The second half is not belt-and-braces. The SDK's re-assert passes are
+     * all-or-nothing: with no POI filter active, `applyPOIFilter` writes
+     * `visible` to *every* POI category layer, and the floor / view-mode passes
+     * sweep their whole layer sets the same way. So releasing one group would
+     * un-hide every other group you'd hidden — hide labels, destinations and
+     * amenities, re-check one, and all three came back.
+     *
+     * Doing it here rather than waiting for the `styledata` the SDK's writes
+     * trigger also keeps it synchronous: MapLibre fires that on a later frame,
+     * so a UI reading visibility straight after this call would otherwise see —
+     * and render — the clobbered state.
+     */
+    private handBackToSdk;
+    /**
+     * The current override set as a plain object — save it, paste it back with
+     * `apply()` to reproduce the exact same framing for a screenshot later.
+     */
+    snapshot(): Record<string, Visibility>;
+    /** Apply a `snapshot()` (or any layer-id → visibility map). */
+    apply(snapshot: Record<string, Visibility>): string[];
+    /**
+     * Stop (or resume) re-asserting overrides when the style changes. Turn it
+     * off if you want a floor switch or `setPOIFilter` to win over what you
+     * toggled by hand.
+     */
+    setSticky(enabled: boolean): boolean;
+    /** Console cheat sheet. */
+    help(): Array<{
+        call: string;
+        does: string;
+    }>;
+    /**
+     * Resolve one selector to layer ids present in the active style, tried in
+     * order: group name → exact layer id → `type:<layer type>` → `/regex/` →
+     * case-insensitive substring on the id.
+     */
+    resolve(selector: string): string[];
+    private resolveAll;
+    private set;
+    /**
+     * Put these layers back to their pre-override visibility and forget them.
+     * Callers decide whether to follow up with `reapplySdkState` — `restore()`
+     * and `reset()` do, `solo()` deliberately doesn't.
+     */
+    private restoreVisibility;
+    /** Write one layer's visibility and remember it as an override. */
+    private write;
+    /**
+     * Re-assert overrides after something else rewrote layer visibility. Only
+     * writes when the current value actually differs, so this doesn't feed
+     * itself through the `styledata` it triggers.
+     */
+    private reapply;
+    private styleLayers;
+    private visibilityOf;
+    /**
+     * MapLibre throws from these getters/setters while a style is mid-swap (the
+     * layer exists in `getStyle()` but its owner is being replaced). A debug tool
+     * that can break the map it's inspecting is worse than useless.
+     */
+    private safe;
+}
+
+type LayerAudit = {
+    /** `featureType` values the CMS permits for this customer. */
+    allowed: string[];
+    /** `featureType` values actually present in the loaded floors. */
+    inData: string[];
+    /** `featureType` values some theme layer filters on. */
+    inStyle: string[];
+    /**
+     * Drawn on a map but not in the customer's allowed list — a mis-authored
+     * or renamed layer. These render only by accident (if the theme happens to
+     * match the string) and are invisible otherwise.
+     */
+    unauthorized: string[];
+    /**
+     * Present in the data and allowed, but no theme layer filters on it. The
+     * author drew something the map will never show.
+     */
+    unstyled: string[];
+    /**
+     * The theme filters on it, but no loaded floor contains it. Dead weight in
+     * the style *for this venue* — another venue may well use it, so this is a
+     * prompt to check, not a delete list. Cross-reference `allowed`: a value
+     * that isn't in there either is dead everywhere for this customer.
+     */
+    unused: string[];
+    /**
+     * Allowed by the CMS but no theme rule matches it, whether or not this
+     * venue happens to draw it. The SDK's total blind spot — an author can
+     * legitimately draw any of these and get nothing.
+     */
+    allowedNotStyled: string[];
+};
+
 type LoggerFn = (...args: unknown[]) => void;
 type AmenityManagerDeps = {
     getVenue: () => any;
@@ -559,8 +787,17 @@ declare class MinuteMaps {
     private floorsApi;
     private venue;
     private spriteKeys;
-    private readonly debug;
+    private readonly debugEnabled;
     private readonly logger;
+    /**
+     * Console-facing layer inspector — `sdk.debug.hide('labels')`,
+     * `sdk.debug.solo('route')`, `sdk.debug.reset()`. Always present so demo
+     * code can drive it; additionally reachable as `window.mm.debug` when
+     * `options.debug` is on. See `DebugLayers`.
+     */
+    readonly debug: DebugLayers;
+    /** The `window` key `debug` mode installed this instance under, if any. */
+    private debugGlobalKey;
     private defaultCamera;
     private viewModes;
     /** Mirror of `config.options.reducedMotion`, mutable via `setReducedMotion`. */
@@ -616,10 +853,9 @@ declare class MinuteMaps {
      *  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 —
-     *  are intentionally unaffected; they're either anchors, status
-     *  indicators, or transient focus state, not categorical content. */
+     *  toggles. Layers absent from this list — `poi-you-are-here-*` and the
+     *  `poi-highlight-*` layers — are intentionally unaffected; they're
+     *  anchors or transient focus state, not categorical content. */
     private static readonly POI_CATEGORY_LAYERS;
     private poiVisibleTypes;
     constructor(config: SDKConfig);
@@ -676,6 +912,21 @@ declare class MinuteMaps {
     set3dEnabled(enabled: boolean): void;
     toggle3d(): void;
     getIs3dEnabled(): boolean;
+    /**
+     * (Re-)register per-amenity icons, per-destination logos, and the kiosk
+     * "you are here" icon. Needed both at init and after every `setTheme()`
+     * call — `map.setStyle(..., { diff: false })` tears down and recreates
+     * the whole `Style` object, which drops every image added at runtime via
+     * `map.addImage`. Only `route-arrow` re-registers itself lazily via
+     * `styleimagemissing`; everything else must be re-run explicitly here or
+     * it silently goes blank after a theme swap.
+     *
+     * `themeName === 'high-contrast'` recolors the amenity badge disc to
+     * `HIGH_CONTRAST_AMENITY_BADGE_COLOR`, leaving ring/glyph colors and
+     * connector (elevator/stairs/escalator) badges untouched. Failures per
+     * icon set are logged and skipped so one bad icon doesn't block the rest.
+     */
+    private registerRuntimeIcons;
     /**
      * Set the active map theme by name (`'default'` / `'high-contrast'`) or by
      * passing a custom `StyleSpecification`. The current floor, route, POIs
@@ -733,9 +984,9 @@ declare class MinuteMaps {
     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. */
+     *  `zoneName`, `keywords`, `description`, and `imageUrl` 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';
@@ -745,12 +996,36 @@ declare class MinuteMaps {
         zoneDescription?: string;
         keywords?: string[];
         description?: string;
+        /** The destination's uploaded location image, ready for an `<img src>`.
+         *  Destinations only — amenities use sprite glyphs, not photos. Inline SVG
+         *  from `/all` comes back as a data URI; otherwise it's the uploaded uri
+         *  path. Absent when nothing was uploaded in the CMS. */
+        imageUrl?: 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[];
+    /**
+     * Cross-reference the venue's drawn layers against the customer's allowed
+     * layer list (JACS `GET /customer/{id}/polygon-layer`) and against what the
+     * active theme can actually render.
+     *
+     * Three failure modes, none of which is visible by looking at the map:
+     * a layer drawn under a name the CMS doesn't list (`unauthorized`), a layer
+     * legitimately drawn that no theme rule matches (`unstyled`), and a theme
+     * rule with nothing to draw at this venue (`unused`). Runs automatically
+     * once after `ready` when `options.debug` is on; call it directly —
+     * `mm.validateMapLayers()` — any time.
+     *
+     * Only counts floors whose geojson has loaded. Init preloads the rest in
+     * the background, so a call in the first moments after `ready` may report
+     * fewer `inData` types than a call a second later.
+     */
+    validateMapLayers(): Promise<LayerAudit>;
+    /** Debug-mode auto-run: log findings once, stay silent when clean. */
+    private reportLayerAudit;
     getFloorMapTemplate3d(floorId: string | number): any[];
     getAllPOIs(floor?: Floor): POI[];
     getYouAreHerePOI(floor?: Floor): POI | null;
@@ -993,6 +1268,19 @@ declare class MinuteMaps {
     private findFloorForWaypoint;
     getCameraPosition(): CameraState | null;
     getMap(): Map | null;
+    /**
+     * Put this instance on `window` so a kiosk running in a browser can be
+     * driven from devtools — `mm.debug.help()`, `mm.getMap()`, `mm.setTheme(…)`.
+     * Debug builds only: nothing is exposed unless `options.debug` is on, and
+     * `options.debugGlobal` renames the key (or `false` opts out entirely).
+     *
+     * Refuses to clobber a key that already holds something that isn't a
+     * MinuteMaps — a kiosk shell with its own `window.mm` shouldn't lose it to
+     * a dev-mode convenience.
+     */
+    private exposeDebugGlobal;
+    /** Drop the `window` handle, but only if it still points at this instance. */
+    private releaseDebugGlobal;
     destroy(): void;
     setCurrentFloor(floor: Floor): Promise<void>;
     /**
@@ -1077,4 +1365,4 @@ declare function groupStepsIntoFloorSections(steps: WayfindStep[]): RouteFloorSe
 declare function activeSectionIndex(sections: RouteFloorSection[], activeStepIndex: number): number;
 
 export { MinuteMaps, activeSectionIndex, createMinuteMapsSDK, groupStepsIntoFloorSections };
-export type { Amenity, AmenityBadgeStyle, AmenityWithFloor, Bounds, BoundsPadding, CameraState, Destination, DestinationChipStyle, EventCallback, Floor, FloorMetadata, JMapAuth, JMapConfig, JacsAuth, JacsConfig, MapEvent, POI, POISearchResult, RouteFloorSection, RoutePoint, RoutingOptions, SDKConfig, SDKOptions, ThemeName, TransitionStep, ViewOptions, WayfindCenterMode, WayfindStep, Waypoint, Zone };
+export type { Amenity, AmenityBadgeStyle, AmenityWithFloor, Bounds, BoundsPadding, CameraState, Destination, EventCallback, Floor, FloorMetadata, JMapAuth, JMapConfig, JacsAuth, JacsConfig, MapEvent, POI, POISearchResult, RouteFloorSection, RoutePoint, RoutingOptions, SDKConfig, SDKOptions, ThemeName, TransitionStep, ViewOptions, WayfindCenterMode, WayfindStep, Waypoint, Zone };