@trackunit/react-map 0.0.4-alpha-9d327375fc1.0

package/README.md

@@ -0,0 +1,296 @@
+# @trackunit/react-map
+
+Contains core map components.
+
+Checklist: 
+[x]Both Google Maps and Mapbox adapters are implemented.
+
+-----
+
+Provider-agnostic map library for React applications. Switch between Google Maps and Mapbox seamlessly without code changes.
+
+## Features
+
+- **Provider Agnostic**: Use Google Maps or Mapbox with the same API
+- **Type Safe**: Full TypeScript support with zero type assertions
+- **Reactive**: Automatic state updates using `useSyncExternalStore`
+- **Accessible**: ARIA labels and keyboard navigation built-in
+- **Extensible**: Easy to add new map providers
+
+## Installation
+
+The library is part of the monorepo. Dependencies are:
+- `@vis.gl/react-google-maps` - Google Maps integration
+- `mapbox-gl` - Mapbox GL JS integration
+- `@trackunit/geo-json-utils` - GeoJSON type definitions
+
+Import map providers from the adapter packages, not from `@trackunit/react-map`:
+- Google Maps: `@trackunit/react-map-adapter-google` (`googleMapsAdapter`, `GoogleApiProvider`, …)
+- Mapbox: `@trackunit/react-map-adapter-mapbox` (`mapboxAdapter`, …)
+
+## Usage
+
+### Google Maps
+
+```tsx
+import { useCameraState, useMap } from "@trackunit/react-map";
+import { googleMapsAdapter } from "@trackunit/react-map-adapter-google";
+
+const MyMap = () => {
+  const [Map, api] = useMap(googleMapsAdapter({
+    apiKey: process.env.GOOGLE_MAPS_API_KEY,
+    theme: "light",
+    language: "en",
+  }));
+
+  const { center, zoom } = useCameraState(api);
+
+  return (
+    <div className="relative h-full">
+      <p>Center: {center[0]}, {center[1]}</p>
+      <p>Zoom: {zoom}</p>
+      <Map className="h-full w-full">
+        {/* Children render inside the map */}
+      </Map>
+    </div>
+  );
+};
+```
+
+### Mapbox
+
+```tsx
+import { useCameraState, useMap } from "@trackunit/react-map";
+import { mapboxAdapter } from "@trackunit/react-map-adapter-mapbox";
+
+const MyMap = () => {
+  const [Map, api] = useMap(mapboxAdapter({
+    accessToken: process.env.MAPBOX_ACCESS_TOKEN,
+    theme: "dark",
+    language: "en",
+  }));
+
+  const { center, zoom } = useCameraState(api);
+
+  return (
+    <div className="relative h-full">
+      <p>Center: {center[0]}, {center[1]}</p>
+      <p>Zoom: {zoom}</p>
+      <Map className="h-full w-full">
+        {/* Same children work with both Google and Mapbox! */}
+      </Map>
+    </div>
+  );
+};
+```
+
+## API
+
+### `useMap(adapter)`
+
+Returns a tuple `[Map, api]`:
+
+- `Map` - React component to render the map
+- `api.state` - Map status (isReady, initializationFailed, appearance, rasterResolution)
+- `useCameraState(api)` - Reactive camera state (center, zoom, bounds, isIdle — changes at up to 60fps)
+- `api.actions.setCenter(position)` - Set map center (returns promise)
+- `api.actions.setZoom(zoom)` - Set zoom level (returns promise)
+- `api.actions.zoomBy(delta)` - Adjust zoom by delta (returns promise)
+- `api.actions.fitBounds(bounds, options)` - Fit map to bounds (returns promise)
+- `api.actions.panTo(position)` - Pan to position with animation (returns promise)
+- `api.on(event, handler)` - Subscribe to map events (returns unsubscribe function)
+
+### Coordinates
+
+All coordinates use GeoJSON format: `[longitude, latitude]`
+
+```tsx
+const berlin: GeoJsonPosition = [13.405, 52.52]; // [lng, lat]
+```
+
+### Bounding Boxes
+
+All bounding boxes use GeoJSON format: `[minLng, minLat, maxLng, maxLat]`
+
+```tsx
+const europeBounds: GeoJsonBbox = [-10, 35, 40, 70];
+```
+
+### Map Actions
+
+All actions return promises that resolve when the map finishes moving:
+
+```tsx
+await api.actions.setCenter([13.405, 52.52]);
+await api.actions.setZoom(12);
+await api.actions.fitBounds([-10, 35, 40, 70], { padding: 50, maxZoom: 15 });
+```
+
+### Map State
+
+`api.state` contains low-frequency MapStatus (readiness, initialization failure, appearance, raster resolution). For CameraState that changes during panning/zooming, use `useCameraState(api)`:
+
+```tsx
+// Initialization state — rarely changes
+const { isReady, appearance } = api.state;
+
+// Camera state — changes at up to 60fps during panning
+const { center, zoom, bounds, isIdle } = useCameraState(api);
+
+// Only re-renders when zoom changes (opt-in)
+const { zoom } = useCameraState(api);
+useEffect(() => {
+  console.log("Zoom changed:", zoom);
+}, [zoom]);
+```
+
+### Map Events
+
+Subscribe to map events with type-safe handlers:
+
+```tsx
+useEffect(() => {
+  const unsubscribe = api.on("click", (e) => {
+    console.log("Clicked at:", e.position);
+  });
+
+  return unsubscribe;
+}, [api.on]);
+```
+
+Available events:
+- `idle` - Map finished moving
+- `movestart` - Map started moving
+- `moveend` - Map finished moving (includes final state)
+- `click` - Map clicked (includes position and original event)
+
+## Switching Providers
+
+To switch providers, only change the adapter configuration:
+
+```tsx
+// Before: Google Maps
+const [Map, api] = useMap(googleMapsAdapter({ apiKey: "..." }));
+
+// After: Mapbox
+const [Map, api] = useMap(mapboxAdapter({ accessToken: "..." }));
+
+// Everything else stays the same!
+```
+
+## Configuration Options
+
+### Google Maps Config
+
+```tsx
+type GoogleMapsConfig = {
+  apiKey: string;              // Required
+  theme?: "light" | "dark";    // Default: "light"
+  language?: string;           // Map labels language
+  initialViewport?: InitialViewport;  // Initial view: center+zoom or bounds
+  restrictBounds?: GeoJsonBbox | null;  // Default: no restriction; null = no restriction
+};
+```
+
+### Mapbox Config
+
+```tsx
+type MapboxConfig = {
+  accessToken: string;         // Required
+  theme?: "light" | "dark";    // Default: "light"
+  language?: string;           // Map labels language
+  initialViewport?: InitialViewport;  // Initial view: center+zoom or bounds
+  restrictBounds?: GeoJsonBbox | null;  // Default: no restriction; null = no restriction
+};
+```
+
+`restrictBounds` controls panning/zoom bounds. GeoJSON format: `[minLng, minLat, maxLng, maxLat]`.
+- `undefined` (default): no restriction (infinite horizontal scroll)
+- `null`: no restriction (infinite horizontal scroll)
+- `GeoJsonBbox`: restrict to custom region (e.g. Europe: `[-10, 35, 40, 70]`)
+
+Invalid bboxes are validated with `geoJsonBboxSchema`; on failure, a console warning is emitted and no restriction is applied (fallback to `null`).
+
+`InitialViewport` is a discriminated union:
+- `{ type: "center"; center: [lng, lat]; zoom?: number }` — center with optional zoom
+- `{ type: "bounds"; bounds: GeoJsonBbox; padding?: number; maxZoom?: number }` — fit to bounds
+
+## Accessibility
+
+Maps include built-in accessibility features:
+
+- ARIA labels and roles
+- Keyboard navigation:
+  - Arrow keys: Pan map (100px)
+  - +/-: Zoom in/out (1 level)
+  - Home: Reset to default view
+  - Tab: Focus map
+  - Escape: Deselect/close popups
+
+## Architecture
+
+For the high-level architecture, motivation, design principles, and rollout strategy, see the **[Map 2026 Design Doc](https://github.com/niceideas/design-docs/blob/main/docs/202602-Manager-Map2026/202602-Manager-Map2026.md)** in the design-docs repo.
+
+Implementation detail in this repo is split between **[CONTEXT.md](CONTEXT.md)** (domain language and how concepts relate) and **[docs/adr/](docs/adr/)** (short architecture decision records).
+
+| Document | What it covers |
+|----------|---------------|
+| [CONTEXT.md](CONTEXT.md) | Glossary: Adapter, Layer Hook, Layer Handle, Layer Port, Entity, Control Config, Annotation, Decoration, and relationships between them |
+| [ADR 0001 — Hook-first map API](docs/adr/0001-hook-first-api.md) | `useMap(adapter)` tuple as the primary API; tuple vs object vs component-first |
+| [ADR 0002 — Adapter factory pattern](docs/adr/0002-adapter-factory-pattern.md) | Adapter factories, `defineAdapter`, `derive`, keeping provider knowledge at the call site |
+| [ADR 0003 — Controls as data](docs/adr/0003-controls-as-data.md) | Control configs as data, discriminated union, middleware pipeline, presentational renderers |
+| [ADR 0004 — Declarative LayerPort snapshot](docs/adr/0004-layer-port-declarative-snapshot.md) | `LayerPort.setSnapshot`, single write path, adapter-owned diffing |
+| [ADR 0005 — Annotation store on MapApi](docs/adr/0005-annotation-store-on-map-api.md) | `MapApi.annotations`, explicit `api` at call sites, renderer claims |
+| [ADR 0006 — Adapters own DOM marker positioning](docs/adr/0006-marker-anchor-ownership.md) | Marker anchors owned by the adapter; no competing transforms in DOM content |
+| [ADR 0007 — Antimeridian shapes merged in adapters](docs/adr/0007-antimeridian-merge-in-adapters.md) | Merging split GeoJSON at render time inside adapters, not in app state |
+| [ADR 0008 — Map panel store on MapApi](docs/adr/0008-map-panel-store-on-map-api.md) | `MapApi.panels`, `usePanel`, `PanelOrchestrator`, menu presentation via panels |
+| [ADR 0009 — Declarative MarkerState](docs/adr/0009-declarative-marker-state.md) | State-driven union prop over imperative marker API |
+| [ADR 0010 — Unified marker render tree](docs/adr/0010-unified-marker-render-tree.md) | Always-mounted slots animated via CSS; no separate circle/pill components |
+| [ADR 0011 — Stick mode anchor-zero + transform animation](docs/adr/0011-stick-anchor-zero-transform-animation.md) | Zero-size anchor container; CSS three-function transform; no JS width measurement |
+| [ADR 0012 — Fixed size ladder with locked pill tier](docs/adr/0012-marker-size-ladder-fixed-pill-tier.md) | Five-tier `MarkerDomSize` enum; pill layout fixed to `md` tier |
+| [ADR 0013 — GpsArrowNorth icon](docs/adr/0013-gps-arrow-north-icon.md) | North-facing SVG variant eliminates `heading - 45` magic offset at call sites |
+| [ADR 0020 — Map state is split by update frequency](docs/adr/0020-map-state-channels.md) | `MapStatus` on `api.state`, `CameraState` via `useCameraState(api)`, and separate adapter notification channels |
+| [@trackunit/react-map-adapter-google README](../map-adapter-google/README.md) | Google Maps adapter: exports, `GoogleApiProvider`, multiple maps |
+| [@trackunit/react-map-adapter-mapbox README](../map-adapter-mapbox/README.md) | Mapbox adapter: exports, configuration, typical usage |
+
+## Testing
+
+```bash
+# Run all tests
+yarn nx test react-map
+
+# Run type checking
+yarn nx run react-map:tsc-validate
+
+# Run linting
+yarn nx lint react-map
+```
+
+## Adding New Providers
+
+To add a new map provider:
+
+1. Create adapter instance implementing `AdapterInstance<TConfig>`
+2. Create type converters (GeoJSON ↔ provider types)
+3. Create renderer component
+4. Create adapter factory using `defineAdapter()`
+5. Export from `index.ts`
+
+Example structure:
+```
+src/adapters/leaflet/
+├── leafletAdapter.ts
+├── LeafletAdapterInstance.ts
+├── LeafletRenderer.tsx
+├── leafletTypeConverters.ts
+└── constants.ts
+```
+
+For more info and a full guide on Iris App SDK Development, please visit our [Developer Hub](https://developers.trackunit.com/).
+
+## Trackunit
+
+This package was developed by Trackunit ApS.
+Trackunit is the leading SaaS-based IoT solution for the construction industry, offering an ecosystem of hardware, fleet management software & telematics.
+
+![The Trackunit logo](https://trackunit.com/wp-content/uploads/2022/03/top-logo.svg)