@minmaps-dev/mm-web-sdk 1.0.0-rc.1 → 1.0.0-rc.3

package/README.md

@@ -1,167 +1,239 @@
-# MinuteMaps SDK
+# MinuteMaps Web SDK
 
-A comprehensive indoor mapping SDK built with MapLibre GL JS, providing venue management, theming, wayfinding, and interactive features.
+`@minmaps-dev/mm-web-sdk` is the official MinuteMaps SDK for the web. It renders indoor venues — floors, POIs, amenities, destinations, and wayfinding routes — on top of [MapLibre GL JS](https://maplibre.org/), with data sourced from JACS.
 
-## 🚀 Features
+## Features
 
-- **Venue Management** - Load and manage indoor venues with multiple floors
-- **Theme System** - Multiple visual themes with easy switching
-- **Wayfinding** - Indoor navigation and routing
-- **Interactive Layers** - Amenities, destinations, and moving elements
-- **Accessibility** - High-contrast themes and accessibility features
-- **Custom Controls** - Floor selector, navigation controls, and more
+- **Venue + floors** — load a venue by `customerId` / `venueId`, switch active floor, and let the SDK manage layer visibility.
+- **POIs, amenities, destinations** — query the venue, filter by floor, and run keyword searches.
+- **Wayfinding** — compute kiosk-to-destination or waypoint-to-waypoint routes and render them on the map.
+- **View modes** — toggle 3D, flat (top-down), and 2D-units modes at runtime.
+- **Camera control** — `setView` / `resetView` / `getCameraPosition`, plus a live `cameraChange` event for compass UIs.
+- **React entrypoint** — drop-in `<MinuteMapsView />` for React 18/19 apps.
+- **JACS proxy or direct mode** — keep credentials server-side with the proxy mode, or call JACS directly from trusted environments.
 
-## 📦 Installation
+## Installation
 
 ```bash
-npm install minutemaps-sdk
+npm install @minmaps-dev/mm-web-sdk maplibre-gl @turf/turf
 ```
 
-## 🎯 Quick Start
+`maplibre-gl` (v4) and `@turf/turf` (v7) are peer dependencies. `react` / `react-dom` (v18 or v19) are optional peers, only required if you use the `/react` entrypoint.
 
-```javascript
-import MinuteMapsSDK from 'minutemaps-sdk';
+Don't forget to import the MapLibre stylesheet once in your app:
 
-// Initialize the SDK
-const sdk = new MinuteMapsSDK();
+```ts
+import 'maplibre-gl/dist/maplibre-gl.css'
+```
 
-// Initialize with a venue
-await sdk.init({
-  container: 'map-container',
-  venueId: 'your-venue-id',
-  styleUrl: 'https://example.com/style.json',
-  onReady: () => {
-    console.log('SDK ready!');
-  }
-});
+## Quick start (vanilla)
+
+```ts
+import { MinuteMaps } from '@minmaps-dev/mm-web-sdk'
+import 'maplibre-gl/dist/maplibre-gl.css'
+
+const sdk = new MinuteMaps({
+  container: 'map',                   // element or element id
+  jmap: {
+    host: '',                         // unused in proxy mode
+    customerId: 123,
+    venueId: 456,
+  },
+  jacs: {
+    mode: 'proxy',                    // recommended for browser apps
+    proxyBaseUrl: '/api/jacs',
+  },
+  options: {
+    customSprite: '/sprites/sprite',  // your icon sprite (no extension)
+    minIndoorZoom: 16,
+    debug: true,
+    styleMode: 'sdkTemplate',
+  },
+})
+
+sdk.on('ready', ({ venue }) => {
+  console.log('venue ready', venue?.name)
+})
+
+await sdk.init()
+```
 
-// Switch themes
-sdk.switchTheme('modern-glassmorph');
+## Quick start (React)
+
+```tsx
+import { MinuteMapsView } from '@minmaps-dev/mm-web-sdk/react'
+import 'maplibre-gl/dist/maplibre-gl.css'
+
+export function Map() {
+  return (
+    <MinuteMapsView
+      className="h-screen w-screen"
+      config={{
+        container: '',                // ignored — the component owns the element
+        jmap: { host: '', customerId: 123, venueId: 456 },
+        jacs: { mode: 'proxy', proxyBaseUrl: '/api/jacs' },
+        options: { styleMode: 'sdkTemplate' },
+      }}
+    />
+  )
+}
 ```
 
-## 🎨 Available Themes
+For a more involved integration that wires events, floors, search, and wayfinding into React state, see the [`mm-web-sdk-example`](../mm-web-sdk-example) Next.js app — particularly [`hooks/useMap.ts`](../mm-web-sdk-example/hooks/useMap.ts).
 
-- **Modern Glassmorph** - Clean, modern design with glass effects
-- **Soft Pastel** - Gentle, accessible color palette
-- **Accessibility** - High-contrast theme for accessibility
+## Configuration
+
+```ts
+type SDKConfig = {
+  container: HTMLElement | string
+  jmap: {
+    host: string
+    customerId: number
+    venueId: number
+    locale?: string
+    auth?: { clientId: string; clientSecret: string }
+  }
+  jacs: {
+    mode: 'proxy' | 'direct'
+    host?: string                                 // 'direct' only
+    auth?: { clientId: string; username: string; password: string } // 'direct' only
+    proxyBaseUrl?: string                          // default '/api/jacs'
+  }
+  options?: SDKOptions
+}
+
+type SDKOptions = {
+  debug?: boolean
+  initialFloor?: string | number
+  customSprite?: string                            // sprite URL prefix (no extension)
+  minIndoorZoom?: number
+  boundsPadding?: number                           // default 50
+  styleMode?: 'venueStyleUrl' | 'sdkTemplate'
+  templateOverrideMode?: 'colorsOnly' | 'colorsAndConstants' | 'all'
+}
+```
 
-## 🏗️ Architecture
+### JACS proxy mode (recommended)
 
-The SDK is organized into several key modules:
+Browser apps should use `mode: 'proxy'` and forward requests through your own server so JACS credentials never reach the client. The example app ships a Next.js route handler at [`app/api/jacs/[...path]/route.ts`](../mm-web-sdk-example/app/api/jacs/%5B...path%5D/route.ts) that:
 
-### Core
-- `ThemeManager` - Theme switching and management
-- `VenueManager` - Venue and building data management
-- `JMapCoreWrapper` - JMap functionality integration
+1. Reads `JACS_HOST`, `JACS_CLIENT_ID`, `JACS_USERNAME`, `JACS_PASSWORD` from server env.
+2. Exchanges the password grant for a bearer token (cached until expiry).
+3. Forwards `GET /api/jacs/<path>` to `${JACS_HOST}/JACS/api/<path>` with the token attached.
 
-### Layers
-- `LayerBuilder` - Map layer creation and management
-- `AmenityLayer` - Amenity visualization
-- `DestinationLayer` - Destination markers
-- `PathLayer` - Route visualization
-- `MoverLayer` - Moving elements (elevators, escalators)
+Copy that handler into your own backend (or adapt it to your framework) and point `jacs.proxyBaseUrl` at it.
 
-### Features
-- `Wayfinding` - Navigation and routing
-- `FeatureHighlighter` - Interactive feature highlighting
-- `MarkerManager` - Custom marker management
-- `AccessibilityFeatures` - Accessibility enhancements
+### JACS direct mode
 
-### Controls
-- `FloorSelector` - Floor switching
-- `NavigationControl` - Map navigation
-- `RecenterControl` - Map recentering
-- `MapInspector` - Debugging tools
+For trusted environments (server-rendered pages, Electron kiosks, internal tools) you can call JACS directly:
 
-### Utils
-- `ColorTokens` - Color system
-- `PatternGenerator` - Visual patterns
-- `IconSelector` - Icon mapping
-- `TurfHelpers` - Geospatial utilities
-- `GeoJSONFormatter` - Data formatting
+```ts
+jacs: {
+  mode: 'direct',
+  host: 'https://jacs.example.com',
+  auth: { clientId, username, password },
+}
+```
 
-## 🎮 Demo Application
+## API
 
-### Next.js Demo
+### Class `MinuteMaps`
 
-A modern Next.js application showcasing the MinuteMaps SDK with a clean UI and best-practice integration:
+```ts
+new MinuteMaps(config: SDKConfig)
+sdk.init(): Promise<void>
+sdk.destroy(): void
+sdk.isReady(): boolean
+sdk.getMap(): maplibregl.Map | null
+```
 
-```bash
-# Navigate to the Next.js demo
-cd demo-next
+`createMinuteMapsSDK(config)` is a factory shorthand for `new MinuteMaps(config)`.
 
-# Install dependencies
-npm install
+### Floors
 
-# Start the development server
-npm run dev
+```ts
+sdk.getFloors(): Floor[]
+sdk.getCurrentFloor(): Floor | null
+sdk.getDefaultFloor(): Floor | null
+sdk.setCurrentFloor(floor: Floor): Promise<void>
 ```
 
-**Features:**
-- 🎨 **Theme Management** - Switch between available themes
-- 🏢 **Floor Selection** - Navigate between building floors
-- 📋 **Layer Controls** - Toggle map layers on/off
-- 🎯 **Feature Controls** - Control SDK features and markers
-- 🚶 **Wayfinding** - Indoor navigation between destinations
-- 📊 **SDK Status** - Real-time status and information
-- ⚡ **Quick Actions** - Recenter map and reset view
+### POIs, destinations, search
 
-### Development Workflow
+```ts
+sdk.getAllPOIs(floor?: Floor): POI[]
+sdk.getDestinations(floor?: Floor): Destination[]
+sdk.searchPOIs(query: string, floor?: Floor): POI[]
+sdk.getYouAreHerePOI(floor?: Floor): POI | null
+sdk.getYouAreHereCoordinates(floor?: Floor): [number, number] | null
+```
 
-For development with live SDK updates:
+### Amenities (`sdk.amenities`)
 
-```bash
-# From the root directory
-npm run demo:react
+```ts
+sdk.amenities.getAll(): AmenityWithFloor[]
+sdk.amenities.getByFloorId(floorId): AmenityWithFloor[]
+sdk.amenities.getAllKiosks(): AmenityWithFloor[]
+sdk.amenities.getKioskForFloor(floorId): AmenityWithFloor | null
 ```
 
-This command:
-1. Watches for SDK source changes and rebuilds automatically
-2. Starts the React development server
-3. Provides hot reloading for both SDK and React app
+### Wayfinding
 
-## 📚 Documentation
+```ts
+sdk.navigateFromKioskToDestination(destination): Promise<...>
+sdk.wayfindBetweenWaypoints(from, to, opts?: {
+  centerMode?: 'none' | 'destination' | 'route'
+  zoom?: number
+}): Promise<...>
+sdk.clearRoute(): void
+```
 
-Generate comprehensive API documentation with a modern, beautiful interface:
+### Camera + view modes
 
-```bash
-# Install dependencies
-npm install
+```ts
+sdk.setView({ center?, zoom?, pitch?, bearing?, animate?, duration? })
+sdk.resetView({ animate?, duration? })
+sdk.getCameraPosition(): CameraState | null
 
-# Generate documentation
-npm run docs
+sdk.set3dEnabled(enabled) / toggle3d() / getIs3dEnabled()
+sdk.setUnits2dEnabled(enabled) / toggleUnits2d() / getIsUnits2dEnabled()
+sdk.setFlatMode(enabled) / toggleFlatMode() / getIsFlatMode()
+```
 
-# Generate and preview locally (opens in browser)
-npm run docs:preview
+### MapLibre passthroughs
 
-# Watch for changes
-npm run docs:watch
+```ts
+sdk.addControl(control, position?)   // forwards to the underlying MapLibre map
+sdk.getMap()                         // escape hatch: the raw maplibregl.Map
 ```
 
-## 🛠️ Development
+### Events
 
-### Building the SDK
+Subscribe with `sdk.on(event, cb)` / unsubscribe with `sdk.off(event, cb)`.
 
-```bash
-# Build the SDK
-npm run build
+| Event           | Payload                       | When                                                       |
+| --------------- | ----------------------------- | ---------------------------------------------------------- |
+| `ready`         | `{ venue }`                   | Map loaded and the initial floor is rendered.              |
+| `floorsLoaded`  | `{}`                          | All floor geojson is available.                            |
+| `floorChanged`  | `{ floor }`                   | After `setCurrentFloor` resolves.                          |
+| `cameraChange`  | `{ camera: CameraState }`     | On every map `move` (drives compass/heading UI).           |
+| `error`         | `{ error }`                   | Init or runtime error.                                     |
 
-# Watch for changes and rebuild
-npm run build:watch
-```
+## Sprites
 
-### Project Structure
+Pass `options.customSprite` as a sprite URL prefix without the extension (MapLibre will append `.json` and `.png` / `@2x`). The example app serves its sprite from [`public/sprites/`](../mm-web-sdk-example/public/sprites/).
 
+## Development
+
+```bash
+npm install
+npm run dev:sdk    # rollup --watch
+npm run build      # clean + production build
+npm run typecheck  # tsc --noEmit
 ```
-minutemaps-sdk/
-├── src-sdk/           # SDK source code
-├── dist/              # Built SDK files
-├── demo-next/         # Next.js demo application
-├── docs/              # Generated documentation
-├── docs-assets/       # Documentation assets
-└── package.json       # Project configuration
-```
 
-## 📄 License
+The build emits ESM, CJS, and types under `dist/` for both the root entry and the `/react` entry.
+
+## License
 
-This project is licensed under the MIT License - see the LICENSE file for details. 
+MIT — see [LICENSE](./LICENSE).