@minmaps-dev/mm-web-sdk 1.0.0-rc.47 → 1.0.0-rc.48

package/dist/index.d.ts

@@ -277,6 +277,46 @@ type WayfindCenterMode = 'none' | 'destination' | 'route';
 type RoutingOptions = {
     avoidStairs?: boolean;
 };
+/**
+ * A spot on a floor that need not be a POI — a tap in the middle of a
+ * corridor. Routes and walk times accept one wherever they accept a POI:
+ * it's snapped to the closest point along a path on its floor and routed
+ * from (or to) there, without any CMS waypoint at that spot.
+ *
+ * `kind` tells it apart from a `POI`, which also has `floorId` and
+ * `coordinates`. Build one with `sdk.snapToPath`, or by hand from a stored
+ * point (a shared link) — the SDK snaps it again either way.
+ */
+type MapLocation = {
+    kind: 'location';
+    floorId: string | number;
+    /** `[lng, lat]`. */
+    coordinates: [number, number];
+    /** What the route calls it — the arrive step's landmark and the end
+     *  flag's label. Omitted, the arrive step reads "You have arrived". */
+    label?: string;
+    /** Where the visitor actually tapped, when it's off the walking network and
+     *  `coordinates` (where the route starts or ends) had to be moved onto it.
+     *  Set by `snapToPath`; a location built from a stored point is snapped from
+     *  `tapped ?? coordinates`, so store this to rebuild it later. */
+    tapped?: [number, number];
+    /** The walkable way from `tapped` to `coordinates` — around rooms, back-of-
+     *  house areas and other obstacles, leaving a room by its door — drawn as a
+     *  dotted line with a marker on the tap. `tapped` without `approach` means
+     *  no walkable way was found (a room with no known door, somewhere nothing
+     *  walks), so the point was simply moved to the nearest path. */
+    approach?: [number, number][];
+    /** `tapped` is inside a building or room, so `approach` leads to a hallway
+     *  rather than an outdoor walkway — it picks the approach step's wording.
+     *  Set by `snapToPath` alongside `approach`. */
+    indoors?: boolean;
+    /** `tapped` was in a hallway, a little way off its path line: the point was
+     *  moved to the middle of the hall, with no `approach` to draw. Set by
+     *  `snapToPath` with `tapped`; a "choose on map" UI can say so. */
+    centered?: boolean;
+};
+/** True for a `MapLocation`, false for a `POI`. */
+declare function isMapLocation(value: unknown): value is MapLocation;
 
 /**
  * A single point along the rendered route. `mapId` lets the renderer
@@ -304,7 +344,7 @@ type RoutePoint = {
     isEndpoint?: boolean;
 };
 
-type WayfindStep = DepartStep | TurnStep | ContinueStep | TransitionStep$1 | ArriveStep;
+type WayfindStep = DepartStep | TurnStep | ContinueStep | TransitionStep$1 | ApproachStep | ArriveStep;
 type StepBase = {
     /** Indices into the input `points` array that this step spans. */
     pointRange: [startInclusive: number, endInclusive: number];
@@ -340,15 +380,39 @@ type TransitionStep$1 = StepBase & {
 type ArriveStep = StepBase & {
     type: 'arrive';
 };
+/**
+ * The walk between a tapped spot and the walking network (`MapLocation.approach`):
+ * `'start'` from where the visitor tapped to the hallway, before the depart
+ * step; `'end'` from the hallway to the tapped destination, before arrive.
+ * Its geometry isn't on the route line, so it carries its own `path` (in
+ * walking order) — highlight and frame that, not `pointRange`, which only
+ * marks the route point it joins.
+ */
+type ApproachStep = StepBase & {
+    type: 'approach';
+    approach: 'start' | 'end';
+    path: [number, number][];
+};
 
 interface MapEvent {
     floor?: Floor;
+    /** `routeReady`: the destination routed to — the exact instance, so for
+     *  `navigateFromKioskToClosestAmenity` it carries the picked `waypointId`. */
     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];
+    /** `locationPicked`: the tap snapped to the closest point along a path, or
+     *  `null` when no path on the floor was within reach (`coordinates` is the
+     *  raw tap either way). `routeFailed`: the location that didn't resolve.
+     *  `routeReady`: the tapped spot routed to, in place of `poi`. */
+    location?: MapLocation | null;
+    /** `locationPicked`: the tap was outside every building and room on the
+     *  floor. With `hasOutdoorPaths(floor.id)` false, nothing outdoors on this
+     *  floor is walkable — the visitor wants a floor that has outdoor paths. */
+    outdoors?: boolean;
     error?: any;
     venue?: any;
     camera?: CameraState;
@@ -527,6 +591,16 @@ interface SDKOptions {
      * zoom.
      */
     initialZoom?: number;
+    /**
+     * Zoom floor for selecting a place — a map tap or `selectPOI` (default
+     * `19.25`, one level into the Kiosk view). A selection made from further out
+     * zooms in to this; a closer zoom is kept. At the Kiosk view's edge (18.25)
+     * the selected dot and name are drawn but still lose collision to their
+     * neighbours, and in the Building view (a room tapped from 16.5 up) they
+     * aren't drawn at all — either way the visitor selects a place they can't
+     * see. `0` keeps the current zoom on every selection.
+     */
+    selectionZoom?: number;
     /**
      * Clamp zoom-out relative to the opening view. When set, the map's
      * `minZoom` becomes `(initialZoom − this)`, so visitors can nudge out by
@@ -661,6 +735,12 @@ type SDKConfig = {
     options?: SDKOptions;
 };
 
+/** The chosen ends; either may be missing. */
+type RouteEndPreview = {
+    start?: POI | MapLocation | null;
+    destination?: POI | MapLocation | null;
+};
+
 type Visibility = 'visible' | 'none';
 type DebugLayersDeps = {
     getMap: () => Map | null;
@@ -1129,6 +1209,9 @@ type RouteImageOptions = {
     pixelRatio?: number;
     /** Padding around each floor's route segment, in CSS px. Default 40. */
     padding?: number;
+    /** Draw in flat (2D) mode, which reads better on paper. The previous mode
+     *  is put back afterwards. Default `true`. */
+    flat?: boolean;
     /** Image MIME type passed to `toDataURL`. Default `'image/png'`. */
     type?: string;
     /** Encoder quality for lossy types (`'image/jpeg'`, `'image/webp'`). */
@@ -1524,7 +1607,15 @@ declare class MinuteMaps {
     /** The destination of the last successfully computed route — kept so
      *  `setLocale()` can rebuild + re-emit `routeReady` with retranslated
      *  step text without recomputing the path. Cleared on route failure. */
-    private lastRouteDestinationPoi;
+    private lastRouteDestination;
+    /** `setLocationPicking` is on: a tap snaps to a path and emits
+     *  `locationPicked` instead of selecting what's under it. */
+    private locationPicking;
+    /** The active route's two ends, for redrawing its approaches after a
+     *  location-pick preview borrowed their source. */
+    private routeApproachEnds;
+    /** The running "moved to the nearest path" animation frame, if any. */
+    private pickAnimationFrame;
     /** Waypoint ids (stringified) of the connector(s) the active transition
      *  step rides — empty unless `setActiveStep` is on a transition. Drives
      *  `applyRouteConnectorHighlight`. */
@@ -1566,8 +1657,9 @@ declare class MinuteMaps {
      *  `clearHighlight`. */
     private selectedCoordinates;
     /** Zoom floor for the current selection's camera move, or `null` to keep
-     *  the current zoom. Set by `selectPOI` (a list pick can arrive from the
-     *  Campus view, where the roof still covers the room); kept beside
+     *  the current zoom. Set by `selectPOI` and map taps (`selectionZoom()` — a
+     *  pick can arrive from the Campus or Building view, where the selected
+     *  marker isn't drawn); kept beside
      *  `selectedCoordinates` so a `setBoundsPadding` re-nudge carries the same
      *  zoom instead of cancelling the zoom-in halfway. Cleared with it. */
     private selectedMinZoom;
@@ -2149,22 +2241,128 @@ declare class MinuteMaps {
     /**
      * Route between two arbitrary POIs — the browser/mobile counterpart of
      * `navigateFromKioskToPOI`, for visitors who aren't standing at a kiosk
-     * and pick their own starting point. Same events (`routeReady` /
-     * `routeFailed`) and the same `centerMode: 'route'` framing. Switches to
-     * the origin's floor first, because the route starts there.
-     *
-     * Emits `routeFailed` with `origin_unavailable` / `destination_unavailable`
-     * when either POI has no waypoint, `no_route` when no path connects them.
+     * and pick their own starting point. `navigateBetween` with POIs only.
      */
     navigateBetweenPOIs(from: POI, to: POI, options?: {
         avoidStairs?: boolean;
     }): Promise<any>;
     /**
-     * Distance + walking time between two arbitrary POIs over the path graph —
-     * `getWalkTimeFromKiosk` with a caller-chosen origin. `null` when either POI
-     * has no waypoint on the graph or no path resolves.
+     * Route between two picks, each a POI or a `MapLocation` (a tapped spot
+     * that isn't a POI — see `snapToPath`). A location is snapped to the
+     * closest point along a path on its floor and routed from there, so a
+     * visitor can start mid-corridor with no waypoint authored at that spot.
+     * Same events (`routeReady` / `routeFailed`) and the same
+     * `centerMode: 'route'` framing as the kiosk routes. Switches to the
+     * origin's floor first, because the route starts there.
+     *
+     * Emits `routeFailed` with `origin_unavailable` / `destination_unavailable`
+     * when a POI has no waypoint or a location has no path within reach,
+     * `no_route` when no path connects them.
      */
-    getWalkTimeBetween(from: POI, target: Parameters<MinuteMaps['getWalkTimeFromKiosk']>[0], opts?: {
+    navigateBetween(from: POI | MapLocation, to: POI | MapLocation, options?: {
+        avoidStairs?: boolean;
+    }): Promise<any>;
+    /**
+     * What a tap on the map stands for as one end of a route — the rule "choose
+     * on map" (`setLocationPicking`) applies, and the one to apply to a stored
+     * tap so it resolves the same way:
+     *
+     * - **Inside a room that holds a destination** → that destination (`POI`),
+     *   routed to its entrance. A clinic's examination rooms and the like aren't
+     *   somewhere to walk a visitor through, so a tap there never becomes a spot
+     *   with an approach (`destinationInRoomAt`: smallest such room, nearest
+     *   destination in it).
+     * - **Anywhere else** — an unplotted corridor, outdoors, a room with no
+     *   destination → `snapToPath`.
+     *
+     * `null` when the floor is unknown or no path is within reach.
+     */
+    resolveMapTap(location: Omit<MapLocation, 'kind'> | MapLocation): POI | MapLocation | null;
+    /** `destinationInRoomAt` against a floor's own geometry and destinations. */
+    private destinationInRoomAtTap;
+    /**
+     * Move a spot on a floor onto the walking network — where a route from (or
+     * to) it will actually start (or end). The path point chosen is the one
+     * closest **to walk to**, not the closest in a straight line: rooms,
+     * back-of-house areas, stairs, elevators, obstacles and other buildings are
+     * walked around, and a tap inside a room leaves by its door (inferred where
+     * a path crosses the room's outline) rather than through the wall to the
+     * corridor behind it. See `data/wayfinding/approach.ts`.
+     *
+     * Returns a `MapLocation` with `coordinates` on a path (`label` carried
+     * over) and, when the tap was off the network, `tapped` plus — if a
+     * walkable way was found — `approach`, the dotted line to draw. `tapped`
+     * without `approach` means the point was simply moved (a room with no known
+     * door, somewhere nothing walks) — or, with `centered`, moved from the side
+     * of a hallway to its middle. `null` when the floor is unknown or no path
+     * is within `maxDistanceMeters` (default 30 m).
+     *
+     * Planned from `tapped ?? coordinates`, so re-snapping a result (or a stored
+     * tap) gives the same answer. Until the floor's geometry has loaded it's the
+     * plain nearest point. Cross-floor paths are never snapped to.
+     */
+    snapToPath(location: Omit<MapLocation, 'kind'> | MapLocation, opts?: {
+        maxDistanceMeters?: number;
+    }): MapLocation | null;
+    /**
+     * Whether floor `floorId` has walkways outdoors — a path edge outside every
+     * building and room. A multi-storey campus usually draws its outdoor paths
+     * on the ground floor only, so a tap outside on another floor
+     * (`locationPicked`'s `outdoors`) can't reach one: a "choose on map" UI can
+     * point the visitor to a floor where this is `true`. `false` when the floor
+     * is unknown or its geometry hasn't loaded.
+     */
+    hasOutdoorPaths(floorId: Floor['id']): boolean;
+    /**
+     * Turn map taps into location picks — for a "choose on map" control. While
+     * on, a tap selects nothing; it's snapped to the closest point along a path
+     * on the visible floor (`snapToPath`), a ring marks the snapped spot, and
+     * **`locationPicked`** is emitted with `location` (the snapped
+     * `MapLocation`, or `null` when no path was in reach — the ring is taken
+     * down), `coordinates` (the raw tap), `floor`, and `outdoors` (the tap is
+     * outside every building and room — see `hasOutdoorPaths`). Turning it off removes
+     * the ring.
+     */
+    setLocationPicking(enabled: boolean): void;
+    /**
+     * Pin the ends a visitor has chosen for a route that isn't drawn yet — a
+     * route form's start and destination — so each choice reads as saved: the
+     * sprite's `marker-start` on `start`, `marker-destination` on
+     * `destination`. A location tapped off the walking network is pinned where
+     * it was tapped. Shown on the end's own floor only. Replaces the previous
+     * preview; `{}` clears it. Independent of the route — clear it once the
+     * route is drawn, so the route's own markers stand alone.
+     */
+    setRouteEndPreview(ends: RouteEndPreview): void;
+    /**
+     * A pick on the map: the ring on the on-path point, and the approach to it
+     * from the tap. A tap that had to be *moved* (no walkable way) is shown
+     * moving — its marker slides from the tap onto the path before the ring
+     * appears — so the jump reads as deliberate. With reduced motion it's
+     * simply there.
+     */
+    private showPickedLocation;
+    /** A pick that resolved to a destination (`resolveMapTap`): its room
+     *  raised and the ring on its pin, as `highlightPOI` locates one. */
+    private showPickedDestination;
+    private stopPickAnimation;
+    /** The floor's path-graph map id: for JACS venues the floor id *is* the
+     *  mapId, but read `mapId` first rather than lean on that. */
+    private mapIdForFloorId;
+    /** What the router takes for one end of a route: a POI's waypoint, or a
+     *  location's floor + on-path point (spliced in by the provider as a
+     *  virtual node). A location must already be through `snapToPath`, so its
+     *  `coordinates` are on a path. `null` when it can't be routed. */
+    private routeEndpointWaypoint;
+    /**
+     * Distance + walking time between two arbitrary picks over the path graph —
+     * `getWalkTimeFromKiosk` with a caller-chosen origin. Either end may be a
+     * `MapLocation`, snapped exactly as `navigateBetween` snaps it, and its
+     * `approach` (the walk from the tap to the path) is counted in `feet` /
+     * `seconds` / `effortSeconds`. `null` when a POI has no waypoint on the
+     * graph, a location has no path within reach, or no path resolves.
+     */
+    getWalkTimeBetween(from: POI | MapLocation, target: Parameters<MinuteMaps['getWalkTimeFromKiosk']>[0] | MapLocation, opts?: {
         walkingSpeedFps?: number;
         avoidStairs?: boolean;
     }): {
@@ -2173,10 +2371,17 @@ declare class MinuteMaps {
         effortSeconds: number;
         pathNodeCount: number;
     } | null;
+    /** One end of a walk-time query: a POI's waypoint, or a location's
+     *  on-path point (already through `snapToPath`). */
+    private walkTimeRef;
+    /** `routeReady`'s destination: `poi` for a place — the exact instance
+     *  routed to, so `navigateFromKioskToClosestAmenity`'s pick is visible —
+     *  or `location` for a tapped spot. */
+    private routeDestinationEventField;
     /** Shared tail of the route entry points: path, camera fit, steps, events.
-     *  `originPoi` is the start a visitor picked (`navigateBetweenPOIs`), which
+     *  `originPoi` is the start a visitor picked (`navigateBetween`), which
      *  gets a start pin; a kiosk route passes none — "You are here" marks it. */
-    private routeToPoi;
+    private routeTo;
     /** 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. */
@@ -2192,6 +2397,9 @@ declare class MinuteMaps {
      * instance under every floor's list.
      */
     private redrawFloorText;
+    /** The route's directions: `buildDirections` over the path, plus a step
+     *  for each tapped end's walk on to / off the network (`withApproachSteps`). */
+    private buildRouteSteps;
     private buildDirectionsContext;
     /**
      * Drive the turn-by-turn UI. Two effects:
@@ -2249,8 +2457,9 @@ declare class MinuteMaps {
      * buttons, the floor picker) never appears in them. For the duration the
      * map container is laid out at a fixed `width` × `height`, the camera
      * fits each floor's segment of the route with uniform `padding`, and the
-     * line is drawn solid (no draw-on sweep, no step highlight). Afterwards
-     * the container size, floor, camera and padding are put back. Hide the
+     * line is drawn solid (no draw-on sweep, no step highlight). The map is
+     * drawn flat (2D) unless `flat: false`. Afterwards the container size,
+     * floor, camera, flat/3D mode and padding are put back. Hide the
      * map behind a loading screen while this runs; the visitor would
      * otherwise see it jump between floors.
      *
@@ -2294,8 +2503,9 @@ declare class MinuteMaps {
      * gesture — it zooms and recenters and draws a pulsing ring, and emits
      * nothing. Selection is the quieter one: no ring, the raised room is the
      * indicator, and the current zoom is kept — unless it is further out than
-     * the Kiosk view (`KIOSK_VIEW_MIN_ZOOM`), where the building's roof still
-     * hides the room, in which case the camera zooms in to that view.
+     * `options.selectionZoom` (default 19.25, just inside the Kiosk view), where
+     * the room or its marker may not be drawn, in which case the camera zooms in
+     * to it. A map tap gets the same floor.
      *
      * Accepts a `POI` (preferred — its `type` and `waypointId` pin down the exact
      * instance, which matters for an amenity that shares one id across every
@@ -2317,6 +2527,11 @@ declare class MinuteMaps {
     selectPOI(target: POI | string | number, options?: {
         includeCoLocated?: boolean;
     }): Promise<POI[]>;
+    /** Zoom floor for a tap or `selectPOI` camera move (`options.selectionZoom`),
+     *  or `null` to keep the current zoom. The default sits a level past the
+     *  Kiosk view's edge: right at `KIOSK_VIEW_MIN_ZOOM` the selected dot and
+     *  name are drawn but routinely lose collision to amenities and room names. */
+    private selectionZoom;
     /** 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;
@@ -2823,5 +3038,5 @@ type ResolvedIconSource = {
  */
 declare function resolveAmenityIconSource(amenity: AmenityLike, preferredLocale?: string): ResolvedIconSource | null;
 
-export { BUILDING_NAME_EXTENSOR_KEY, DAY_KEYS, IMAGE_ALT_EXTENSOR_KEY, MinuteMaps, OPEN_HOURS_EXTENSOR_KEY, OPEN_HOURS_VERSION, PHONE_EXTENSOR_KEY, POINT_OF_INTEREST_EXTENSOR_KEY, RESERVED_EXTENSOR_PREFIX, SNAPSHOT_SCHEMA_VERSION, SnapshotProvider, SnapshotUnavailableError, VenueDirectory, activeSectionIndex, createMinuteMapsSDK, customerDisplayName, dayKeyAt, getOpenStatus, groupStepsIntoFloorSections, isConnectorAmenity, parseBuildingName, parseImageAlt, parseOpenHours, parsePhone, parsePointOfInterest, resolveAmenityIconSource, resolveSnapshotLocale, timeZoneAbbreviation };
-export type { Amenity, AmenityBadgeStyle, AmenityWithFloor, Bounds, BoundsPadding, CameraState, Customer, CustomerVenues, DayKey, Destination, DestinationPhone, EventCallback, Floor, FloorMetadata, HoursRange, JMapAuth, JMapConfig, JacsAuth, JacsConfig, JacsProviderConfig, JacsReader, ListCustomerVenuesOptions, MapEvent, OpenHours, OpenHoursTransition, OpenStatus, OpenStatusOptions, POI, POISearchResult, ResolvedIconSource, RouteFloorImage, RouteFloorSection, RouteImageOptions, RoutePoint, RoutingOptions, SDKConfig, SDKOptions, SnapshotProviderConfig, SnapshotUpdateCheck, SnapshotVersions, ThemeName, TransitionStep, VenueDirectoryConfig, VenueSummary, ViewOptions, WayfindCenterMode, WayfindStep, Waypoint, Zone };
+export { BUILDING_NAME_EXTENSOR_KEY, DAY_KEYS, IMAGE_ALT_EXTENSOR_KEY, MinuteMaps, OPEN_HOURS_EXTENSOR_KEY, OPEN_HOURS_VERSION, PHONE_EXTENSOR_KEY, POINT_OF_INTEREST_EXTENSOR_KEY, RESERVED_EXTENSOR_PREFIX, SNAPSHOT_SCHEMA_VERSION, SnapshotProvider, SnapshotUnavailableError, VenueDirectory, activeSectionIndex, createMinuteMapsSDK, customerDisplayName, dayKeyAt, getOpenStatus, groupStepsIntoFloorSections, isConnectorAmenity, isMapLocation, parseBuildingName, parseImageAlt, parseOpenHours, parsePhone, parsePointOfInterest, resolveAmenityIconSource, resolveSnapshotLocale, timeZoneAbbreviation };
+export type { Amenity, AmenityBadgeStyle, AmenityWithFloor, Bounds, BoundsPadding, CameraState, Customer, CustomerVenues, DayKey, Destination, DestinationPhone, EventCallback, Floor, FloorMetadata, HoursRange, JMapAuth, JMapConfig, JacsAuth, JacsConfig, JacsProviderConfig, JacsReader, ListCustomerVenuesOptions, MapEvent, MapLocation, OpenHours, OpenHoursTransition, OpenStatus, OpenStatusOptions, POI, POISearchResult, ResolvedIconSource, RouteEndPreview, RouteFloorImage, RouteFloorSection, RouteImageOptions, RoutePoint, RoutingOptions, SDKConfig, SDKOptions, SnapshotProviderConfig, SnapshotUpdateCheck, SnapshotVersions, ThemeName, TransitionStep, VenueDirectoryConfig, VenueSummary, ViewOptions, WayfindCenterMode, WayfindStep, Waypoint, Zone };