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

package/dist/index.d.ts

@@ -233,6 +233,11 @@ interface Zone {
     /** Authored hex color (e.g. "#d32f2f"); may be empty when the author
      *  hasn't picked one — such zones are skipped for color-coding. */
     color: string;
+    /** The color this zone's rooms are drawn in under the active theme — `color`
+     *  in the default theme, its high-contrast palette entry under high contrast.
+     *  Use this, not `color`, for a legend swatch, and re-read it on
+     *  `themeChanged`. Set on `getZones()` results only. */
+    displayColor?: string;
     description?: string;
 }
 
@@ -348,7 +353,7 @@ interface MapEvent {
     venue?: any;
     camera?: CameraState;
     /** Emitted by `themeChanged`; `'custom'` when consumer passed a raw style. */
-    theme?: 'default' | 'high-contrast' | 'custom';
+    theme?: 'default' | 'high-contrast' | 'color-blind' | 'custom';
     /** Emitted by `localeChanged` after `setLocale()` finishes patching the
      *  venue model. BCP-47 code (`'en'`, `'es'`, `'es-MX'`). */
     locale?: string;
@@ -383,7 +388,7 @@ type BoundsPadding = number | {
  * `options.theme` init option. Pass a `StyleSpecification` directly for
  * custom themes.
  */
-type ThemeName = 'default' | 'high-contrast';
+type ThemeName = 'default' | 'high-contrast' | 'color-blind';
 /**
  * Style of the disc + ring rendered behind each amenity icon. The SDK
  * composites this into the icon bitmap at registration time, so badge +
@@ -414,7 +419,10 @@ interface SDKOptions {
     debugGlobal?: string | false;
     /**
      * Initial theme. `'default'` uses the bundled hybrid 3D theme.
-     * `'high-contrast'` uses the WCAG-AA tuned theme. Pass a
+     * `'high-contrast'` uses the WCAG-AA tuned theme. `'color-blind'` keeps the
+     * default look but swaps the colors that red-green and blue-yellow color
+     * blindness merge (the route, room categories and department zones,
+     * restrooms, parks). Pass a
      * `StyleSpecification` for fully custom styling.
      */
     theme?: ThemeName | any;
@@ -1073,6 +1081,24 @@ interface OpenStatusOptions {
  * wrong answer at a kiosk is worse than a missing one.
  */
 declare function parseOpenHours(raw: unknown): OpenHours | null;
+/**
+ * The weekday `now` falls on in `timeZone` (host clock when omitted or
+ * unrecognised) — the same day `getOpenStatus` evaluates against. Exported so
+ * a week table can highlight "today" without disagreeing with the status line
+ * around the venue's midnight.
+ */
+declare function dayKeyAt(now: Date, timeZone?: string): DayKey;
+/**
+ * A short label for `timeZone` (host zone when omitted or unrecognised) — the
+ * zone `getOpenStatus` reads hours against — so a UI can say "Opens 9:00 AM ET".
+ *
+ * US zones get the generic form (`ET`, `CT`, `MT`, `PT`, `AKT`), which doesn't
+ * flip with daylight saving. Elsewhere the engine has no generic abbreviation
+ * (it would spell out "Germany Time"), so this falls back to the specific short
+ * name, which may be an offset (`GMT+2`). `now` only matters for that fallback
+ * and for zones like Phoenix that print `MST` year-round.
+ */
+declare function timeZoneAbbreviation(now?: Date, timeZone?: string): string;
 /**
  * The live open/closed state for a parsed week.
  *
@@ -1083,10 +1109,32 @@ declare function parseOpenHours(raw: unknown): OpenHours | null;
  *
  * Hours carry no timezone of their own, so they are read against the host clock
  * unless `options.timeZone` names the venue's zone. The kiosk case needs no
- * option: the machine stands in the building it is describing.
+ * option: the machine stands in the building it is describing. A web consumer
+ * whose visitors may be elsewhere should resolve the venue's zone (e.g. from
+ * `MinuteMaps.getVenueCenter()`) and pass it.
  */
 declare function getOpenStatus(hours: OpenHours, now?: Date, options?: OpenStatusOptions): OpenStatus;
 
+/** One floor of the active route, drawn on its own for a printout. */
+type RouteFloorImage = {
+    floor: Floor;
+    /** The bare map canvas (no DOM chrome), as a `data:` URL. */
+    dataUrl: string;
+};
+type RouteImageOptions = {
+    /** CSS-pixel size the map is laid out at while capturing. Default 1200×800. */
+    width?: number;
+    height?: number;
+    /** Canvas pixels per CSS pixel. Default 2, crisp enough for paper. */
+    pixelRatio?: number;
+    /** Padding around each floor's route segment, in CSS px. Default 40. */
+    padding?: number;
+    /** Image MIME type passed to `toDataURL`. Default `'image/png'`. */
+    type?: string;
+    /** Encoder quality for lossy types (`'image/jpeg'`, `'image/webp'`). */
+    quality?: number;
+};
+
 type JacsProviderConfig = {
     mode: 'proxy';
     proxyBaseUrl?: string;
@@ -1404,6 +1452,8 @@ declare class SnapshotProvider implements JacsReader {
     private fetchJson;
 }
 
+/** A built-in theme name, or `'custom'` when a raw style was passed. */
+type ActiveThemeName = ThemeName | 'custom';
 declare class MinuteMaps {
     private config;
     private map;
@@ -1461,8 +1511,9 @@ declare class MinuteMaps {
     /** Multiplier applied to every theme label's `text-size`, mutable via
      *  `setTextScale`. Re-applied after every `setTheme()` swap. */
     private textScale;
-    /** Each label layer's unscaled `text-size`, captured by `setTextScale`.
-     *  Cleared on `setTheme()` — the recreated layers carry new base values. */
+    /** Each label layer's unscaled `text-size` and em offsets, captured by
+     *  `setTextScale` and keyed `"<layer id>|<property>"`. Cleared on
+     *  `setTheme()` — the recreated layers carry new base values. */
     private baseTextSizes;
     /** Tracks the active theme name so `setTheme()` is a no-op when re-requested. */
     private activeThemeName;
@@ -1478,6 +1529,9 @@ declare class MinuteMaps {
      *  step rides — empty unless `setActiveStep` is on a transition. Drives
      *  `applyRouteConnectorHighlight`. */
     private activeTransitionWaypointIds;
+    /** Set while `captureRouteFloorImages` runs; holds the bounds padding to
+     *  put back afterwards (updated by any `setBoundsPadding` in between). */
+    private routeCapture;
     private amenityManager;
     private wayfinding;
     private highlightManager;
@@ -1511,6 +1565,12 @@ declare class MinuteMaps {
      *  fresh insets, the same way it already re-fits an active route. Cleared by
      *  `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
+     *  `selectedCoordinates` so a `setBoundsPadding` re-nudge carries the same
+     *  zoom instead of cancelling the zoom-in halfway. Cleared with it. */
+    private selectedMinZoom;
     private youAreHerePulse;
     /** Theme layers whose features represent a tappable destination/amenity.
      *  A click hit-tests these (see `SelectionManager`) → `poiSelected`. The
@@ -1651,16 +1711,62 @@ declare class MinuteMaps {
      */
     private registerRuntimeIcons;
     /**
-     * Set the active map theme by name (`'default'` / `'high-contrast'`) or by
+     * Set the active map theme by name (`'default'` / `'high-contrast'` /
+     * `'color-blind'`) or by
      * passing a custom `StyleSpecification`. The current floor, route, POIs
      * and camera are preserved across the swap — only layer styling changes.
      *
      * Used by kiosk consumers to wire the OS-level / popover high-contrast
      * toggle to the map. See `KIOSK.md` for the pattern.
+     *
+     * Switching between the two built-in themes happens in place (paint
+     * properties plus the sprite — see `swapBuiltinThemeInPlace`); a custom style,
+     * or leaving one, rebuilds the style with `setStyle`. Calls run one at a time
+     * in the order made, so a quick double toggle can't interleave two swaps.
      */
     setTheme(theme: ThemeName | StyleSpecification): Promise<void>;
+    /** Tail of the `setTheme` queue. */
+    private themeQueue;
+    private applyTheme;
+    /**
+     * Switch between built-in themes without `setStyle`. They share every layer
+     * and differ only in paint and sprite (high contrast and color-blind are
+     * derived from hybrid — see `themes/`), so this rewrites the paint
+     * properties that differ and points the map at the other sprite sheet.
+     * Sources, filters, zoom ranges, layout overrides (text scale, dyslexic font)
+     * and the selection's destination focus are untouched, so unlike the
+     * `setStyle` path there is nothing to capture and restore.
+     *
+     * Returns `false`, having changed nothing, when the two themes differ in
+     * anything paint can't express; the caller then falls back to `setStyle`.
+     */
+    private swapBuiltinThemeInPlace;
+    /** Room layers whose color a zone palette replaces. The
+     *  highlight pair is here so a selected room's raised block keeps its
+     *  palette color instead of reverting to the authored one. */
+    private static readonly ZONE_PAINT_TARGETS;
+    /** Zone id → palette fill for `themeName`, over the zones in use (see
+     *  `assignZonePaletteColors` for why only those), or `null` for a theme that
+     *  draws the authored colors. */
+    private paletteZoneColors;
+    /**
+     * Under a theme with a zone palette (high contrast, color-blind), color each
+     * zoned room from it, keeping the theme's own value for everything else.
+     * Under the default theme, write the theme's own value back: its expression
+     * already tints by the authored `zoneColor`, and an in-place swap away from
+     * color-blind wouldn't reset these layers otherwise, since the two static
+     * themes' unit fills are identical and `diffThemePaint` skips them.
+     *
+     * Writes the room layers' paint, so it must run before `setUnitFocusDim(true)`
+     * captures them — otherwise clearing the selection would hand back the
+     * palette-less value.
+     */
+    private applyZonePaint;
+    /** The color a zone's rooms are drawn in under the active theme: its palette
+     *  entry under high contrast or color-blind, its authored color otherwise. */
+    private zoneDisplayColor;
     /** Currently active theme name (or `'custom'` when a raw style was passed). */
-    getActiveTheme(): 'default' | 'high-contrast' | 'custom';
+    getActiveTheme(): ActiveThemeName;
     /**
      * Update the SDK's reduced-motion preference at runtime. When true, every
      * imperative camera move (`setView`, `resetView`, `refit`, recenter, route
@@ -1704,6 +1810,10 @@ declare class MinuteMaps {
      * wrapped), so zoom interpolation and data-driven sizing keep working. Re-applied after
      * `setTheme()`, since `setStyle({ diff: false })` recreates every layer from
      * the pristine theme JSON. Non-finite or non-positive values reset to 1.
+     *
+     * The em-based `text-offset` / `text-variable-anchor-offset` are divided by
+     * the same factor, so each label keeps its pixel distance from an icon that
+     * doesn't scale (see `scaleTextEmOffset`).
      */
     setTextScale(scale: number): void;
     getTextScale(): number;
@@ -1761,6 +1871,28 @@ declare class MinuteMaps {
     setFlatMode(enabled: boolean): void;
     toggleFlatMode(): void;
     getIsFlatMode(): boolean;
+    /**
+     * Street address of the venue, from its first JACS building's `address`.
+     * The CMS's Edit Venue form saves its Address field there, since it binds a
+     * venue to a single building. `null` before the venue loads or when the
+     * address is blank. In the venue's default language: `/all` ignores
+     * `?locale=` and the locale refetch doesn't cover buildings.
+     */
+    getVenueAddress(): string | null;
+    /**
+     * Description of the venue, from its first JACS building's `description` —
+     * stored there by the CMS's Edit Venue form, like `getVenueAddress()`.
+     * `null` before the venue loads or when the description is blank. Same
+     * locale caveat: always the venue's default language.
+     */
+    getVenueDescription(): string | null;
+    /**
+     * Center of the venue's bounds as `[lng, lat]`. `null` before the venue
+     * loads or when it has no coordinates. JACS records no time zone, so a
+     * consumer whose visitors may be outside the venue's zone resolves one from
+     * this point and passes it to `getOpenStatus` / `dayKeyAt`.
+     */
+    getVenueCenter(): [number, number] | null;
     getFloors(): Floor[];
     getCurrentFloor(): Floor | null;
     getDefaultFloor(): Floor | null;
@@ -1784,12 +1916,14 @@ declare class MinuteMaps {
         floorShortName?: string;
         zoneName?: string;
         zoneDescription?: string;
-        /** The department's authored hex colour (`Zone.color`) — the same value
-         *  that tints this room's polygon on the map, so a consumer can print a
-         *  swatch beside the department name and connect the two. Absent when the
-         *  author never picked one, which is also when the map leaves the room
-         *  untinted; treat "no colour" as "this department isn't colour-coded",
-         *  not as "fall back to a default swatch". */
+        /** The colour that tints this room's polygon on the map under the active
+         *  theme — the department's authored `Zone.color`, or its high-contrast
+         *  palette entry under high contrast (`Zone.displayColor`) — so a consumer
+         *  can print a swatch beside the department name and connect the two.
+         *  Re-read it on `themeChanged`. Absent when the author never picked one,
+         *  which is also when the map leaves the room untinted; treat "no colour"
+         *  as "this department isn't colour-coded", not as "fall back to a default
+         *  swatch". */
         zoneColor?: string;
         keywords?: string[];
         description?: string;
@@ -2074,10 +2208,26 @@ declare class MinuteMaps {
      * instead swap the connector(s) the step rides to their highlighted
      * sprite badge (`CONNECTOR_HIGHLIGHTED_ICON_SUFFIX`).
      *
+     * `opts.fit` moves the camera too:
+     * - `'step'` frames just this step (zoomed no closer than
+     *   `ROUTE_STEP_FIT_MAX_ZOOM`) instead of the floor's whole segment, and
+     *   keeps framing it through later re-fits — `setBoundsPadding` as the
+     *   consumer's directions card resizes, a floor switch back to the step's
+     *   floor — until another fit or a new route.
+     * - `'route'` goes back to the route's own framing (its floor segment),
+     *   as when it was first drawn — e.g. a "Restart" on the first step.
+     *
+     * Omitted, the camera is left alone, so a route's first framing stays
+     * the whole route.
+     *
      * Pass `null` to clear the highlight without changing the floor or
      * tearing down the route.
      */
-    setActiveStep(step: WayfindStep | null): Promise<void>;
+    setActiveStep(step: WayfindStep | null, opts?: {
+        fit?: 'step' | 'route';
+    }): Promise<void>;
+    /** The coordinates of `step`'s point range, for the camera to frame. */
+    private stepFocusFor;
     private writeActiveStepHighlight;
     private clearActiveStepHighlight;
     /**
@@ -2091,6 +2241,24 @@ declare class MinuteMaps {
      * that predates the variant) rather than drawing nothing.
      */
     private applyRouteConnectorHighlight;
+    /**
+     * Draw each floor the active route crosses, in route order, and return
+     * one image per floor — for printing directions.
+     *
+     * Images are the map canvas alone, so the consumer's DOM chrome (panels,
+     * 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
+     * map behind a loading screen while this runs; the visitor would
+     * otherwise see it jump between floors.
+     *
+     * The step highlight is cleared, not restored: call `setActiveStep`
+     * again with the step your UI is showing. Resolves to `[]` when no route
+     * is displayed.
+     */
+    captureRouteFloorImages(opts?: RouteImageOptions): Promise<RouteFloorImage[]>;
     clearRoute(): void;
     /**
      * Put the end-of-route marker on `poi`, or take it down (`null`). With
@@ -2124,8 +2292,10 @@ declare class MinuteMaps {
      *
      * This is deliberately *not* `highlightPOI`, which is the search-locate
      * gesture — it zooms and recenters and draws a pulsing ring, and emits
-     * nothing. Selection is the quieter one: current zoom kept, no ring, the
-     * raised room is the indicator.
+     * 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.
      *
      * Accepts a `POI` (preferred — its `type` and `waypointId` pin down the exact
      * instance, which matters for an amenity that shares one id across every
@@ -2206,7 +2376,8 @@ declare class MinuteMaps {
     /** 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,
-     *  so it reads as a nudge, not a recenter. */
+     *  so it reads as a nudge, not a recenter — unless `selectedMinZoom` is set
+     *  and the camera is further out, in which case it zooms in to that floor. */
     private easeToSelection;
     /** Dim every unit's paint (or restore it) so a selected room reads as the
      *  focus. Idempotent: capturing only happens on the first activate, and the
@@ -2652,5 +2823,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, getOpenStatus, groupStepsIntoFloorSections, isConnectorAmenity, parseBuildingName, parseImageAlt, parseOpenHours, parsePhone, parsePointOfInterest, resolveAmenityIconSource, resolveSnapshotLocale };
-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, RouteFloorSection, 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, 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 };