@minmaps-dev/mm-web-sdk 1.0.0-rc.51 → 1.0.0-rc.53

package/dist/index.d.ts

@@ -86,6 +86,10 @@ interface POI {
      *  type-level name shared by every instance — see `Amenity.name`. Amenities
      *  only, and only set when JACS actually returned an instance name. */
     instanceName?: string;
+    /** The instance flags set to Yes on this placement (`mm_baby_changing`,
+     *  `mm_wheelchair_accessible`), in `INSTANCE_FLAG_KEYS` order. Amenities
+     *  only; absent when none. Drives the flag bubble on the map pin. */
+    instanceFlags?: string[];
 }
 /**
  * Amenity - a specific type of POI (facilities, services)
@@ -195,10 +199,14 @@ interface Waypoint {
      *  "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. */
+     *  specific amenity it's rendering rather than assuming index 0.
+     *  `extensors` are per-instance flags (e.g. baby changing at this one
+     *  restroom), layered over the amenity's own `extensors`; omitted when the
+     *  instance has none. */
     amenityAssociations?: Array<{
         id: string | number;
         name: string;
+        extensors?: Record<string, string>;
     }>;
 }
 /**
@@ -1073,6 +1081,15 @@ declare const POINT_OF_INTEREST_EXTENSOR_KEY = "mm_point_of_interest";
  * `venue.buildings`.
  */
 declare const BUILDING_NAME_EXTENSOR_KEY = "mm_building_name";
+/**
+ * Per-instance amenity flags. Unlike the keys above, these ride on one
+ * placement of an amenity (JACS `amenityAssociations[].extensors`), not the
+ * amenity record, because "this restroom has a changing table" is true of one
+ * restroom, not every restroom in the venue. Values are `"true"` / `"false"`;
+ * a missing key means nobody recorded it — see `parseFlag`.
+ */
+declare const BABY_CHANGING_EXTENSOR_KEY = "mm_baby_changing";
+declare const WHEELCHAIR_ACCESSIBLE_EXTENSOR_KEY = "mm_wheelchair_accessible";
 interface DestinationPhone {
     /** Exactly as the author typed it — `"(408) 300-9294"`. Deliberately not
      *  normalised: doing that properly across international formats needs a real
@@ -1090,6 +1107,9 @@ declare function parsePhone(raw: unknown): DestinationPhone | null;
 declare function parseImageAlt(raw: unknown): string | undefined;
 /** The building name, or `undefined` when the author set none. */
 declare function parseBuildingName(raw: unknown): string | undefined;
+/** A yes/no/unknown flag. `undefined` for anything but `"true"`/`"false"` —
+ *  a missing key is "not recorded", and a kiosk must not read that as "no". */
+declare function parseFlag(raw: unknown): boolean | undefined;
 /** The point-of-interest flag. Absence means false — only the checked state is
  *  ever stored. */
 declare function parsePointOfInterest(raw: unknown): boolean;
@@ -1217,6 +1237,60 @@ declare function timeZoneAbbreviation(now?: Date, timeZone?: string): string;
  */
 declare function getOpenStatus(hours: OpenHours, now?: Date, options?: OpenStatusOptions): OpenStatus;
 
+/**
+ * Choosing among an amenity's placements by their per-instance flags
+ * (`amenityAssociations[].extensors`, e.g. "this restroom has a changing
+ * table"). Pure — the SDK feeds the result to `findClosestByWalkTime`, so a
+ * flag only ever narrows *which* instances are eligible, never how they rank.
+ *
+ * Everything here is keyed on `'true'`. "No" and "not recorded" are both "not a
+ * match": a kiosk must never send someone to a restroom nobody has verified.
+ */
+/** The instance flags a consumer can filter or build variants on, in display order. */
+declare const INSTANCE_FLAG_KEYS: readonly ["mm_baby_changing", "mm_wheelchair_accessible"];
+type InstanceFlagKey = (typeof INSTANCE_FLAG_KEYS)[number];
+/** The instance's value for one flag: `true`, `false`, or `undefined` (not recorded). */
+declare function instanceFlag(amenityId: Amenity['id'], wp: Waypoint, key: string): boolean | undefined;
+/**
+ * Why `preferAccessible` fell back to every instance:
+ * - `'none-accessible'` — instances are recorded, but none as accessible. Worth
+ *   telling the visitor.
+ * - `'not-recorded'` — nobody has recorded accessibility here yet (a venue not
+ *   backfilled). Say nothing: it's today's behaviour, and a warning on every
+ *   route would only alarm people.
+ */
+type AccessibleFallback = 'none-accessible' | 'not-recorded';
+interface AmenityInstanceChoice {
+    /** The eligible waypoints, before any walk-time ranking. */
+    waypoints: Waypoint[];
+    /** Set when `preferAccessible` found no accessible instance and fell back. */
+    fallback?: AccessibleFallback;
+}
+/**
+ * The instances to pick from: those matching `require`, then — with
+ * `preferAccessible` — only the wheelchair-accessible ones among them, falling
+ * back to all of them when there are none. `require` never falls back: a
+ * "Restroom · Baby changing" request with no flagged restroom has no answer.
+ */
+declare function chooseAmenityInstances(amenity: Amenity, opts?: {
+    require?: readonly string[];
+    preferAccessible?: boolean;
+}): AmenityInstanceChoice;
+/** A flag-specific way to ask for an amenity — "Restroom · Baby changing station". */
+interface AmenityVariant {
+    amenity: Amenity;
+    /** The instance flag this variant requires; pass it as `require: [flag]`. */
+    flag: InstanceFlagKey;
+    /** How many placements qualify. Always at least 1. */
+    instanceCount: number;
+}
+/**
+ * One variant per amenity and flag with at least one instance flagged Yes, in
+ * amenity order then `INSTANCE_FLAG_KEYS` order. A venue nobody has backfilled
+ * yields none, so consumers can ship variant rows before the data exists.
+ */
+declare function amenityVariants(amenities: readonly Amenity[]): AmenityVariant[];
+
 /** One floor of the active route, drawn on its own for a printout. */
 type RouteFloorImage = {
     floor: Floor;
@@ -1766,6 +1840,14 @@ declare class MinuteMaps {
      * refetch and no re-compositing.
      */
     private serveMissingStyleImage;
+    /**
+     * Compose a pin-plus-flag-bubble image (`map/flagBadge.ts`) from the pin's
+     * own registered image. Uploaded and curated icons register asynchronously
+     * during `init`, and a sprite sheet may still be loading, so a base that
+     * isn't on the map yet is retried for a few seconds rather than given up on —
+     * giving up would leave a flagged pin blank for the whole session.
+     */
+    private serveFlaggedIcon;
     on(event: string, cb: (e: MapEvent) => void): void;
     off(event: string, cb?: (e: MapEvent) => void): void;
     addControl(control: IControl, position?: ControlPosition): void;
@@ -2104,6 +2186,13 @@ declare class MinuteMaps {
          *  tick if the UI stays on screen. The raw string also remains in
          *  `properties` for consumers that would rather parse it themselves. */
         openHours?: OpenHours;
+        /** This placement has a baby changing station (`mm_baby_changing`).
+         *  Amenity instances only. `undefined` means not recorded — render
+         *  nothing rather than "No". */
+        babyChanging?: boolean;
+        /** This placement is wheelchair accessible (`mm_wheelchair_accessible`).
+         *  Amenity instances only; same `undefined` = not recorded rule. */
+        wheelchairAccessible?: boolean;
     };
     /** Resolve the source Destination/Amenity record backing a rendered POI,
      *  for detail fields (category, localized description) that don't live on
@@ -2760,6 +2849,29 @@ declare class MinuteMaps {
     findClosestByWalkTime<T>(items: readonly T[], toWaypoint: (item: T) => Waypoint | null | undefined, opts?: {
         avoidStairs?: boolean;
     }): T | null;
+    /**
+     * Flag-specific ways to ask for an amenity — one per amenity and instance
+     * flag with at least one placement flagged Yes ("Restroom · Baby changing
+     * station"). Route one with `navigateFromKioskToClosestAmenity(amenity.id,
+     * { require: [variant.flag] })`. Empty for a venue whose instances carry no
+     * flags yet, so a consumer can render variant rows before the backfill.
+     */
+    getAmenityVariants(): AmenityVariant[];
+    /**
+     * The placements of an amenity eligible for a request, before walk-time
+     * ranking: only those with every `require` flag set to Yes, then — with
+     * `preferAccessible` — only the wheelchair-accessible ones among them,
+     * falling back to all of them (see `fallback`) when none are. `null` for an
+     * unknown amenity.
+     *
+     * The routing and highlight calls use this internally; a consumer collapsing
+     * search results to one instance per amenity should rank this list with
+     * `findClosestByWalkTime` so its pick matches the route.
+     */
+    getAmenityInstances(amenityId: string | number, options?: {
+        require?: readonly string[];
+        preferAccessible?: boolean;
+    }): AmenityInstanceChoice | null;
     /**
      * Route from the kiosk to the closest physical instance of an amenity.
      * Resolves the amenity venue-wide, picks the instance with the smallest
@@ -2775,9 +2887,15 @@ declare class MinuteMaps {
      * 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.
+     *
+     * `require` and `preferAccessible` narrow which instances are eligible
+     * before the pick — see `getAmenityInstances`. A `require` nothing matches
+     * routes nowhere (and warns) rather than to an unverified instance.
      */
     navigateFromKioskToClosestAmenity(amenityId: string | number, options?: {
         avoidStairs?: boolean;
+        require?: readonly string[];
+        preferAccessible?: boolean;
     }): Promise<any>;
     /**
      * Highlight + center on the closest physical instance of an amenity.
@@ -2788,9 +2906,13 @@ declare class MinuteMaps {
      * This is the right call from a venue-wide list ("here are all the
      * bathrooms in the building, take me to the closest one"). For taps on
      * a specific resolved POI (e.g. a search result that already names one
-     * instance), use `highlightPOI` instead.
+     * instance), use `highlightPOI` instead. `require` / `preferAccessible`
+     * narrow the eligible instances as in `navigateFromKioskToClosestAmenity`.
      */
-    highlightAmenity(amenityId: string | number): Promise<void>;
+    highlightAmenity(amenityId: string | number, options?: {
+        require?: readonly string[];
+        preferAccessible?: boolean;
+    }): Promise<void>;
     /** Which floor owns this waypoint, by matching mapId against the floor's
      *  `mapId` (or `id` as fallback). Used to switch floors when routing /
      *  highlighting hits an instance on a different one. */
@@ -3100,5 +3222,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, 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 };
+export { BABY_CHANGING_EXTENSOR_KEY, BUILDING_NAME_EXTENSOR_KEY, DAY_KEYS, IMAGE_ALT_EXTENSOR_KEY, INSTANCE_FLAG_KEYS, 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, WHEELCHAIR_ACCESSIBLE_EXTENSOR_KEY, activeSectionIndex, amenityVariants, chooseAmenityInstances, createMinuteMapsSDK, customerDisplayName, dayKeyAt, getOpenStatus, groupStepsIntoFloorSections, instanceFlag, isConnectorAmenity, isMapLocation, parseBuildingName, parseFlag, parseImageAlt, parseOpenHours, parsePhone, parsePointOfInterest, resolveAmenityIconSource, resolveSnapshotLocale, timeZoneAbbreviation };
+export type { AccessibleFallback, Amenity, AmenityBadgeStyle, AmenityInstanceChoice, AmenityVariant, AmenityWithFloor, Bounds, BoundsPadding, CameraState, Customer, CustomerVenues, DayKey, Destination, DestinationPhone, EventCallback, Floor, FloorMetadata, HoursRange, InstanceFlagKey, 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 };