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

package/README.md

@@ -1,167 +1,227 @@
-# MinuteMaps SDK
+<div align="center">
 
-A comprehensive indoor mapping SDK built with MapLibre GL JS, providing venue management, theming, wayfinding, and interactive features.
+# MinuteMaps Web SDK
 
-## 🚀 Features
+**Render indoor venues — floors, POIs, amenities, destinations, and wayfinding routes — on top of [MapLibre GL JS](https://maplibre.org/).**
 
-- **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
+[![npm](https://img.shields.io/npm/v/@minmaps-dev/mm-web-sdk?label=npm)](https://www.npmjs.com/package/@minmaps-dev/mm-web-sdk)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![types](https://img.shields.io/badge/types-included-blue)](./dist/index.d.ts)
 
-## 📦 Installation
+</div>
+
+`@minmaps-dev/mm-web-sdk` is the official MinuteMaps SDK for the web. It loads venues from JACS, manages floors, POIs, amenities, destinations, and the camera, and gives you a small, well-typed surface for building modern kiosks and indoor mapping web apps.
 
 ```bash
-npm install minutemaps-sdk
+npm install @minmaps-dev/mm-web-sdk maplibre-gl @turf/turf
 ```
 
-## 🎯 Quick Start
+```ts
+import { MinuteMaps } from '@minmaps-dev/mm-web-sdk'
+import 'maplibre-gl/dist/maplibre-gl.css'
 
-```javascript
-import MinuteMapsSDK from 'minutemaps-sdk';
+const sdk = new MinuteMaps({
+  container: 'map',
+  jmap: { host: '', customerId: 123, venueId: 456 },
+  jacs: { mode: 'proxy', proxyBaseUrl: '/api/jacs' },
+  options: { styleMode: 'sdkTemplate' },
+})
 
-// Initialize the SDK
-const sdk = new MinuteMapsSDK();
+sdk.on('ready', ({ venue }) => console.log('venue ready', venue?.name))
+await sdk.init()
+```
 
-// 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!');
-  }
-});
+---
 
-// Switch themes
-sdk.switchTheme('modern-glassmorph');
-```
+## Status
 
-## 🎨 Available Themes
+This SDK is on a pre-1.0 release candidate (`1.0.0-rc.3`). The following capabilities are wired but **dormant pending backend support** — they are not yet functional in the published build:
 
-- **Modern Glassmorph** - Clean, modern design with glass effects
-- **Soft Pastel** - Gentle, accessible color palette
-- **Accessibility** - High-contrast theme for accessibility
+| Area | Status | Notes |
+| --- | --- | --- |
+| Floors, POIs, amenities, destinations | ✅ Shipped | Loads via JACS `building/full` + `venue/full`. |
+| Camera + view modes (3D/2D/flat) | ✅ Shipped | Style toggles work against the bundled `alt3-hybrid-style.json`. |
+| Venue-served stylesheets | 🚧 Roadmap | SDK currently uses its bundled style; `loadAndPatchVenueStyle()` is bypassed. |
+| Polygon layers + 3D map templates | 🚧 Roadmap | `buildPolygonLayers` / `applyMapTemplate3d` imports are commented in `src/sdk.ts`. |
+| Wayfinding | 🚧 Roadmap | Route renderer is fully built, but the runtime provider is a stub that throws *"Wayfinding is not yet implemented in the SDK"*. |
 
-## 🏗️ Architecture
+Track re-enable points by grepping `// TODO: Re-enable` in `src/sdk.ts` and `src/data/jacsDataProvider.ts`.
 
-The SDK is organized into several key modules:
+---
 
-### Core
-- `ThemeManager` - Theme switching and management
-- `VenueManager` - Venue and building data management
-- `JMapCoreWrapper` - JMap functionality integration
+## What's in the box
 
-### Layers
-- `LayerBuilder` - Map layer creation and management
-- `AmenityLayer` - Amenity visualization
-- `DestinationLayer` - Destination markers
-- `PathLayer` - Route visualization
-- `MoverLayer` - Moving elements (elevators, escalators)
+- **Venue + floors** — load a venue by `customerId` / `venueId`, switch active floor, let the SDK manage layer visibility.
+- **POIs, amenities, destinations** — query by floor, run keyword searches, find the kiosk's "You are here" location.
+- **View modes** — toggle 3D extrusion, 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.
+- **JACS proxy or direct mode** — keep credentials server-side (recommended) or call JACS directly from trusted environments.
 
-### Features
-- `Wayfinding` - Navigation and routing
-- `FeatureHighlighter` - Interactive feature highlighting
-- `MarkerManager` - Custom marker management
-- `AccessibilityFeatures` - Accessibility enhancements
+---
 
-### Controls
-- `FloorSelector` - Floor switching
-- `NavigationControl` - Map navigation
-- `RecenterControl` - Map recentering
-- `MapInspector` - Debugging tools
+## Documentation
 
-### Utils
-- `ColorTokens` - Color system
-- `PatternGenerator` - Visual patterns
-- `IconSelector` - Icon mapping
-- `TurfHelpers` - Geospatial utilities
-- `GeoJSONFormatter` - Data formatting
+The lean root README intentionally stops here. For depth, see:
 
-## 🎮 Demo Application
+- [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) — module map, init flow, JACS data path, style patching, dormant 3D notes.
+- [`docs/API.md`](./docs/API.md) — full public API surface grouped by lifecycle, floors, POIs, amenities, wayfinding, camera, events.
+- [`docs/KIOSK.md`](./docs/KIOSK.md) — kiosk integration patterns (You-Are-Here, kiosk-to-destination wayfinding once enabled, view-mode UX, sprite hosting, idle reset).
 
-### Next.js Demo
+External integrators will usually only need the [API](./docs/API.md) and [Kiosk](./docs/KIOSK.md) docs. Internal MTS engineers should also read [Architecture](./docs/ARCHITECTURE.md) before touching `src/sdk.ts` or the JACS provider.
 
-A modern Next.js application showcasing the MinuteMaps SDK with a clean UI and best-practice integration:
+---
 
-```bash
-# Navigate to the Next.js demo
-cd demo-next
+## Quick start (vanilla)
 
-# Install dependencies
-npm install
+```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))
+sdk.on('floorChanged', ({ floor }) => console.log('now showing', floor?.name))
 
-# Start the development server
-npm run dev
+await sdk.init()
 ```
 
-**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
+## 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' },
+      }}
+    />
+  )
+}
+```
 
-### Development Workflow
+The React entry is intentionally minimal: it owns its own `<div>`, calls `init()` on mount, and `destroy()` on unmount. Reach for the vanilla `MinuteMaps` class when you need imperative control (floor switching from a side panel, camera animations driven by Redux, etc.).
 
-For development with live SDK updates:
+---
 
-```bash
-# From the root directory
-npm run demo:react
+## Configuration at a glance
+
+```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
+}
 ```
 
-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
+Full option reference and an annotated `SDKOptions` shape live in [`docs/API.md`](./docs/API.md#configuration).
 
-## 📚 Documentation
+### JACS proxy mode (recommended)
 
-Generate comprehensive API documentation with a modern, beautiful interface:
+Browser apps should use `mode: 'proxy'` and forward requests through your own server so JACS credentials never reach the client. Your proxy should:
 
-```bash
-# Install dependencies
-npm install
+1. Read `JACS_HOST`, `JACS_CLIENT_ID`, `JACS_USERNAME`, `JACS_PASSWORD` from server env.
+2. Exchange the password grant for a bearer token (cache until expiry).
+3. Forward `GET /api/jacs/<path>` to `${JACS_HOST}/JACS/api/<path>` with the token attached.
+
+A reference Next.js route handler ships in the example app at `mm-web-sdk-example/app/api/jacs/[...path]/route.ts`. Copy it into your own backend or adapt it to your framework, then point `jacs.proxyBaseUrl` at it.
 
-# Generate documentation
-npm run docs
+### JACS direct mode
 
-# Generate and preview locally (opens in browser)
-npm run docs:preview
+For trusted environments — server-rendered pages, Electron kiosks, internal tools — call JACS directly:
 
-# Watch for changes
-npm run docs:watch
+```ts
+jacs: {
+  mode: 'direct',
+  host: 'https://jacs.example.com',
+  auth: { clientId, username, password },
+}
 ```
 
-## 🛠️ Development
+> ⚠ Never ship `direct` mode to a public browser bundle. Your JACS credentials would be visible to anyone with devtools.
 
-### Building the SDK
+---
 
-```bash
-# Build the SDK
-npm run build
+## Sprites
 
-# Watch for changes and rebuild
-npm run build:watch
-```
+`options.customSprite` is a sprite URL **prefix without extension** — MapLibre appends `.json` and `.png` (and `@2x` variants) automatically. The example app serves its sprite from `mm-web-sdk-example/public/sprites/`.
 
-### Project Structure
+---
 
+## Development
+
+```bash
+npm install
+npm run dev:sdk         # rollup --watch (rebuilds dist/ on change)
+npm run build           # rimraf dist + production rollup build
+npm run typecheck       # tsc --noEmit
+npm test                # vitest run
+npm run test:watch      # vitest in watch mode
+npm run test:coverage   # vitest run --coverage (v8 provider)
 ```
-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. Tests live in `tests/` and target the three highest-leverage modules: `JacsProvider`, `WayfindingManager`, and `ViewModeController`. Coverage thresholds are gated in `vitest.config.ts` (currently 60% lines/funcs/stmts, 50% branches).
+
+### Continuous integration
+
+Two workflows in `.github/workflows/`:
+
+- **`ci.yml`** — runs typecheck, vitest with coverage, and the production build on every push and pull request to `main` / `dev`. Coverage and `dist/` are uploaded as artifacts.
+- **`publish.yml`** — runs on tags matching `v*` (or via manual dispatch). Verifies the tag matches `package.json` version, runs the full pipeline, and publishes to npm with provenance. Requires an `NPM_TOKEN` repo secret.
+
+> **Internal note:** future Claude sessions get oriented from [`CLAUDE.md`](./CLAUDE.md). Repo-local subagents in [`.claude/agents/`](./.claude/agents/) cover API doc sync, release notes, and style/template edits.
+
+---
+
+## Browser + framework support
+
+| Target | Version |
+| --- | --- |
+| Node (build/dev) | ≥ 18 |
+| `maplibre-gl` | ^4 |
+| `@turf/turf` | ^7 |
+| `react` / `react-dom` | ^18 or ^19 (only required for `/react` entry) |
+
+Modern evergreen browsers. Kiosk targets are typically pinned Chromium builds — if you need to support a specific minimum, open an issue.
+
+---
+
+## License
 
-This project is licensed under the MIT License - see the LICENSE file for details. 
+MIT — see [LICENSE](./LICENSE).