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

// 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

PortTrackingError — codes: PORT_SEARCH_FAILED, VESSEL_TRACK_FAILED, ETA_ESTIMATE_FAILED.
PortMap on react-map primitives — aligned on MapView, Marker, Polygon from @suaveplan/react-map.
i18n — @suaveplan/react-translate for ETA labels ("Arriving", "Delayed"), facility lists, all ARIA strings.
Missing tests — PortMap, ShippingLaneOverlay, VesselTracker, useVesselTracking, portIconPaths all fully covered.
Storybook — stories for every component + hooks playground.
Playwright E2E — live vessel stream, marker updates, ETA panel.

File layout

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

3.6 KiB Raw Blame History