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

package/dist/react.d.ts

@@ -1,14 +1,350 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
+interface POI {
+    /** Unique identifier */
+    id: string | number;
+    /** POI type */
+    type: 'amenity' | 'destination' | 'kiosk';
+    /** Display name */
+    name: string;
+    /** Geographic coordinates [longitude, latitude] */
+    coordinates: [number, number];
+    /** Icon identifier for rendering */
+    iconId?: string;
+    /** Whether this POI should render its label */
+    showLabel?: boolean;
+    /** Floor this POI belongs to */
+    floorId: string | number;
+    /** Category/type of amenity (e.g., 'restroom', 'elevator') */
+    amenityType?: string;
+    /** Locale-stable classification text (name + type + keywords, frozen at
+     *  load before any locale patch can translate them). Copied from the
+     *  source `Amenity.classifyText`; used by `amenityCategoryFor`/rank
+     *  instead of the live, possibly-translated fields. See `Amenity.classifyText`. */
+    classifyText?: string;
+    /** Which amenity icon layer this POI renders in — `'connector'`,
+     *  `'entrance'`, `'parking'`, `'bus'`, `'information'` 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' | 'information' | 'other';
+    /** Search keywords */
+    keywords?: string[];
+    /** Additional properties */
+    properties?: Record<string, unknown>;
+    /** JMap waypoint ID that this POI instance is bound to */
+    waypointId?: string | number;
+    /** Full waypoint object for this POI instance */
+    waypoint?: Waypoint;
+    /** Marks this POI as the "You are here" kiosk */
+    isYouAreHere?: boolean;
+    /** For kiosk POIs only: compass heading the device physically faces, in
+     *  degrees clockwise from north. Sourced from JACS `Device.heading`. */
+    heading?: number | null;
+    /** Per-instance name for this specific placement of an amenity (e.g.
+     *  "Parking Lot A" for a "Parking" amenity), resolved from the waypoint's
+     *  `amenityAssociations`. Distinct from `name`, which is the amenity's
+     *  type-level name shared by every instance — see `Amenity.name`. Amenities
+     *  only, and only set when JACS actually returned an instance name. */
+    instanceName?: string;
+}
+/**
+ * Waypoint - a specific point location
+ */
+interface Waypoint {
+    /** Geographic coordinates [longitude, latitude] */
+    coordinates: number[];
+    /** Associated map ID */
+    mapId: string | number;
+    /** Associated floor ID */
+    floorId?: string | number;
+    /** Whether this is the primary/default waypoint */
+    isPrimary?: boolean;
+    /** CMS zone (department) this waypoint belongs to, if any. The only backend
+     *  link between a location and its department — read at runtime across the
+     *  data provider (see the package CLAUDE.md zone landmine). */
+    zoneId?: string | number;
+    /** Per-instance names JACS attaches to this waypoint's amenities (e.g. a
+     *  "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. */
+    amenityAssociations?: Array<{
+        id: string | number;
+        name: string;
+    }>;
+}
+
+/** SW/NE bounding box */
+type Bounds = [[number, number], [number, number]];
+
+/**
+ * Padding kept clear inside the viewport when the SDK frames bounds —
+ * the initial venue/floor fit and the wayfinding route fit. A plain
+ * number pads all sides equally; the object form lets a kiosk reserve
+ * space for fixed UI overlays (header, dock, side rails) so framed
+ * content is never hidden behind them.
+ */
+type BoundsPadding = number | {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+};
+/**
+ * Built-in theme names accepted by `MinuteMaps.setTheme()` and the
+ * `options.theme` init option. Pass a `StyleSpecification` directly for
+ * custom themes.
+ */
+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 +
+ * 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;
+    /** Extra inset between the icon and the badge's inner edge, in logical px
+     *  (applied on all sides). Default `0` — the icon fills ~85% of the disc
+     *  as before. Raise this if an icon's own artwork reaches close to its
+     *  viewBox edges and ends up touching the ring. */
+    padding?: number;
+};
 interface SDKOptions {
     debug?: boolean;
-    theme?: 'light' | 'dark' | 'hybrid' | any;
+    /**
+     * `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. `'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;
+    /**
+     * When true, the SDK skips animations on imperative camera calls
+     * (wayfinding fits, `setView`, idle re-frames). Consumers should
+     * mirror their app's `prefers-reduced-motion` state into this.
+     */
+    reducedMotion?: boolean;
+    /**
+     * Whether a freshly computed route auto-highlights its first step's
+     * segment (the brighter `route-line-active` overlay). Defaults to
+     * `true`, preserving the turn-by-turn segment highlight that
+     * `setActiveStep` drives.
+     *
+     * Set `false` for kiosk-style "show the whole route at once" UIs:
+     * the entire route line is shown without singling out one segment,
+     * which reads more clearly at a glance and avoids implying the visitor
+     * must step through the route. `setActiveStep` still works when called
+     * explicitly (e.g. a paginated QR-handoff / mobile flow) — this only
+     * controls the automatic highlight on `routeReady`.
+     */
+    routeStepHighlight?: boolean;
+    /**
+     * Which way is up while a route is on screen. Defaults to `'kiosk'`.
+     *
+     * - `'kiosk'` — the kiosk's heading rotated 180°, so the map matches the
+     *   direction a visitor walks away from the screen (180°, south-up, when
+     *   the venue has no kiosk heading).
+     * - `'first-step'` — the direction of the route's first step: the tapped
+     *   start's approach when there is one, otherwise the first stretch of
+     *   the path. For UIs viewed away from any kiosk (a phone, a home
+     *   computer), where the kiosk's facing means nothing. Taken once per
+     *   route, so stepping through it or toggling the full route keeps that
+     *   orientation.
+     */
+    routeBearing?: 'kiosk' | 'first-step';
+    /**
+     * Whether restroom pins that are too close together to draw individually
+     * collapse into a single Material `wc` badge. Defaults to `true`.
+     *
+     * Venues author men's and women's restrooms as two amenities a few metres
+     * apart. Both are wayfinding-critical (rank 0) and both draw on a layer that
+     * doesn't allow icon overlap, so without this MapLibre resolves the collision
+     * by hiding one of them outright until the camera is very close in. Grouping
+     * shows one badge in their place and hands back *all* the members when it's
+     * tapped, so the consumer can offer directions to each.
+     *
+     * Set `false` to opt out and get the raw collision behaviour back.
+     */
+    groupRestroomIcons?: boolean;
     initialFloor?: string | number;
     enableInteractions?: boolean;
     customSprite?: string;
     minIndoorZoom?: number;
+    /**
+     * How far, in **metres** (default `0.3`, ≈1 ft), extruded interior polygons
+     * (restrooms, back-of-house, obstacles, connectors) are inset so their edges
+     * don't z-fight the neighbouring room block. A polygon too thin to survive
+     * the inset (it would keep under half its area, e.g. a ~0.3 m back-of-house
+     * perimeter band) is left at its original size rather than erased. Metres to match the theme's
+     * `fill-extrusion-height` values, which MapLibre defines in metres — unlike
+     * the distances shown to visitors, which are in feet. Was feet before this
+     * option changed units; a value of `1` is now ~3.3× thicker.
+     */
     wallThickness?: number;
-    boundsPadding?: number;
+    /**
+     * How much costlier a candidate on a **different floor** from the kiosk is
+     * treated when choosing the closest instance of an amenity (default `1.5`).
+     * Used by `findClosestByWalkTime`, and so by `navigateFromKioskToClosestAmenity`
+     * and `highlightAmenity`.
+     *
+     * A multiplier on the trip's effort — walk time plus the elevator wait — not
+     * a distance: `1.5` means another floor's instance has to be a third cheaper
+     * to beat one on the kiosk's floor. It is a *preference* for not making the
+     * visitor change floors, layered on top of the physical cost of doing so
+     * (which is already in the effort). `1` turns it off and ranks by effort
+     * alone; a value below `1` is treated as `1`. It only affects which instance
+     * is chosen — never a route.
+     *
+     * For scale: at the Las Vegas VA the nearest other-floor Lactation Pod costs
+     * ~400 ft-equivalent against ~530 for the one on the kiosk's floor, so it
+     * takes a value above ~1.32 to keep the visitor on their floor.
+     */
+    otherFloorPenalty?: number;
+    boundsPadding?: BoundsPadding;
+    /**
+     * Caps how far a visitor can pan/zoom out. By default the SDK derives this
+     * from the venue's own bounds, scaled to 3x its width/height around the
+     * same center — enough room to pan around the building without drifting
+     * into an empty, un-tiled region. The default box is never smaller than
+     * ~3.7 km a side, so a small venue isn't forced to zoom in tighter than a
+     * large one. Pass a number to use a different
+     * multiplier (e.g. `1.5` for a tighter leash), explicit `[[west, south],
+     * [east, north]]` bounds to override entirely, or `false` to disable
+     * max-bounds clamping.
+     */
+    maxBounds?: Bounds | number | false;
+    /**
+     * Hides basemap points of interest (civic and marine icons, park names) that
+     * fall within this many metres of the venue's bounds, so an OSM library or
+     * chapel on the campus isn't drawn underneath the venue's own map. Defaults
+     * to `50`. Street labels, road shields and water labels are never hidden.
+     * Pass `false` to show every basemap POI.
+     */
+    hideBasemapPoisNearVenue?: number | false;
+    /**
+     * Whether the venue's kiosk anchors a "You are here" marker, and the opening
+     * view / default route origin. Defaults to `true`. Set `false` for non-kiosk
+     * consumers (e.g. a browser map): no device is resolved, even via the
+     * "first placed device" fallback, so the marker is never drawn.
+     */
+    kiosk?: boolean;
+    /**
+     * Pitch (deg) for the opening view, applied centred on the kiosk ("You
+     * are here"). Omit for top-down.
+     */
+    initialPitch?: number;
+    /**
+     * Zoom for the opening view, centred on the kiosk. Set this above the
+     * theme's unit-walls breakpoint (~16.5 in the bundled hybrid theme) so the
+     * kiosk opens on the building's interior floor plan (its contents) rather
+     * than a zoomed-out 3D massing outline. Omit to keep the post-floor-fit
+     * 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
+     * this many zoom levels but never pull back below the interior into the
+     * massing/region. `0` locks zoom-out exactly to the opening view.
+     */
+    minZoomBelowInitialFit?: number;
+    /**
+     * Zoom-out floor expressed as ground scale: the most metres one CSS pixel
+     * may span. The SDK converts it to a `minZoom` at the venue's latitude, so
+     * every venue shows the same amount of surrounding map when fully zoomed
+     * out — a plain zoom number doesn't, because Web Mercator shows less ground
+     * per zoom level the further a venue is from the equator. Takes precedence
+     * over `minZoomBelowInitialFit`. For scale, `1.207` is zoom 15.8 at Orlando
+     * (about 2.3 km x 1.3 km on a 1920x1080 screen).
+     */
+    minZoomMetersPerPixel?: number;
+    /**
+     * 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;
+    /**
+     * Badge for vertical-circulation connectors (elevator / stairs / escalator).
+     * These render as their own visual class — a navy disc with a white glyph —
+     * so circulation reads distinct from the gold service amenities. Pass `false`
+     * to fall them back into the regular gold badge, or an object to tune the
+     * disc / ring. When `amenityBadge` is `false`, connectors are badge-less too
+     * unless this is set explicitly.
+     */
+    connectorBadge?: AmenityBadgeStyle | false;
+    /**
+     * Badge for information-desk amenities (curated `information`/`info`
+     * icon). These render as their own visual class — a green disc with a
+     * white glyph by default — so information reads distinct from the gold
+     * service amenities. Pass `false` to fall them back into the regular gold
+     * badge, or an object to tune the disc / ring. When `amenityBadge` is
+     * `false`, information icons are badge-less too unless this is set
+     * explicitly.
+     */
+    informationBadge?: AmenityBadgeStyle | false;
+    /**
+     * Glyph colour for information icons on their badge. Default white
+     * (matches `informationBadge`'s default green disc).
+     */
+    informationIconColor?: string;
+    /**
+     * Badge for the end-of-route flag (`poi-route-end-flag`) shown in place of a
+     * destination's dot while a route to it is displayed. Has its own defaults
+     * (green disc, white ring) that don't follow `amenityBadge`. Pass an object
+     * to tune the disc / ring, or `false` for the bare flag glyph with no badge.
+     * When `amenityBadge` is `false`, the flag is badge-less too unless this is
+     * set explicitly. Under the high-contrast theme the disc colour is forced to
+     * the high-contrast amenity yellow, like the amenity and connector badges.
+     */
+    routeEndBadge?: AmenityBadgeStyle | false;
+    /**
+     * Flag glyph colour on the end-of-route badge. Default white (contrasts the
+     * default green disc); doesn't follow `amenityIconColor`. Ignored under the
+     * high-contrast theme, which forces its own glyph colour.
+     */
+    routeEndIconColor?: string;
     styleMode?: 'venueStyleUrl' | 'sdkTemplate';
     templateOverrideMode?: 'colorsOnly' | 'colorsAndConstants' | 'all';
 }
@@ -24,9 +360,19 @@ type SDKConfig = {
         venueId: number;
         locale?: string;
         auth?: JMapAuth;
+        /**
+         * Identifies which physical kiosk this instance is, so the SDK can pin
+         * the "You are here" marker. Matched against either the numeric device
+         * `id` or the device `uuid` from the venue's `devices`. The device's
+         * attached waypoint (`waypoint.deviceIds`) is the kiosk's location.
+         */
+        deviceId?: string | number;
     };
     jacs: {
-        mode: 'proxy' | 'direct';
+        /** `snapshot` reads published venue snapshots from a CDN — what clients
+         *  should use. `proxy`/`direct` read live JACS (the draft): local dev and
+         *  CMS preview. */
+        mode: 'proxy' | 'direct' | 'snapshot';
         host?: string;
         auth?: {
             clientId: string;
@@ -34,13 +380,17 @@ type SDKConfig = {
             password: string;
         };
         proxyBaseUrl?: string;
+        baseUrl?: string;
     };
     options?: SDKOptions;
 };
 
-declare function MinuteMapsView({ config, className }: {
+declare function MinuteMapsView({ config, className, onSelect, }: {
     config: SDKConfig;
     className?: string;
+    /** Fired when the user taps a destination/amenity pin. `pois` holds every
+     *  POI co-located at that point (overlapping pins / a shared suite). */
+    onSelect?: (pois: POI[], coordinates: [number, number]) => void;
 }): react_jsx_runtime.JSX.Element;
 
 export { MinuteMapsView };