becomap-v2 2.0.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,603 @@
+import maplibregl from 'maplibre-gl';
+
+/**
+ * Venue data types.
+ *
+ * `Raw*` types are the provider output contract (`VenueData`) — a neutral,
+ * JSON-friendly shape both the REST adapter (editor protobuf) and the mock
+ * generator produce. The built model types add derived links and O(1)
+ * indexes and are what the rest of the SDK consumes.
+ *
+ * This module is renderer-agnostic: no three.js, no maplibre imports.
+ */
+/** [lng, lat] */
+type LngLat = [number, number];
+/** GeoJSON polygon geometry as produced by the editor (shape.json_data). */
+interface PolygonGeometry {
+    type: 'Polygon';
+    /** Outer ring first, holes after; rings are [lng, lat] positions. */
+    coordinates: LngLat[][];
+}
+/** GeoJSON line geometry — the editor emits INNER_WALL shapes as centerlines. */
+interface LineStringGeometry {
+    type: 'LineString';
+    coordinates: LngLat[];
+}
+type ShapeGeometryData = PolygonGeometry | LineStringGeometry;
+interface RawSite {
+    id: string;
+    name: string;
+    /** Initial map center; venue bounds refine this later. */
+    center: LngLat;
+}
+interface RawFloor {
+    id: string;
+    name: string;
+    /** Vertical ordering within its building (0 = ground). */
+    level: number;
+    buildingId: string;
+}
+interface RawBuilding {
+    id: string;
+    name: string;
+    floors: RawFloor[];
+}
+interface RawNode {
+    id: string;
+    lat: number;
+    lng: number;
+    floorId: string;
+    accessible: boolean;
+    privateNode: boolean;
+    /** Adjacent node ids (same-floor walkable links). */
+    siblings: string[];
+}
+/** Per-shape styling authored in the editor (Feature.properties.shapeProperties). */
+interface ShapeStyle {
+    /** Extrusion height in meters (0/0.1 = flat base, walls ~2-4.1, stores ~4). */
+    height?: number;
+    /** Wall/stroke color. */
+    color?: string;
+    /** Fill/top color. */
+    fillColor?: string;
+    /** 0..1; walls are sometimes translucent (0.6-0.8). */
+    opacity?: number;
+    /** Editor label font size. */
+    labelSize?: number;
+    /** Editor label rotation (radians). */
+    labelRotation?: number;
+}
+interface RawShape {
+    id: string;
+    floorId: string;
+    layerId: string;
+    /** Editor shape type: 'WALL' | 'INNER_WALL' | 'POLYGON' (mock uses 'polygon'). */
+    type: string;
+    geometry: ShapeGeometryData;
+    style?: ShapeStyle;
+}
+interface RawLocation {
+    id: string;
+    name: string;
+    /** Editor location type, e.g. 'tenant' | 'amenities' | 'entrance'. */
+    type: string;
+    description?: string;
+    nodeId?: string;
+    shapeId?: string;
+    amenity?: string;
+    categoryIds: string[];
+    logoUrl?: string;
+    hidden: boolean;
+    sortOrder: number;
+}
+interface RawCategory {
+    id: string;
+    name: string;
+    icon?: string;
+    sortOrder: number;
+    colorHex?: string;
+}
+interface RawMapObject {
+    id: string;
+    nodeId: string;
+    modelUrl: string;
+    scale: number;
+    rotation: number;
+    altitude: number;
+    light: number;
+}
+type FloorConnectionKind = 'elevator' | 'escalator' | 'stairs' | 'passage' | 'door' | 'ramp' | 'other';
+/**
+ * Joins two nodes (typically on different floors): elevator shafts,
+ * escalators, stairs. Mirrors the editor's connection semantics:
+ * cost = (weight > 0 ? weight : 100) * (multiplier || 1), applied per
+ * direction.
+ */
+interface RawFloorConnection {
+    id: string;
+    kind: FloorConnectionKind;
+    name?: string;
+    accessible: boolean;
+    /** 0 means "use the default cost of 100". */
+    weight: number;
+    /** 0/absent means 1. */
+    multiplier: number;
+    direction: 'both' | 'startToEnd' | 'endToStart';
+    startNodeId: string;
+    endNodeId: string;
+}
+/** Everything a provider returns; input to {@link buildVenue}. */
+interface VenueData {
+    site: RawSite;
+    buildings: RawBuilding[];
+    nodes: RawNode[];
+    shapes: RawShape[];
+    locations: RawLocation[];
+    categories: RawCategory[];
+    mapObjects: RawMapObject[];
+    floorConnections: RawFloorConnection[];
+    /** Default icon set: key (e.g. RESTROOM) -> CDN SVG url. Category
+     *  `iconFromDefaultList` keys and amenity names resolve through this. */
+    iconset?: Record<string, string>;
+}
+interface GraphEdge {
+    toNodeId: string;
+    /** Walk cost: meters for sibling edges; editor weight rule for connections. */
+    cost: number;
+    /** Whether this edge is usable on accessible routes. */
+    accessible: boolean;
+    /** Set for connection (cross-floor) edges. */
+    connectionKind?: FloorConnectionKind;
+}
+interface GraphNode {
+    id: string;
+    lng: number;
+    lat: number;
+    floorId: string;
+    accessible: boolean;
+    privateNode: boolean;
+    edges: GraphEdge[];
+}
+interface Category {
+    id: string;
+    name: string;
+    icon?: string;
+    sortOrder: number;
+    colorHex?: string;
+}
+interface Shape {
+    id: string;
+    floorId: string;
+    layerId: string;
+    type: string;
+    geometry: ShapeGeometryData;
+    style?: ShapeStyle;
+}
+interface VenueLocation {
+    id: string;
+    name: string;
+    type: string;
+    description?: string;
+    nodeId?: string;
+    shapeId?: string;
+    /** Derived from its node's (preferred) or shape's floor. */
+    floorId?: string;
+    amenity?: string;
+    categories: Category[];
+    logoUrl?: string;
+    hidden: boolean;
+    sortOrder: number;
+}
+interface MapObjectDef {
+    id: string;
+    nodeId: string;
+    modelUrl: string;
+    scale: number;
+    rotation: number;
+    altitude: number;
+    light: number;
+}
+interface Floor {
+    id: string;
+    name: string;
+    level: number;
+    buildingId: string;
+    locations: VenueLocation[];
+    shapes: Shape[];
+    nodes: GraphNode[];
+}
+interface Building {
+    id: string;
+    name: string;
+    /** Sorted by level ascending. */
+    floors: Floor[];
+}
+interface VenueStats {
+    buildings: number;
+    floors: number;
+    locations: number;
+    shapes: number;
+    nodes: number;
+    edges: number;
+    categories: number;
+    mapObjects: number;
+}
+
+/**
+ * The built, indexed venue model. Instance-scoped (never a singleton),
+ * immutable by convention after {@link buildVenue} returns.
+ */
+declare class Venue {
+    #private;
+    readonly id: string;
+    readonly name: string;
+    readonly center: [number, number];
+    readonly buildings: Building[];
+    readonly categories: Category[];
+    readonly mapObjects: MapObjectDef[];
+    /** Default icon set (key -> SVG url) — markers resolve amenity icons here. */
+    readonly iconset: Record<string, string>;
+    constructor(data: {
+        id: string;
+        name: string;
+        center: [number, number];
+        buildings: Building[];
+        categories: Category[];
+        mapObjects: MapObjectDef[];
+        iconset?: Record<string, string>;
+        nodes: GraphNode[];
+        shapes: Shape[];
+        locations: VenueLocation[];
+        edgeCount: number;
+    });
+    getBuilding(id: string): Building | undefined;
+    getFloor(id: string): Floor | undefined;
+    getLocation(id: string): VenueLocation | undefined;
+    getShape(id: string): Shape | undefined;
+    getNode(id: string): GraphNode | undefined;
+    getCategory(id: string): Category | undefined;
+    get locations(): IterableIterator<VenueLocation>;
+    get nodes(): IterableIterator<GraphNode>;
+    stats(): VenueStats;
+}
+/**
+ * Build the indexed venue model from raw provider data: derive location
+ * floors, group entities per floor, and assemble the routing graph (sibling
+ * edges with haversine costs; cross-floor edges from floor connections with
+ * kind penalties).
+ */
+declare function buildVenue(data: VenueData): Venue;
+
+/** What happens AT a step. Mirrors the v1 SDK's step-action semantics. */
+type StepAction = 'depart' | 'turn' | 'continue' | 'floorChange' | 'exitBuilding' | 'enterBuilding' | 'arrive';
+/** Which way to go at a step. `up`/`down` accompany a floor change. */
+type StepDirection = 'none' | 'straight' | 'slightLeft' | 'left' | 'uTurnLeft' | 'slightRight' | 'right' | 'uTurnRight' | 'up' | 'down';
+interface RouteStep {
+    lng: number;
+    lat: number;
+    floorId: string;
+    buildingId: string | null;
+    segmentIndex: number;
+    /** Cumulative meters from the route start (matches ribbon arc length). */
+    cumMeters: number;
+    /** Ready-to-show English instruction, built from the fields below. */
+    label: string;
+    /** Structured action, so hosts can localise or draw their own UI. */
+    action: StepAction;
+    /** Structured direction — the turn this step calls for. */
+    direction: StepDirection;
+    /** Meters covered from THIS step to the next (0 at the destination). */
+    distanceMeters: number;
+    /** Graph node this step sits on. */
+    nodeId: string;
+    /** Named location at this step, for "turn right at Zara" (null when none). */
+    landmark: string | null;
+}
+
+/**
+ * All events a {@link BecoMap} instance can emit, with their payload types.
+ * Payload shapes are placeholders in the foundation phase and are refined as
+ * features land (venue selection in Phase 5, routing in Phase 6).
+ */
+interface BecoMapEvents {
+    /** Fired once the underlying map has loaded and the SDK is ready. */
+    load: undefined;
+    /** Fired when a location is selected. */
+    select: {
+        locationId: string;
+    };
+    /** Fired when the visible floor of a building changes. */
+    floorChange: {
+        floorId: string;
+    };
+    /** Fired when the active route changes (null = route cleared). */
+    routeChange: {
+        routeId: string | null;
+    };
+    /**
+     * Fired when the route preview reaches a floor connection (null = card
+     * should hide). Apps can consume this to render their OWN instruction UI —
+     * the built-in card can be disabled via `ui.transitionCard: false`.
+     */
+    transition: {
+        kind: string;
+        toFloorId: string;
+        toFloorName: string;
+        direction: 'up' | 'down';
+        label: string;
+    } | null;
+    /**
+     * Fired whenever the active turn-by-turn step changes (null = route
+     * cleared). Carries STRUCTURED data — `action`, `direction`, `distanceMeters`
+     * — so apps can localise the instruction or render their own nav UI instead
+     * of parsing `label`.
+     */
+    step: {
+        index: number;
+        total: number;
+        label: string;
+        action: StepAction;
+        direction: StepDirection;
+        distanceMeters: number;
+        floorId: string;
+        landmark: string | null;
+        isFirst: boolean;
+        isLast: boolean;
+    } | null;
+    /** Fired on recoverable SDK errors. */
+    error: {
+        message: string;
+        cause?: unknown;
+    };
+}
+/** A listener for a single event's payload. */
+type Listener<T> = (payload: T) => void;
+
+/**
+ * Source of venue data. The REST provider talks to the beCoMap backend
+ * (editor-generated protobuf + JSON metadata); the mock provider generates a
+ * venue procedurally. Both return the same {@link VenueData} contract.
+ */
+interface VenueProvider {
+    /**
+     * Fetch everything needed to build the venue model.
+     *
+     * @param signal Abort to cancel in-flight work (the owning BecoMap aborts
+     * this on destroy()).
+     */
+    fetchVenue(signal?: AbortSignal): Promise<VenueData>;
+}
+
+/**
+ * Named colour themes for store polygons.
+ *
+ * The palettes follow what the market leaders actually ship (values read from
+ * Mappedin's own `styles.json` and Place Vendôme's abuzz scene): a very TIGHT,
+ * HIGH-KEY value range — whites and near-whites within a few percent of each
+ * other — with structure carried by soft tonal steps and one or two desaturated
+ * accents, never by dark grey. Mappedin's walls are `#ffffff`, its rooms
+ * `#f5f5f5`, its hallways `#FCFCFC`; the only saturated notes are a pale blue
+ * (`#E6F4FB`) and a warm cream (`#F5EFE0`). Heavy mid-greys are what made the
+ * earlier themes read as muddy, so nothing here goes below ~75% lightness.
+ *
+ * Every palette stays in a WARM hue family. A cool blue-grey of the same
+ * lightness reads as an untextured CAD default rather than a material: the
+ * leaders' only saturated notes are warm ones (Mappedin's `#F5EFE0` desks,
+ * Place Vendôme's `#34230e` wood), because a map surface has to suggest
+ * plaster, stone or timber to look designed rather than unfinished.
+ *
+ * - `ivory` — the DEFAULT: warm greige directory panels
+ * - `data`  — the venue's real editor colours for tops, walls and inner walls
+ */
+type PolygonThemeName = 'ivory' | 'data' | 'neutral';
+
+/** Options accepted by {@link createMap}. All fields are optional. */
+interface BecoMapOptions {
+    /**
+     * Store-polygon colour theme. `ivory` (default) is the warm directory-panel
+     * look; `data` uses the venue's real editor / category colours. `neutral`
+     * is a back-compat alias for `ivory`.
+     */
+    polygonTheme?: PolygonThemeName;
+    /** Initial map center as [lng, lat]. Defaults to [0, 0] until venue data provides one. */
+    center?: [number, number];
+    /** Initial zoom level. Defaults to 15. */
+    zoom?: number;
+    /** Initial pitch in degrees. Defaults to 0. */
+    pitch?: number;
+    /** Initial bearing in degrees. Defaults to 0. */
+    bearing?: number;
+    /** Venue data source. Without it, `map.venue.load()` rejects. */
+    venue?: {
+        provider: VenueProvider;
+    };
+    /** Built-in UI controls. */
+    ui?: {
+        /** Floor switcher control (default true). */
+        floorSwitcher?: boolean;
+        /** Route navigation bar (default true). */
+        routeBar?: boolean;
+        /** Built-in floor-connection instruction card (default true). Disable to
+         *  render your own HTML from the `transition` event. */
+        transitionCard?: boolean;
+    };
+}
+
+interface FrameStats {
+    drawCalls: number;
+    triangles: number;
+}
+
+interface BuildingView {
+    open: boolean;
+    floorId: string;
+}
+
+interface SearchResult {
+    location: VenueLocation;
+    /** Higher is better: matched tokens + full-prefix bonuses. */
+    score: number;
+}
+
+interface NavStepInfo {
+    index: number;
+    total: number;
+    label: string;
+    isFirst: boolean;
+    isLast: boolean;
+    /** Structured action — localise or draw your own UI from this, not the label. */
+    action: StepAction;
+    /** Structured direction (turn / up / down). */
+    direction: StepDirection;
+    /** Meters covered from this step to the next (0 at the destination). */
+    distanceMeters: number;
+    /** Floor this step is on. */
+    floorId: string;
+    /** Named location at this step, when the step sits on one. */
+    landmark: string | null;
+}
+
+/**
+ * Namespaced facade stubs. Each facade is a typed surface whose methods are
+ * filled in by later phases; until then they throw a descriptive error so
+ * consumers get a clear signal instead of silent no-ops.
+ */
+
+/** Venue data access: loading and model lookups. */
+interface VenueFacade {
+    /** Fetch venue data via the configured provider and build the model. */
+    load(): Promise<VenueStats>;
+    /** The built venue model, or null before {@link VenueFacade.load} resolves. */
+    current(): Venue | null;
+    /** Convenience: model stats, or null before load. */
+    stats(): VenueStats | null;
+}
+/** Floor visibility and selection (live since Phase 4). */
+interface FloorsFacade {
+    /** Show a floor (opens its building if sealed, focuses it). */
+    select(floorId: string): void;
+    /** Building whose floors the built-in switcher controls. */
+    focusedBuildingId(): string | null;
+    /** Current LOD view of a building (sealed vs open + visible floor). */
+    viewOf(buildingId: string): BuildingView | undefined;
+}
+/** Location search (live since Phase 5). */
+interface SearchFacade {
+    /** Token-prefix search over names and categories (diacritic-insensitive, non-blocking). */
+    query(text: string): Promise<SearchResult[]>;
+    /** All visible locations in a category, sorted. */
+    byCategory(categoryId: string): VenueLocation[];
+}
+interface RouteInfo {
+    /** Total walking distance in meters. */
+    distanceMeters: number;
+    /** Number of turn-by-turn steps. */
+    stepCount: number;
+}
+/** Routing and navigation (live since Phase 6). */
+interface RoutingFacade {
+    /** Compute + render + preview a route between two locations. */
+    route(fromLocationId: string, toLocationId: string, options?: {
+        accessibleOnly?: boolean;
+    }): Promise<RouteInfo>;
+    /** Clear the active route (the ONLY way besides the route bar ✕). */
+    clear(): void;
+    /** Replay the runner preview along the active route. */
+    preview(): void;
+    /** Step navigation (mirrors the built-in route bar). */
+    next(): void;
+    previous(): void;
+    stepInfo(): NavStepInfo | null;
+    active(): boolean;
+}
+/** Camera control helpers (live since Phase 5). */
+interface CameraFacade {
+    /** Fit the camera to the loaded venue's extents. */
+    focusVenue(options?: {
+        pitch?: number;
+        duration?: number;
+    }): void;
+    /** Fly to a location, opening its building/floor if needed. */
+    focusTo(locationId: string): void;
+}
+
+/**
+ * The public handle returned by {@link createMap}. Everything a consumer can
+ * do goes through this interface — the implementing class is internal.
+ */
+interface BecoMap {
+    /** Subscribe to an SDK event. Subscribing to `load` after the map has loaded fires immediately. */
+    on<K extends keyof BecoMapEvents>(event: K, listener: Listener<BecoMapEvents[K]>): void;
+    /** Unsubscribe a listener previously passed to {@link BecoMap.on}. */
+    off<K extends keyof BecoMapEvents>(event: K, listener: Listener<BecoMapEvents[K]>): void;
+    /** Tear down the map, its WebGL context, and all listeners. */
+    destroy(): void;
+    /** Debug: last frame's draw calls/triangles from the unified 3D layer. */
+    getFrameStats(): FrameStats;
+    /** The underlying MapLibre GL map, for advanced camera/interaction control. */
+    getMapLibreMap(): maplibregl.Map;
+    /**
+     * Switch the store-polygon colour theme at runtime: `ivory` (the default
+     * warm directory panels) or `data` (the venue's real editor / category
+     * colours). `neutral` is a back-compat alias for `ivory`.
+     */
+    setPolygonTheme(theme: PolygonThemeName): void;
+    /** Select a location programmatically (highlight + popup + `select` event). */
+    selectLocation(locationId: string): void;
+    /** Clear the current selection (no event; deselect event may come later). */
+    clearSelection(): void;
+    /** Venue data access (Phase 2). */
+    readonly venue: VenueFacade;
+    /** Floor selection and LOD views (Phase 4). */
+    readonly floors: FloorsFacade;
+    /** Location search (Phase 5). */
+    readonly search: SearchFacade;
+    /** Routing and navigation (Phase 6). */
+    readonly routing: RoutingFacade;
+    /** Camera helpers. */
+    readonly camera: CameraFacade;
+}
+/**
+ * Create a beCoMap instance inside the given container element.
+ *
+ * @example
+ * ```ts
+ * import { createMap } from 'becomap';
+ * const map = createMap(document.getElementById('map')!, { zoom: 16 });
+ * map.on('load', () => console.log('ready'));
+ * ```
+ */
+declare function createMap(container: HTMLElement, options?: BecoMapOptions): BecoMap;
+
+declare class MockVenueProvider implements VenueProvider {
+    #private;
+    /**
+     * @param options.stress Tile the campus stress×stress (default 1). Used to
+     * exceed venue-scale polygon counts for performance verification.
+     */
+    constructor(options?: {
+        seed?: number;
+        stress?: number;
+    });
+    fetchVenue(): Promise<VenueData>;
+}
+
+interface RestVenueProviderOptions {
+    baseUrl: string;
+    siteId: string;
+    clientId: string;
+    clientSecret: string;
+}
+/**
+ * Loads a venue from the beCoMap backend: token auth, site + floors + floor
+ * connections via JSON, and the five editor-generated protobuf binaries via
+ * the absolute URLs the site payload provides. Produces the same `VenueData`
+ * contract as the mock provider.
+ */
+declare class RestVenueProvider implements VenueProvider {
+    #private;
+    constructor(options: RestVenueProviderOptions);
+    fetchVenue(signal?: AbortSignal): Promise<VenueData>;
+}
+
+export { type BecoMap, type BecoMapEvents, type BecoMapOptions, type Building, type CameraFacade, type Category, type Floor, type FloorConnectionKind, type FloorsFacade, type GraphEdge, type GraphNode, type Listener, type LngLat, type MapObjectDef, MockVenueProvider, type NavStepInfo, type PolygonGeometry, type PolygonThemeName, RestVenueProvider, type RestVenueProviderOptions, type RouteStep, type RoutingFacade, type SearchFacade, type Shape, type StepAction, type StepDirection, Venue, type VenueData, type VenueFacade, type VenueLocation, type VenueProvider, type VenueStats, buildVenue, createMap };