Initial Commit
This commit is contained in:
107
openspec/changes/enterprise-react-map/proposal.md
Normal file
107
openspec/changes/enterprise-react-map/proposal.md
Normal file
@@ -0,0 +1,107 @@
|
||||
# OpenSpec Change: enterprise-react-map
|
||||
|
||||
- **Change ID**: enterprise-react-map
|
||||
- **Package**: `@suaveplan/react-map`
|
||||
- **Category**: react
|
||||
- **Target path**: `react/platform/react-map`
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-map.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/react-map` on genesis from scratch at enterprise quality. A headless, provider-agnostic mapping layer: `useMap` hook owns map state (center, zoom, bounds, markers, polygons, clusters); component primitives (`MapView`, `MapContainer`, `Marker`, `MarkerCluster`, `Polygon`) render via a typed `MapAdapter` interface. Genesis adds the first concrete adapters (MapLibre GL + Leaflet), a bundled clustering algorithm, geo math helpers (`haversine`, `boundsUnion`, `pointInPolygon`), Storybook for every component, accessibility (keyboard pan/zoom, `role="application"`), i18n for ARIA labels, and Playwright E2E.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
Package does not exist on genesis — fresh build.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` (`workspace:^`) | `MapError` |
|
||||
| `@suaveplan/events` (`workspace:^`) | Map event bus |
|
||||
| `@suaveplan/react-translate` (`workspace:^`) | i18n for ARIA labels / tooltips |
|
||||
| `@opentelemetry/api` (`catalog:observability`) | Spans + counters |
|
||||
| `zod` (`catalog:forms`) | Config schemas |
|
||||
| `tslib` (`catalog:build`) | TS helpers |
|
||||
|
||||
External: `maplibre-gl catalog:maps` (peer/optional), `leaflet catalog:maps` (peer/optional), React 18 peer.
|
||||
|
||||
---
|
||||
|
||||
## Preserved public API surface
|
||||
|
||||
```ts
|
||||
// Components
|
||||
MapView, MapContainer, Marker, MarkerCluster, Polygon
|
||||
|
||||
// Hooks
|
||||
useMap, useMapContext
|
||||
|
||||
// Adapters
|
||||
MapAdapter, MapLibreAdapter, LeafletAdapter
|
||||
createMapLibreAdapter, createLeafletAdapter
|
||||
|
||||
// Utils
|
||||
haversine, boundsUnion, pointInPolygon, clusterMarkers, cn
|
||||
|
||||
// Types
|
||||
LatLng, MapBounds, MapConfig, MapProps, MapContainerProps,
|
||||
MarkerData, MarkerProps, MarkerClusterData, MarkerClusterProps,
|
||||
PolygonData, PolygonProps, ClusterConfig, MapEventMap,
|
||||
UseMapReturn, MapAdapterOptions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## New additions for genesis
|
||||
|
||||
1. **`MapError`** — codes: `MAP_ADAPTER_INIT_FAILED`, `MAP_RENDER_FAILED`.
|
||||
2. **`MapAdapter` interface** — typed contract enabling swap of vendor SDKs.
|
||||
3. **`MapLibreAdapter` + `LeafletAdapter`** — first reference implementations; peer-dep gated.
|
||||
4. **Clustering algorithm** — `clusterMarkers(markers, config)` grid/supercluster-style in `src/utils/cluster.ts`.
|
||||
5. **Geo math** — `haversine`, `boundsUnion`, `pointInPolygon` in `src/utils/geo.ts`.
|
||||
6. **Storybook** — stories for `MapView`, `Marker`, `Polygon`, `MarkerCluster`, `MapContainer`, `useMap` playground.
|
||||
7. **Accessibility** — keyboard pan/zoom (arrow keys, `+`/`-`), `role="application"`, screen-reader marker descriptions.
|
||||
8. **Playwright E2E** — pan, zoom, marker click, cluster expand, polygon draw.
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
react/platform/react-map/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
types/
|
||||
components/
|
||||
map-view/ (tsx + types + md + test + stories + index)
|
||||
map-container/ (tsx + types + md + test + stories + index)
|
||||
marker/ (tsx + types + md + test + stories + index)
|
||||
marker-cluster/ (tsx + types + md + test + stories + index)
|
||||
polygon/ (tsx + types + md + test + stories + index)
|
||||
hooks/
|
||||
map-context/ (tsx + md + test + index)
|
||||
use-map/ (ts + md + test + index)
|
||||
adapters/
|
||||
adapter.types.ts
|
||||
maplibre/ (ts + md + test + index)
|
||||
leaflet/ (ts + md + test + index)
|
||||
utils/
|
||||
geo.ts + test + md
|
||||
cluster.ts + test + md
|
||||
cn.ts
|
||||
e2e/
|
||||
map.spec.ts
|
||||
```
|
||||
128
openspec/changes/enterprise-react-map/tasks.md
Normal file
128
openspec/changes/enterprise-react-map/tasks.md
Normal file
@@ -0,0 +1,128 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user