Initial Commit
This commit is contained in:
100
openspec/changes/enterprise-react-port-tracking/proposal.md
Normal file
100
openspec/changes/enterprise-react-port-tracking/proposal.md
Normal file
@@ -0,0 +1,100 @@
|
||||
# OpenSpec Change: enterprise-react-port-tracking
|
||||
|
||||
- **Change ID**: enterprise-react-port-tracking
|
||||
- **Package**: `@suaveplan/react-port-tracking`
|
||||
- **Category**: react
|
||||
- **Target path**: `react/platform/react-port-tracking`
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-port-tracking.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/react-port-tracking` on genesis from scratch at enterprise quality. React surface for `@suaveplan/ports`: composite components (`PortMap`, `VesselTracker`, `ShippingLaneOverlay`, `PortMarker`, `ETAPanel`, `PortInfoCard`) and hooks (`usePortSearch`, `useShippingLanes`, `useETAEstimate`, `useVesselTracking`). Genesis closes test gaps for `PortMap`, `ShippingLaneOverlay`, `VesselTracker`, `useVesselTracking`, and `portIconPaths` (all missing from main branch), aligns `PortMap` on top of `@suaveplan/react-map` primitives, adds i18n via `@suaveplan/react-translate`, Storybook for every component, and Playwright E2E for live vessel tracking.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
Package does not exist on genesis — fresh build.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` (`workspace:^`) | `PortTrackingError` |
|
||||
| `@suaveplan/events` (`workspace:^`) | Vessel event bus |
|
||||
| `@suaveplan/ports` (`workspace:^`) | Port data + ETA engine |
|
||||
| `@suaveplan/react-map` (`workspace:^`) | Map primitives (MapView, Marker, Polygon) |
|
||||
| `@suaveplan/react-translate` (`workspace:^`) | i18n for ETA labels, port names |
|
||||
| `@opentelemetry/api` (`catalog:observability`) | Spans + counters |
|
||||
| `zod` (`catalog:forms`) | Config schemas |
|
||||
| `tslib` (`catalog:build`) | TS helpers |
|
||||
|
||||
External: React 18 peer.
|
||||
|
||||
---
|
||||
|
||||
## Preserved public API surface
|
||||
|
||||
```ts
|
||||
// Components
|
||||
PortMap, VesselTracker, ShippingLaneOverlay,
|
||||
PortMarker, ETAPanel, PortInfoCard
|
||||
|
||||
// Hooks
|
||||
usePortSearch, useShippingLanes, useETAEstimate, useVesselTracking
|
||||
|
||||
// Utils
|
||||
portIconPaths
|
||||
|
||||
// Types
|
||||
ETAPanelProps, PortInfoCardProps, PortMapProps, PortMarkerProps,
|
||||
ShippingLaneOverlayProps, VesselPosition, VesselTrackerProps,
|
||||
UseETAEstimateOptions, UseETAEstimateReturn,
|
||||
UsePortSearchOptions, UsePortSearchReturn,
|
||||
ShippingLaneWithDistance, UseShippingLanesReturn,
|
||||
UseVesselTrackingOptions, UseVesselTrackingReturn, PortIconType
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## New additions for genesis
|
||||
|
||||
1. **`PortTrackingError`** — codes: `PORT_SEARCH_FAILED`, `VESSEL_TRACK_FAILED`, `ETA_ESTIMATE_FAILED`.
|
||||
2. **`PortMap` on `react-map` primitives** — aligned on `MapView`, `Marker`, `Polygon` from `@suaveplan/react-map`.
|
||||
3. **i18n** — `@suaveplan/react-translate` for ETA labels ("Arriving", "Delayed"), facility lists, all ARIA strings.
|
||||
4. **Missing tests** — `PortMap`, `ShippingLaneOverlay`, `VesselTracker`, `useVesselTracking`, `portIconPaths` all fully covered.
|
||||
5. **Storybook** — stories for every component + hooks playground.
|
||||
6. **Playwright E2E** — live vessel stream, marker updates, ETA panel.
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
react/platform/react-port-tracking/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
types/
|
||||
components/
|
||||
port-map/ (tsx + types + md + test + stories + index)
|
||||
vessel-tracker/ (tsx + types + md + test + stories + index)
|
||||
shipping-lane-overlay/ (tsx + types + md + test + stories + index)
|
||||
port-marker/ (tsx + types + md + test + stories + index)
|
||||
eta-panel/ (tsx + types + md + test + stories + index)
|
||||
port-info-card/ (tsx + types + md + test + stories + index)
|
||||
hooks/
|
||||
use-port-search/ use-shipping-lanes/ use-eta-estimate/ use-vessel-tracking/
|
||||
utils/
|
||||
port-icons.ts + test + md
|
||||
e2e/
|
||||
port-tracking.spec.ts
|
||||
```
|
||||
117
openspec/changes/enterprise-react-port-tracking/tasks.md
Normal file
117
openspec/changes/enterprise-react-port-tracking/tasks.md
Normal file
@@ -0,0 +1,117 @@
|
||||
# Tasks: enterprise-react-port-tracking
|
||||
|
||||
**Change ID**: enterprise-react-port-tracking
|
||||
**Package**: `@suaveplan/react-port-tracking`
|
||||
**Target path**: `react/platform/react-port-tracking`
|
||||
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/ports`, `@suaveplan/react-map`, `@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/ports workspace:^`, `@suaveplan/react-map workspace:^`, `@suaveplan/react-translate workspace:^`, `@opentelemetry/api catalog:observability`, `zod catalog:forms`, `tslib catalog:build`.
|
||||
|
||||
---
|
||||
|
||||
## 2. Error codes and types
|
||||
|
||||
- [ ] Define `PortTrackingError`; codes: `PORT_SEARCH_FAILED`, `VESSEL_TRACK_FAILED`, `ETA_ESTIMATE_FAILED`.
|
||||
- [ ] Define all types: `ETAPanelProps`, `PortInfoCardProps`, `PortMapProps`, `PortMarkerProps`, `ShippingLaneOverlayProps`, `VesselPosition`, `VesselTrackerProps`, `UseETAEstimateOptions`, `UseETAEstimateReturn`, `UsePortSearchOptions`, `UsePortSearchReturn`, `ShippingLaneWithDistance`, `UseShippingLanesReturn`, `UseVesselTrackingOptions`, `UseVesselTrackingReturn`, `PortIconType`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Utils
|
||||
|
||||
### port-icons.ts
|
||||
|
||||
- [ ] `portIconPaths: Record<PortIconType, string>` — SVG path strings for sea/air/rail/multimodal port icon types.
|
||||
- [ ] Write `port-icons.test.ts` (≤500 lines): all icon types present, paths are valid non-empty strings. `{ timeout: 5000 }`.
|
||||
- [ ] Write `port-icons.md`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Hooks
|
||||
|
||||
### usePortSearch
|
||||
|
||||
- [ ] Searches ports via `@suaveplan/ports`. Returns `{ results, loading, error, search }`. OTel `port.search` span. Throws `PortTrackingError(PORT_SEARCH_FAILED)` on engine error.
|
||||
- [ ] Write test + md.
|
||||
|
||||
### useShippingLanes
|
||||
|
||||
- [ ] Loads shipping lanes with distance from a reference point. Returns `{ lanes, loading, error }`.
|
||||
- [ ] Write test + md.
|
||||
|
||||
### useETAEstimate
|
||||
|
||||
- [ ] Computes ETA from current position + route via `@suaveplan/ports`. Returns `{ eta, distance, speed, loading, error }`. OTel `vessel.eta.estimate` span.
|
||||
- [ ] Write test + md.
|
||||
|
||||
### useVesselTracking
|
||||
|
||||
- [ ] Subscribes to vessel position updates via `@suaveplan/events`. Returns `{ position, history, loading, error }`. OTel `vessel.position.update` counter. Throws `PortTrackingError(VESSEL_TRACK_FAILED)` on connection failure.
|
||||
- [ ] Write `use-vessel-tracking.test.ts` (≤500 lines): initial position, position update event, history accumulates, unsubscribe on unmount. `{ timeout: 10000 }`.
|
||||
- [ ] Write `use-vessel-tracking.md`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Components
|
||||
|
||||
### PortMarker
|
||||
|
||||
- [ ] SVG marker using `portIconPaths` for port type. Accepts `port`, `onClick`, ARIA label via `useTranslation`.
|
||||
- [ ] Write test, stories (all-types, selected, playground), md.
|
||||
|
||||
### ETAPanel
|
||||
|
||||
- [ ] Displays ETA, distance, speed. Labels "Arriving" / "Delayed" via `useTranslation`. Handles `null` ETA with "–".
|
||||
- [ ] Write test, stories (arriving, delayed, unknown, playground), md.
|
||||
|
||||
### PortInfoCard
|
||||
|
||||
- [ ] Port card with facilities, name, type, coordinates. All labels via `useTranslation`.
|
||||
- [ ] Write test, stories (default, with-facilities, no-facilities, playground), md.
|
||||
|
||||
### ShippingLaneOverlay
|
||||
|
||||
- [ ] Renders shipping lanes as `Polygon` / polylines on `@suaveplan/react-map` canvas.
|
||||
- [ ] Write `shipping-lane-overlay.test.tsx` (≤500 lines): renders lanes on map, no-lanes empty state. `{ timeout: 5000 }`.
|
||||
- [ ] Write stories (default, multi-lane, highlighted, playground), md.
|
||||
|
||||
### VesselTracker
|
||||
|
||||
- [ ] Renders vessel icon at current position using `@suaveplan/react-map` `Marker`. Shows course line. Updates smoothly on position change.
|
||||
- [ ] Write `vessel-tracker.test.tsx` (≤500 lines): renders at position, updates on new position event, shows course. `{ timeout: 5000 }`.
|
||||
- [ ] Write stories (default, in-motion, anchored, playground), md.
|
||||
|
||||
### PortMap
|
||||
|
||||
- [ ] Composite: `MapView` from `@suaveplan/react-map` + `PortMarker[]` + `ShippingLaneOverlay` + `VesselTracker[]`. Accepts `adapter` prop forwarded to `MapView`.
|
||||
- [ ] Write `port-map.test.tsx` (≤500 lines): renders map + markers + overlays, vessel positions updated, empty markers state. `{ timeout: 10000 }`.
|
||||
- [ ] Write stories (default, with-vessels, with-lanes, loading, playground), md.
|
||||
|
||||
---
|
||||
|
||||
## 6. E2E
|
||||
|
||||
- [ ] `e2e/port-tracking.spec.ts` — Playwright:
|
||||
- Render `PortMap` with test data; verify port markers present.
|
||||
- Simulate vessel position update event; verify `VesselTracker` moves.
|
||||
- Verify `ETAPanel` shows "Arriving" label for an in-bound vessel.
|
||||
- Test search for a port; verify `PortInfoCard` renders for the result.
|
||||
|
||||
---
|
||||
|
||||
## 7. Verify and publish
|
||||
|
||||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/react-port-tracking` — green.
|
||||
- [ ] `bunx turbo test:coverage --filter=@suaveplan/react-port-tracking` — 100%.
|
||||
- [ ] `bun scripts/publish.ts --package @suaveplan/react-port-tracking`.
|
||||
- [ ] Archive change folder.
|
||||
Reference in New Issue
Block a user