@trackunit/react-map 0.1.30 → 0.1.31

package/README.md

@@ -1,30 +1,59 @@
 # @trackunit/react-map
 
-Contains core map components.
+Provider-agnostic, hook-first map library for React applications. Switch between Google Maps and Mapbox without touching your application code.
 
-Checklist: 
-[x]Both Google Maps and Mapbox adapters are implemented.
+## Design principles
 
------
+- **Provider behind an adapter.** Google Maps or Mapbox is passed in as adapter config. Swapping providers is a one-line change; your components, events, and tests are untouched.
+- **Hook-first, TanStack-style.** State, actions, and the renderable component are co-located at the call site via `useMap(adapter)`. No context tree to set up; no provider-specific types leaking into your code.
+- **Resolver props — you decide.** Where choices are genuinely the consumer's — which markers render as DOM vs symbol, what style a hovered shape gets — the library hands you a fully-described context object and takes a small decision back. It never makes the heuristic call behind your back.
+- **Defaults, but always composable.** Every resolver ships a sensible default that is exported for composition. Use it as-is, wrap it, or replace it entirely.
+- **Atomic components.** `MapMarker`, `ClusterMarker`, `MapMarkerIcon`, and `Panel` are usable stand-alone, even outside a map.
+- **Strong types.** Discriminated unions, exhaustive switches, and typed resolver contracts catch mistakes at compile time.
+- **No vendor leakage.** All provider-specific types and APIs belong inside adapters. Nothing outside an adapter may import from `mapbox-gl` or `@vis.gl/react-google-maps`.
+- **Self-contained, portable layers.** A well-designed layer hook owns its own data loading, controls, and settings so it can be dropped into any map without surrounding setup. Concretely, layers should accept a pre-built `filters` object as a prop rather than fetching raw data — the hook owns the query internally and the caller owns the filter shape.
 
-Provider-agnostic map library for React applications. Switch between Google Maps and Mapbox seamlessly without code changes.
+## Three layers of abstraction
 
-## Features
+The library is intentionally split into three tiers. **Reach for the highest-level tier that satisfies your needs, and only drop down a layer when you need more control.** Starting at a lower tier than necessary means reinventing abstractions the higher tiers already provide.
 
-- **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
+### Tier 1 — `useMap` and `MapApi`
+
+The foundation. Full control over camera, events, controls, panels, annotations, and the adapter surface. Maximum flexibility; you invent everything yourself.
+
+Use this when you are building something structurally novel or need to escape a constraint in a higher-level hook.
+
+### Tier 2 — Layer hooks (`useMarkers`, `useShapes`, …)
+
+The everyday workhorse. Layer hooks give a high-productivity path to common map features without giving anything away. They surface full library behaviour with sensible defaults you can override one decision at a time via resolver props.
+
+The atomic building blocks these compose are exported for reuse too: the output components (`MapMarker`, `ClusterMarker`, `MapMarkerIcon`) and helper hooks (`useAdaptiveMarkerHelpers`, `useShapeLabelHelpers`, …) that surface the default resolver heuristics. This is where almost all map feature work should live.
+
+### Tier 3 — Your domain layer hooks
+
+The top tier is your own domain hooks — built on top of Tier 2 primitives. Highly opinionated hooks that own data fetching, display logic, controls, and interaction end-to-end. Closed by design — no customization knobs. If you need something similar but with different behaviour, drop to Tier 2 and compose from the atomic pieces.
+
+Every finished, map-ready layer is a Tier 3 hook, so the tier you pick is really your starting point: use a ready-made domain hook as-is, or assemble your own from Tier 2 primitives.
+
+**This library exports generic primitives only.** Domain hooks belong in the domain library that serves them — not in `@trackunit/react-map`. Trackunit's own asset and site layer hooks are reference implementations that will be published separately. If you build a domain layer that would be valuable beyond your own app, consider publishing it as its own package too.
 
 ## 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
+```bash
+npm install @trackunit/react-map
+```
+
+Map providers live in separate adapter packages — install whichever one(s) you use alongside it:
+
+```bash
+# Google Maps
+npm install @trackunit/react-map-adapter-google
+
+# Mapbox
+npm install @trackunit/react-map-adapter-mapbox
+```
 
-Import map providers from the adapter packages, not from `@trackunit/react-map`:
+Always import providers from the adapter package, never from `@trackunit/react-map`:
 - Google Maps: `@trackunit/react-map-adapter-google` (`googleMapsAdapter`, `GoogleApiProvider`, …)
 - Mapbox: `@trackunit/react-map-adapter-mapbox` (`mapboxAdapter`, …)
 
@@ -229,42 +258,11 @@ Maps include built-in accessibility features:
 
 ## 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
+`@trackunit/react-map` is built in independently-useful layers: provider **adapters**, the **`useMap`** foundation and `MapApi`, **layer hooks** (`useMarkers`, `useShapes`, …), and **atomic components** (`MapMarker`, `ClusterMarker`, …). Each tier is usable and testable on its own — see the design principles and three-tier model above.
 
-# Run type checking
-yarn nx run react-map:tsc-validate
-
-# Run linting
-yarn nx lint react-map
-```
+Provider integrations ship as separate packages:
+- `@trackunit/react-map-adapter-google` — Google Maps
+- `@trackunit/react-map-adapter-mapbox` — Mapbox
 
 ## Adding New Providers
 

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@trackunit/react-map",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
     "node": ">=24.x"
   },
   "dependencies": {
-    "@trackunit/react-components": "2.1.39",
+    "@trackunit/react-components": "2.1.40",
     "@trackunit/css-class-variance-utilities": "1.13.43",
-    "@trackunit/react-form-components": "2.1.41",
-    "@trackunit/react-core-hooks": "1.17.52",
+    "@trackunit/react-form-components": "2.1.42",
+    "@trackunit/react-core-hooks": "1.17.53",
     "@trackunit/geo-json-utils": "1.14.46",
-    "@trackunit/i18n-library-translation": "2.0.40",
-    "@trackunit/react-modal": "2.1.43",
+    "@trackunit/i18n-library-translation": "2.0.41",
+    "@trackunit/react-modal": "2.1.44",
     "react-minimal-pie-chart": "^8.4.0",
     "@trackunit/react-map-adapter-shared": "0.0.27",
     "@trackunit/react-map-color-utils": "0.0.12",