suaveplan/openspec/changes/enterprise-react-map/tasks.md

Tasks: enterprise-react-map

Change ID: enterprise-react-map Package: @suaveplan/react-map Target path: react/platform/react-map Prerequisite packages on Verdaccio: @suaveplan/error, @suaveplan/events, @suaveplan/react-translate

---

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Scaffold

• Create directory tree. Write package.json at 0.1.0, tsconfig.json, vitest.config.ts, scripts.
• Dependencies: @suaveplan/error workspace:^, @suaveplan/events workspace:^, @suaveplan/react-translate workspace:^, @opentelemetry/api catalog:observability, zod catalog:forms, tslib catalog:build. Peer/optional: maplibre-gl catalog:maps, leaflet catalog:maps.

---

2. Error codes and types

• Define MapError; codes: MAP_ADAPTER_INIT_FAILED, MAP_RENDER_FAILED.
• Define all types: LatLng, MapBounds, MapConfig, MapProps, MapContainerProps, MarkerData, MarkerProps, MarkerClusterData, MarkerClusterProps, PolygonData, PolygonProps, ClusterConfig, MapEventMap, UseMapReturn, MapAdapter, MapAdapterOptions.

---

3. Utils

geo.ts

• haversine(a: LatLng, b: LatLng): number — distance in metres.
• boundsUnion(a: MapBounds, b: MapBounds): MapBounds — smallest bounding box covering both.
• pointInPolygon(point: LatLng, polygon: LatLng[]): boolean — ray-cast algorithm.
• Write geo.test.ts (≤500 lines): known-distance pairs, bounds union, polygon in/out. { timeout: 5000 }.
• Write geo.md.

cluster.ts

• clusterMarkers(markers: MarkerData[], config: ClusterConfig): MarkerClusterData[] — grid-based clustering with configurable cell size.
• Write cluster.test.ts (≤500 lines): single cluster, no overlap, empty input, zoom-level variation. { timeout: 5000 }.
• Write cluster.md.

---

4. Adapters

MapAdapter interface

• adapter.types.ts — MapAdapter<TMap> interface: init(container, config): TMap, setCenter(map, center), setZoom(map, zoom), getBounds(map): MapBounds, on(map, event, handler), off(map, event, handler), destroy(map).

MapLibreAdapter

• createMapLibreAdapter(): MapAdapter — wraps maplibre-gl; gate with if (maplibregl === undefined) throw MapError(MAP_ADAPTER_INIT_FAILED).
• Write maplibre.test.ts (≤500 lines): init, center/zoom set, bounds read, destroy, missing-lib error. DI-injected maplibre mock. { timeout: 10000 }.
• Write maplibre.md.

LeafletAdapter

• createLeafletAdapter(): MapAdapter — wraps leaflet; gate similarly.
• Write leaflet.test.ts (≤500 lines). { timeout: 10000 }.
• Write leaflet.md.

---

5. Hooks

useMap

• useMap(config) — manages center, zoom, bounds, markers, polygons, clusters. Accepts adapter prop. Returns UseMapReturn. OTel map.init span.
• Write use-map.test.ts (≤500 lines): state init, center update, marker add/remove, bounds change. { timeout: 10000 }.
• Write use-map.md.

useMapContext

• React context + useMapContext() hook. Throws MapError if used outside MapContainer.
• Write test + md.

---

6. Components

MapContainer

• Provides MapContext; renders the vendor-specific map instance. Accepts adapter, config, className.
• Write test, stories (maplibre, leaflet, playground), md.

MapView

• Top-level composite: MapContainer + children overlay slot. Keyboard pan (arrow keys), zoom (+/-), role="application", aria-label via useTranslation.
• Write test, stories (default, markers, polygons, clusters, playground), md.

Marker

• Rendered via adapter; accepts position, onClick, label, icon. Screen-reader description generated from label.
• Write test, stories (default, custom-icon, with-popup, playground), md.

MarkerCluster

• Renders cluster circle with count using clusterMarkers. Animated expand on click.
• Write test, stories (small-cluster, large-cluster, expanding, playground), md.

Polygon

• Renders polygon overlay via adapter. Accepts positions[], fillColor, strokeColor, onClick.
• Write test, stories (default, filled, multi-polygon, playground), md.

---

7. E2E

• e2e/map.spec.ts — Playwright:
  • Render MapView with MapLibre adapter; verify map canvas present.
  • Click a Marker; verify popup/callback fires.
  • Render MarkerCluster; click cluster; verify it expands to individual markers.
  • Draw a Polygon; verify onClick fires with correct coordinates.
  • Use keyboard arrow keys to pan; verify center coordinates change.

---

8. Verify and publish

• bunx turbo lint typecheck test --filter=@suaveplan/react-map — green.
• bunx turbo test:coverage --filter=@suaveplan/react-map — 100%.
• bun scripts/publish.ts --package @suaveplan/react-map.
• Archive change folder.