@minmaps-dev/mm-web-sdk 1.0.0-rc.22 → 1.0.0-rc.24

package/dist/index.d.ts

@@ -166,6 +166,83 @@ type ViewOptions = {
 /** SW/NE bounding box */
 type Bounds = [[number, number], [number, number]];
 
+/** How to center the map after computing a route */
+type WayfindCenterMode = 'none' | 'destination' | 'route';
+/**
+ * Per-call routing preferences forwarded to the wayfinding provider.
+ *
+ * - `accessible` — prefer accessible paths; providers should drop or heavily
+ *   penalize edges marked inaccessible (stairs by default, anything else
+ *   the provider's data flags).
+ * - `avoidStairs` — hard-filter stairs from the graph.
+ *
+ * The bundled stub provider doesn't compute routes; consumers wire a real
+ * provider (see `mm-web-sdk-example/lib/wayfinding`) that reads these
+ * flags when building edge weights.
+ */
+type RoutingOptions = {
+    accessible?: boolean;
+    avoidStairs?: boolean;
+};
+
+/**
+ * A single point along the rendered route. `mapId` lets the renderer
+ * split the polyline by floor (so other-floor segments don't paint
+ * through the visible floor's geometry); `waypointId` and `pathTypeId`
+ * let downstream layers (text-directions, step UI) classify
+ * transitions — e.g. "Take the elevator" vs "Walk straight". The two
+ * endpoint points are the kiosk and destination anchors (`isEndpoint`
+ * marks them so they can render endpoint pins). All fields except
+ * `coordinates` are optional for backward-compat with the straight-line
+ * fallback.
+ */
+type RoutePoint = {
+    coordinates: [number, number];
+    /** Floor mapId this point sits on. Missing on the straight-line fallback. */
+    mapId?: number;
+    /** JACS waypoint id this point resolved to, if any. */
+    waypointId?: number;
+    /** Path type of the edge that LEADS INTO this point (i.e. the edge
+     *  whose `toKey` is this node). Used to detect elevator / stair /
+     *  escalator transitions. Missing on the start point and on the
+     *  straight-line fallback. */
+    pathTypeId?: number;
+    /** True for the snapped kiosk + destination anchors. */
+    isEndpoint?: boolean;
+};
+
+type WayfindStep = DepartStep | TurnStep | ContinueStep | TransitionStep | ArriveStep;
+type StepBase = {
+    /** Indices into the input `points` array that this step spans. */
+    pointRange: [startInclusive: number, endInclusive: number];
+    /** Floor this step is on. `null` for cross-floor transitions. */
+    floorId: number | null;
+    /** Localized instruction text. */
+    text: string;
+    /** Total walking distance within this step, in meters (rounded). */
+    distanceMeters?: number;
+    /** Landmark name used for anchoring, if any. */
+    landmark?: string;
+};
+type DepartStep = StepBase & {
+    type: 'depart';
+};
+type TurnStep = StepBase & {
+    type: 'turn-left' | 'turn-right' | 'u-turn';
+};
+type ContinueStep = StepBase & {
+    type: 'continue';
+};
+type TransitionStep = StepBase & {
+    type: 'transition';
+    transition: 'elevator' | 'stairs' | 'escalator';
+    fromFloorId: number | null;
+    toFloorId: number | null;
+};
+type ArriveStep = StepBase & {
+    type: 'arrive';
+};
+
 interface MapEvent {
     floor?: Floor;
     poi?: POI;
@@ -178,6 +255,16 @@ interface MapEvent {
     /** Emitted by `localeChanged` after `setLocale()` finishes patching the
      *  venue model. BCP-47 code (`'en'`, `'es'`, `'es-MX'`). */
     locale?: string;
+    /** Emitted by `routeReady` after a successful `navigateFromKioskToPOI`.
+     *  Carries the raw geometry (`points`) and the human-readable
+     *  step-by-step directions. Subscribe to drive a turn-by-turn UI. */
+    route?: {
+        points: RoutePoint[];
+        steps: WayfindStep[];
+        /** Floor mapId of each segment, in render order. `null` for
+         *  segments emitted by the straight-line fallback. */
+        floorIds: Array<number | null>;
+    };
 }
 type EventCallback = (event: MapEvent) => void;
 
@@ -200,6 +287,19 @@ type BoundsPadding = number | {
  * custom themes.
  */
 type ThemeName = 'default' | 'high-contrast';
+/**
+ * Style of the disc + ring rendered behind each amenity icon. The SDK
+ * composites this into the icon bitmap at registration time, so badge +
+ * icon participate in symbol collision as one unit.
+ */
+type AmenityBadgeStyle = {
+    /** Fill colour of the badge disc. Default `'#fdb81e'`. */
+    color?: string;
+    /** Stroke colour of the ring around the disc. Default `'#FFFFFF'`. */
+    ringColor?: string;
+    /** Ring width in logical px. Default `2`. */
+    ringWidth?: number;
+};
 interface SDKOptions {
     debug?: boolean;
     /**
@@ -241,13 +341,26 @@ interface SDKOptions {
      */
     minZoomBelowInitialFit?: number;
     /**
-     * If set, the SDK recolours every amenity SVG to this colour as it
-     * registers the icon (visible fills + strokes; `none` / `transparent` are
-     * preserved). Pair with a theme circle badge layer so amenities read as
-     * polished icon-on-badge — e.g. `#ffffff` icons on the gold `poi-amenity-
-     * badge` layer in the bundled hybrid theme. Omit to keep the CMS colours.
+     * Override the colour the SDK recolours every amenity SVG to before it
+     * composites the badge. `none` / `transparent` fills are preserved so
+     * cut-outs stay. When the badge is enabled (the default), this defaults
+     * to navy (`#162e51`) so icons read on gold. Set explicitly for a
+     * different look, or set `amenityBadge: false` to disable recolouring
+     * altogether and keep the CMS-uploaded colours.
      */
     amenityIconColor?: string;
+    /**
+     * Badge composited behind each amenity icon. Pass `false` to render the
+     * icon alone (no badge — useful for high-contrast or 2D themes where the
+     * gold disc would compete with the floor). Pass an object to tune the
+     * disc / ring style. Defaults to a VA-gold disc with a 2px white ring.
+     *
+     * The badge is baked into the icon bitmap (canvas composite) rather than
+     * drawn as a separate circle layer, so badge + icon participate in symbol
+     * collision together — overlapping amenities hide as one unit instead of
+     * the icon hiding while the disc stays painted.
+     */
+    amenityBadge?: AmenityBadgeStyle | false;
     styleMode?: 'venueStyleUrl' | 'sdkTemplate';
     templateOverrideMode?: 'colorsOnly' | 'colorsAndConstants' | 'all';
 }
@@ -300,25 +413,6 @@ type SDKConfig = {
     options?: SDKOptions;
 };
 
-/** How to center the map after computing a route */
-type WayfindCenterMode = 'none' | 'destination' | 'route';
-/**
- * Per-call routing preferences forwarded to the wayfinding provider.
- *
- * - `accessible` — prefer accessible paths; providers should drop or heavily
- *   penalize edges marked inaccessible (stairs by default, anything else
- *   the provider's data flags).
- * - `avoidStairs` — hard-filter stairs from the graph.
- *
- * The bundled stub provider doesn't compute routes; consumers wire a real
- * provider (see `mm-web-sdk-example/lib/wayfinding`) that reads these
- * flags when building edge weights.
- */
-type RoutingOptions = {
-    accessible?: boolean;
-    avoidStairs?: boolean;
-};
-
 type LoggerFn = (...args: unknown[]) => void;
 type AmenityManagerDeps = {
     getVenue: () => any;
@@ -379,6 +473,7 @@ declare class MinuteMaps {
     private amenityManager;
     private wayfinding;
     private highlightManager;
+    private youAreHerePulse;
     /** 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 —
@@ -476,6 +571,45 @@ declare class MinuteMaps {
      * cone rendered next to the "You are here" marker.
      */
     getKioskHeading(): number | null;
+    /**
+     * Display name of the JACS device the kiosk is anchored to (e.g.
+     * "Main Lobby Kiosk", "Information Desk Kiosk"). `null` when the venue
+     * has no kiosk anchor or the device record carries no `name`.
+     *
+     * Distinct from `getYouAreHerePOI()?.name`, which is always the
+     * literal "You are here" label rendered on the map. Use this for chrome
+     * that needs the kiosk's identity — e.g. the directions overlay's
+     * "From <kiosk>" header.
+     */
+    getKioskName(): string | null;
+    /**
+     * Distance + walking time from the kiosk's anchor waypoint to a target,
+     * computed over the JACS path graph (the same graph the routing engine
+     * uses). Designed for "Closest: 30 sec walk" subtitles in the consumer
+     * UI — no second graph build, no second Dijkstra implementation.
+     *
+     * Accepts a raw waypoint id, an amenity / destination object (the first
+     * entry of its `waypoints` array is treated as the entry point), or any
+     * `{ 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).
+     */
+    getWalkTimeFromKiosk(target: number | string | {
+        id?: number | string;
+        mapId?: number;
+    } | {
+        waypoints?: Array<number | string | {
+            id?: number | string;
+        }>;
+    }, opts?: {
+        walkingSpeedMps?: number;
+    }): {
+        meters: number;
+        seconds: number;
+        pathNodeCount: number;
+    } | null;
     /**
      * Center the camera on the kiosk's "You are here" position. Use this
      * (not `resetView`) for a chrome "Recenter" button — `resetView` snaps
@@ -524,6 +658,30 @@ declare class MinuteMaps {
         accessible?: boolean;
         avoidStairs?: boolean;
     }): Promise<any>;
+    /** Build the landmark / floor-name context the directions module needs.
+     *  Pulled out so `setLocale()` or `setActiveStep()` can rebuild it on
+     *  demand if we ever surface a locale-aware variant. */
+    private buildDirectionsContext;
+    /**
+     * Drive the turn-by-turn UI. Two effects:
+     *
+     * 1. When the step's `floorId` differs from the active floor, switch
+     *    floors so the segment for the step's leg becomes visible.
+     * 2. Highlight the step's slice of the route line by writing the
+     *    point range to the `route-active-step` source; the bundled
+     *    theme's `route-line-active` layer paints it in gold over the
+     *    muted base route.
+     *
+     * Transition steps (cross-floor elevator / stair hops) clear the
+     * highlight — the overlay text carries the action, and there's no
+     * meaningful on-floor segment to paint.
+     *
+     * Pass `null` to clear the highlight without changing the floor or
+     * tearing down the route.
+     */
+    setActiveStep(step: WayfindStep | null): Promise<void>;
+    private writeActiveStepHighlight;
+    private clearActiveStepHighlight;
     clearRoute(): void;
     /**
      * Highlight a single POI on the map — a pulsing ring — and bring it into
@@ -555,6 +713,28 @@ declare class MinuteMaps {
      * single-venue scale, and avoids a turf dependency on the hot path.
      */
     findClosestWaypoint(waypoints: Waypoint[], from?: [number, number]): Waypoint | 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
+     * 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 `accessible` / `avoidStairs` to weight the *route* (the SDK's
+     * routing engine reads these per call). Note: closest-instance picking
+     * itself is currently distance-based and does not yet honor those
+     * weights — 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 `accessible`/`avoidStairs` is set.
+     */
+    navigateFromKioskToClosestAmenity(amenityId: string | number, options?: {
+        accessible?: boolean;
+        avoidStairs?: boolean;
+    }): Promise<any>;
     /**
      * Highlight + center on the closest physical instance of an amenity.
      * The amenity is resolved against `amenities.getDistinct()` (venue-wide,
@@ -575,6 +755,23 @@ declare class MinuteMaps {
     getMap(): Map | null;
     destroy(): void;
     setCurrentFloor(floor: Floor): Promise<void>;
+    /**
+     * Filter the route-line / route-halo layers to only render segments
+     * whose `floorId` matches the active floor (or features that carry no
+     * `floorId` at all — the straight-line fallback, which we want visible
+     * on every floor since it has no floor membership to filter against).
+     *
+     * Features are tagged with the JACS pixel `mapId` (that's what flows
+     * through the route point's `mapId`), so the filter compares against
+     * the active floor's `mapId`, NOT its `id` — those are two different
+     * JACS identifiers (`floor.id` is the building-floor record; `mapId`
+     * is the SVG asset). We accept the floor's `id` here for convenience
+     * and resolve to `mapId` via `getFloors()`.
+     *
+     * Applied imperatively rather than baked into the theme JSON so the
+     * filter tracks runtime floor changes without restyling the map.
+     */
+    private updateRouteFloorFilter;
     isReady(): boolean;
     private setFloorLayerVisibility;
     private getBoundsPadding;
@@ -603,4 +800,4 @@ declare class MinuteMaps {
 declare function createMinuteMapsSDK(config: SDKConfig): MinuteMaps;
 
 export { MinuteMaps, createMinuteMapsSDK };
-export type { Amenity, AmenityWithFloor, Bounds, BoundsPadding, CameraState, Destination, EventCallback, Floor, FloorMetadata, JMapAuth, JMapConfig, JacsAuth, JacsConfig, MapEvent, POI, POISearchResult, RoutingOptions, SDKConfig, SDKOptions, ThemeName, ViewOptions, WayfindCenterMode, Waypoint };
+export type { Amenity, AmenityBadgeStyle, AmenityWithFloor, Bounds, BoundsPadding, CameraState, Destination, EventCallback, Floor, FloorMetadata, JMapAuth, JMapConfig, JacsAuth, JacsConfig, MapEvent, POI, POISearchResult, RoutePoint, RoutingOptions, SDKConfig, SDKOptions, ThemeName, ViewOptions, WayfindCenterMode, WayfindStep, Waypoint };