@motionstudies/web 0.1.0-alpha.11 → 0.1.0-alpha.12

package/README.md

@@ -164,6 +164,28 @@ Rail and other transport consumers can share the same time filtering through `mo
 
 `@motionstudies/data/air-endpoints` provides offline `enrichAirEndpoints` for existing air manifests, chunks and opening snapshots. Supply cached same-date global ADSB.lol heatmaps, an OurAirports CSV and the service date's local UTC offset. It associates only unambiguous low-altitude endpoints near a reference airport; cruise-only traces and uncertain routes stay unknown. Optional `AirEndpoint` origin/destination fields carry airport identity, observed boundary time and `observed-endpoint` evidence. `airportBoardMovements` maps full manifest entries to board rows without confusing playback chunk boundaries with flight endpoints. Input hashes and source/licence attribution are recorded in fixture metadata. These fields describe inferred observations, never flight schedules, gates or live status.
 
+## Vehicle hero cards
+
+`VehicleHeroCard` shows one vehicle's destination, next stop and remaining calling points. Import it from `@motionstudies/web/components/VehicleHeroCard` with `@motionstudies/web/vehicle-hero-card.css`. The **Vehicle heroes** lab compares `uk-bus` (amber onboard display), `uk-rail` (dark rail display), `yellow-bus` (yellow next-stop panel) and `sbb` (blue next-stop panel with a red service badge). These are presentation studies, not official operator components.
+
+```tsx
+<VehicleHeroCard
+  presentation="sbb"
+  vehicle={{ service: 'IC 1', operator: 'SBB CFF FFS', destination: 'Genève-Aéroport' }}
+  stops={[
+    { id: 'bern', name: 'Bern', time: '10:28', platform: '6' },
+    { id: 'fribourg', name: 'Fribourg/Freiburg', time: '10:56' },
+  ]}
+  note="Synthetic journey · Example calls and times."
+  onSelectStop={selectStation}
+  selectedStopId={selectedStationId}
+/>
+```
+
+Consumers supply remaining `stops` in journey order and update them with playback, seeking or observations; the card has no independent clock. The first supplied call is the next stop. Optional `time`, `platform` and `detail` are consumer-formatted; absent values stay absent. `vehicle.destination` is optional and shows an explicit unavailable label when missing. The final supplied stop is never inferred to be the destination: set `isDestination` only when confirmed, especially when data is progressively chunked. Empty calls mean no upcoming stops are available, without asserting that the vehicle has arrived.
+
+The required `note` explains provenance. Optional `status`, `statusTone`, `clockLabel`, localized `labels`, `loading`, `error` and `onRetry` follow the consumer's data; the component never manufactures an on-time status. Loading and errors hide the calling points. Stop selection is controlled through stable call IDs and does not alter playback or clear when a call leaves the list. All supplied calls are shown, with wrapping names and container-based compact layouts. The lab exercises advance/rewind, unknown destinations/times, localization, disruption, recovery and narrow widths. Edition adoption requires its own package upgrade and data adapter.
+
 ## Optional live airport feed
 
 `AirportBoard` from `@motionstudies/web/components/AirportBoard` adds Study/Now controls around an existing `AirportHeroCard` configuration. Pass `studyCard` with the usual card props and `live={{ baseUrl, edition, airport }}` for the shared service. Import `airport-hero-card.css`. `labels` localizes the wrapper's control and availability messages. The lower-level `useAirportFeed` hook and core `domain/live-airport` contract are also public exports.
@@ -193,3 +215,5 @@ The renderer now shares active GPU upload ranges, paused frame reuse, label and
 `useTransitionValue(target, { durationMs, easing, steps })` from `@motionstudies/web/use-transition-value` animates a numeric value, returning `value` and `transitioning`. It reverses from the current frame, cancels on teardown, and settles immediately when reduced motion becomes active. `smoothTransition` is the default easing; `cosineTransition` and stepped progress support existing edition rhythms. Keep custom easing functions stable. Camera actions and lazy layout loading stay in the edition.
 
 Edition chunk scripts can call `runNetworkChunkCli()` from `@motionstudies/data/network-chunk-cli`. It accepts the existing `--input`, `--manifest`, `--opening`, `--chunk-hours`, `--opening-start`, `--opening-end`, and `--focus` arguments. Source acquisition, provenance, output paths and command invocation remain edition-owned.
+
+For timetable-backed vehicle selections, `NetworkVehicleHeroCard` from `@motionstudies/web/components/NetworkVehicleHeroCard` accepts `snapshot`, `train`, playback `time`, a required source `note` and the vehicle card's presentation/state/label options. Import `vehicle-hero-card.css`. It resolves the selected train ID against the current snapshot, retaining destination identity but showing no stale calls when that ID is absent. Calls stay in journey order, use stable journey/call IDs and follow backward seeking. During dwell the heading becomes `atStopLabel` (default “At stop”) and the time is the departure; otherwise it is the upcoming arrival. Times are formatted with `formatServiceTime` by default, without normalizing after midnight or adding delay twice. Use `showTimes={false}` for frequency-modelled journeys, and explain the model in `note`. The core `vehicleCalls` helper is also exported from `@motionstudies/core/domain/vehicle-calls` for custom adapters. Selection callback IDs refer to calls, not station indexes.

package/components/NetworkVehicleHeroCard.d.ts

@@ -0,0 +1,13 @@
+import { type NetworkSnapshot, type NetworkTrain } from '@motionstudies/core/domain/network';
+import { type VehicleHeroCardProps } from './VehicleHeroCard.tsx';
+export interface NetworkVehicleHeroCardProps extends Omit<VehicleHeroCardProps, 'vehicle' | 'stops'> {
+    readonly snapshot: NetworkSnapshot;
+    readonly train: NetworkTrain;
+    readonly time: number;
+    /** Hide clock values for frequency-based or otherwise approximate motion. */
+    readonly showTimes?: boolean;
+    readonly atStopLabel?: string;
+    readonly formatTime?: (time: number) => string;
+}
+/** Resolve the selected ID against the current chunk; never reuse stale stop indexes. */
+export declare function NetworkVehicleHeroCard({ snapshot, train, time, showTimes, atStopLabel, formatTime, ...props }: NetworkVehicleHeroCardProps): import("react").JSX.Element;

package/components/NetworkVehicleHeroCard.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from 'react';
+import { formatServiceTime } from '@motionstudies/core/domain/network';
+import { vehicleCalls } from '@motionstudies/core/domain/vehicle-calls';
+import { VehicleHeroCard } from './VehicleHeroCard.js';
+/** Resolve the selected ID against the current chunk; never reuse stale stop indexes. */
+export function NetworkVehicleHeroCard({ snapshot, train, time, showTimes = true, atStopLabel = 'At stop', formatTime = (value) => formatServiceTime(value).slice(0, 5), ...props }) {
+    const current = useMemo(() => snapshot.trains.find(entry => entry.id === train.id), [snapshot, train.id]);
+    const calls = current ? vehicleCalls(snapshot, current, time) : [];
+    const identity = current ?? train;
+    return _jsx(VehicleHeroCard, { ...props, vehicle: { service: identity.route || identity.shortName,
+            destination: identity.headsign.trim() || undefined }, labels: { ...props.labels, ...(calls[0]?.atStop ? { nextStop: atStopLabel } : {}) }, stops: calls.map(call => ({ ...call, time: showTimes ? formatTime(call.time) : undefined })) });
+}

package/components/VehicleHeroCard.d.ts

@@ -0,0 +1,51 @@
+import { type ReactNode } from 'react';
+export type VehicleHeroPresentation = 'uk-bus' | 'uk-rail' | 'yellow-bus' | 'sbb';
+export interface VehicleCallingPoint {
+    readonly id: string;
+    readonly name: string;
+    /** Consumer-formatted arrival time or estimate. Omit when unknown. */
+    readonly time?: string;
+    readonly platform?: string;
+    readonly detail?: string;
+    /** Set only for a confirmed destination, never just the end of a data chunk. */
+    readonly isDestination?: boolean;
+}
+declare const defaultLabels: {
+    bus: string;
+    rail: string;
+    destination: string;
+    destinationUnknown: string;
+    nextStop: string;
+    callingAt: string;
+    terminus: string;
+    platform: string;
+    loading: string;
+    empty: string;
+    retry: string;
+};
+export interface VehicleHeroCardProps {
+    readonly vehicle: {
+        readonly service: string;
+        readonly destination?: string;
+        readonly operator?: string;
+        readonly description?: string;
+    };
+    /** Remaining calls in journey order, starting with the next stop. The consumer owns playback/filtering. */
+    readonly stops: readonly VehicleCallingPoint[];
+    readonly presentation?: VehicleHeroPresentation;
+    /** Explicit source/freshness explanation. */
+    readonly note: ReactNode;
+    readonly status?: string;
+    readonly statusTone?: 'neutral' | 'warning';
+    readonly clockLabel?: string;
+    readonly labels?: Partial<typeof defaultLabels>;
+    readonly loading?: boolean;
+    readonly error?: string;
+    readonly onRetry?: () => void;
+    readonly onSelectStop?: (id: string) => void;
+    readonly selectedStopId?: string;
+    readonly className?: string;
+}
+/** An onboard view of one vehicle; no destination, timing or operational status is inferred. */
+export declare function VehicleHeroCard({ vehicle, stops, presentation, note, status, statusTone, clockLabel, labels, loading, error, onRetry, onSelectStop, selectedStopId, className }: VehicleHeroCardProps): import("react").JSX.Element;
+export {};

package/components/VehicleHeroCard.js

@@ -0,0 +1,21 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+const defaultLabels = {
+    bus: 'Bus', rail: 'Train', destination: 'Destination', destinationUnknown: 'Destination unavailable',
+    nextStop: 'Next stop', callingAt: 'Then calling at', terminus: 'Destination', platform: 'Platform',
+    loading: 'Loading upcoming stops…', empty: 'No upcoming stops available.', retry: 'Retry',
+};
+/** An onboard view of one vehicle; no destination, timing or operational status is inferred. */
+export function VehicleHeroCard({ vehicle, stops, presentation = 'uk-rail', note, status, statusTone = 'neutral', clockLabel, labels, loading, error, onRetry, onSelectStop, selectedStopId, className = '' }) {
+    const titleId = useId();
+    const copy = { ...defaultLabels, ...labels };
+    const bus = presentation === 'uk-bus' || presentation === 'yellow-bus';
+    const [next, ...following] = stops;
+    const stopContent = (stop) => _jsxs(_Fragment, { children: [_jsxs("span", { className: "ms-vehicle-hero__stop-name", children: [stop.name, stop.isDestination && _jsx("small", { children: copy.terminus }), stop.detail && _jsx("span", { className: "ms-vehicle-hero__detail", children: stop.detail })] }), (stop.time || stop.platform) && _jsxs("span", { className: "ms-vehicle-hero__timing", children: [stop.time && _jsx("strong", { children: stop.time }), stop.platform && _jsxs("small", { children: [copy.platform, " ", stop.platform] })] })] });
+    const renderStop = (stop) => onSelectStop
+        ? _jsx("button", { type: "button", className: "ms-vehicle-hero__stop", "aria-pressed": selectedStopId === stop.id, onClick: () => onSelectStop(stop.id), children: stopContent(stop) })
+        : _jsx("div", { className: "ms-vehicle-hero__stop", children: stopContent(stop) });
+    return _jsxs("section", { className: `ms-vehicle-hero ${className}`, "data-presentation": presentation, "aria-labelledby": titleId, "aria-busy": loading || undefined, children: [_jsxs("div", { className: "ms-vehicle-hero__masthead", children: [_jsxs("span", { children: [bus ? copy.bus : copy.rail, vehicle.operator ? ` · ${vehicle.operator}` : ''] }), clockLabel && _jsx("span", { children: clockLabel })] }), _jsxs("div", { className: "ms-vehicle-hero__identity", children: [_jsx("strong", { className: "ms-vehicle-hero__service", children: vehicle.service }), _jsxs("div", { children: [_jsx("p", { className: "ms-vehicle-hero__eyebrow", children: copy.destination }), _jsx("h2", { id: titleId, children: vehicle.destination || copy.destinationUnknown }), vehicle.description && _jsx("p", { className: "ms-vehicle-hero__description", children: vehicle.description })] })] }), status && _jsx("div", { className: "ms-vehicle-hero__status", "data-tone": statusTone, children: status }), error ? _jsxs("div", { className: "ms-vehicle-hero__message", role: "status", children: [error, onRetry && _jsx("button", { type: "button", onClick: onRetry, children: copy.retry })] })
+                : loading ? _jsx("div", { className: "ms-vehicle-hero__message", role: "status", children: copy.loading })
+                    : next ? _jsxs("div", { className: "ms-vehicle-hero__journey", children: [_jsxs("div", { className: "ms-vehicle-hero__next", children: [_jsx("p", { className: "ms-vehicle-hero__eyebrow", children: copy.nextStop }), renderStop(next)] }), following.length > 0 && _jsxs("div", { className: "ms-vehicle-hero__following", children: [_jsx("p", { className: "ms-vehicle-hero__eyebrow", children: copy.callingAt }), _jsx("ol", { children: following.map((stop) => _jsx("li", { "data-terminus": stop.isDestination || undefined, children: renderStop(stop) }, stop.id)) })] })] }) : _jsx("div", { className: "ms-vehicle-hero__message", role: "status", children: copy.empty }), _jsx("div", { className: "ms-vehicle-hero__note", children: note })] });
+}

package/components/vehicle-hero-card.css

@@ -0,0 +1,64 @@
+.ms-vehicle-hero {
+  --vehicle-bg: #101820; --vehicle-panel: #070b10; --vehicle-ink: #f1b94f;
+  --vehicle-text: #f4f4ed; --vehicle-muted: #a9b2ba; --vehicle-line: #33404b;
+  --vehicle-badge: #183b55; --vehicle-badge-ink: #fff;
+  container-type: inline-size; width: 100%; min-width: 0; overflow: hidden;
+  border: 1px solid var(--vehicle-line); border-radius: 8px;
+  background: var(--vehicle-bg); color: var(--vehicle-text); font: 16px/1.4 Arial, Helvetica, sans-serif;
+}
+.ms-vehicle-hero, .ms-vehicle-hero * { box-sizing: border-box; }
+.ms-vehicle-hero[data-presentation="uk-bus"] {
+  --vehicle-bg: #1a201d; --vehicle-panel: #080d09; --vehicle-ink: #ffbd59;
+  --vehicle-badge: #ffbd59; --vehicle-badge-ink: #10150e; --vehicle-line: #3c473d;
+}
+.ms-vehicle-hero[data-presentation="sbb"] {
+  --vehicle-bg: #fff; --vehicle-panel: #123579; --vehicle-ink: #fff; --vehicle-text: #162846;
+  --vehicle-muted: #54647c; --vehicle-line: #d5dce6; --vehicle-badge: #eb0000; --vehicle-badge-ink: #fff;
+  border-radius: 2px;
+}
+.ms-vehicle-hero[data-presentation="yellow-bus"] {
+  --vehicle-bg: #fffcf3; --vehicle-panel: #ffdc00; --vehicle-ink: #202318; --vehicle-text: #202318;
+  --vehicle-muted: #62624e; --vehicle-line: #d9d5bd; --vehicle-badge: #202318; --vehicle-badge-ink: #ffdc00;
+  border-radius: 2px;
+}
+.ms-vehicle-hero__masthead { display: flex; justify-content: space-between; gap: 12px; padding: 15px 24px; color: var(--vehicle-muted); font-size: 12px; font-variant-numeric: tabular-nums; border-bottom: 1px solid var(--vehicle-line); }
+.ms-vehicle-hero__masthead span { overflow-wrap: anywhere; }
+.ms-vehicle-hero__identity { display: grid; grid-template-columns: auto minmax(0, 1fr); align-items: start; gap: 20px; padding: 28px 24px; }
+.ms-vehicle-hero__service { background: var(--vehicle-badge); color: var(--vehicle-badge-ink); font-size: clamp(22px, 6cqi, 36px); padding: 8px 12px; line-height: 1.1; max-width: 160px; overflow-wrap: anywhere; }
+.ms-vehicle-hero__eyebrow { margin: 0 0 8px; font-size: 11px; letter-spacing: .12em; text-transform: uppercase; font-weight: 600; }
+.ms-vehicle-hero__identity h2 { margin: 0; font-size: clamp(24px, 5.5cqi, 38px); line-height: 1.12; letter-spacing: -.035em; overflow-wrap: anywhere; font-weight: 600; }
+.ms-vehicle-hero__description { color: var(--vehicle-muted); font-size: 13px; margin: 10px 0 0; overflow-wrap: anywhere; }
+.ms-vehicle-hero__status { margin: 0 24px 20px; padding: 9px 12px; border-left: 3px solid var(--vehicle-muted); font-size: 13px; overflow-wrap: anywhere; }
+.ms-vehicle-hero__status[data-tone="warning"] { border-color: #c87d00; background: #ffe6ae; color: #493000; }
+.ms-vehicle-hero__next { background: var(--vehicle-panel); color: var(--vehicle-ink); padding: 20px 24px 24px; }
+.ms-vehicle-hero__next .ms-vehicle-hero__stop-name { font-size: clamp(23px, 5cqi, 34px); line-height: 1.16; }
+.ms-vehicle-hero[data-presentation^="uk-"] .ms-vehicle-hero__next { font-family: ui-monospace, 'SFMono-Regular', Consolas, monospace; }
+.ms-vehicle-hero__stop { display: flex; align-items: baseline; justify-content: space-between; gap: 16px; padding: 8px 0; min-width: 0; width: 100%; text-align: left; color: inherit; font: inherit; }
+.ms-vehicle-hero button.ms-vehicle-hero__stop { border: 0; border-radius: 0; background: none; cursor: pointer; }
+.ms-vehicle-hero button.ms-vehicle-hero__stop:hover { box-shadow: 0 1px currentColor; }
+.ms-vehicle-hero button.ms-vehicle-hero__stop[aria-pressed="true"] { box-shadow: 0 2px currentColor; }
+.ms-vehicle-hero button:focus-visible { outline: 2px solid currentColor; outline-offset: 3px; }
+.ms-vehicle-hero__stop-name { min-width: 0; overflow-wrap: anywhere; font-size: 17px; font-weight: 600; }
+.ms-vehicle-hero__stop small, .ms-vehicle-hero__detail { display: block; font: 12px/1.5 Arial, Helvetica, sans-serif; margin-top: 5px; }
+.ms-vehicle-hero__timing { flex-shrink: 0; max-width: 40%; text-align: right; overflow-wrap: anywhere; font-variant-numeric: tabular-nums; }
+.ms-vehicle-hero__timing strong { font-size: 16px; font-weight: 500; }
+.ms-vehicle-hero__following { padding: 24px; }
+.ms-vehicle-hero__following > p { color: var(--vehicle-muted); }
+.ms-vehicle-hero__following ol { list-style: none; padding: 0 0 0 20px; margin: 14px 0 0; }
+.ms-vehicle-hero__following li { position: relative; padding: 2px 0 14px 14px; border-left: 2px solid var(--vehicle-line); }
+.ms-vehicle-hero__following li:last-child { padding-bottom: 0; border-color: transparent; }
+.ms-vehicle-hero__following li:last-child::after { content: ''; position: absolute; left: -2px; top: 0; width: 2px; height: 18px; background: var(--vehicle-line); }
+.ms-vehicle-hero__following li::before { content: ''; position: absolute; width: 9px; height: 9px; border: 2px solid var(--vehicle-text); background: var(--vehicle-bg); border-radius: 50%; left: -5.5px; top: 18px; }
+.ms-vehicle-hero__following li[data-terminus]::before { background: var(--vehicle-text); }
+.ms-vehicle-hero__message { padding: 28px 24px; min-height: 120px; display: flex; flex-wrap: wrap; align-items: center; gap: 16px; overflow-wrap: anywhere; }
+.ms-vehicle-hero__message button { padding: 8px 12px; border: 1px solid currentColor; color: inherit; background: transparent; font: inherit; cursor: pointer; }
+.ms-vehicle-hero__note { padding: 16px 24px; border-top: 1px solid var(--vehicle-line); color: var(--vehicle-muted); font-size: 11px; line-height: 1.6; overflow-wrap: anywhere; }
+@container (max-width: 360px) {
+  .ms-vehicle-hero__identity { gap: 12px; padding: 22px 16px; }
+  .ms-vehicle-hero__service { max-width: 100px; padding: 8px; }
+  .ms-vehicle-hero__masthead, .ms-vehicle-hero__next, .ms-vehicle-hero__following, .ms-vehicle-hero__note, .ms-vehicle-hero__message { padding-left: 16px; padding-right: 16px; }
+  .ms-vehicle-hero__status { margin-left: 16px; margin-right: 16px; }
+  .ms-vehicle-hero__stop { gap: 10px; }
+  .ms-vehicle-hero__next .ms-vehicle-hero__stop { flex-wrap: wrap; }
+  .ms-vehicle-hero__next .ms-vehicle-hero__timing { max-width: 100%; text-align: left; }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionstudies/web",
-  "version": "0.1.0-alpha.11",
+  "version": "0.1.0-alpha.12",
   "private": false,
   "type": "module",
   "description": "Browser controls and loaders for Motion Studies.",
@@ -121,6 +121,12 @@
       "import": "./components/BusStopHeroCard.js",
       "default": "./components/BusStopHeroCard.js"
     },
+    "./components/VehicleHeroCard": {
+      "types": "./components/VehicleHeroCard.d.ts",
+      "import": "./components/VehicleHeroCard.js",
+      "default": "./components/VehicleHeroCard.js"
+    },
+    "./vehicle-hero-card.css": "./components/vehicle-hero-card.css",
     "./components/RailStationHeroCard": {
       "types": "./components/RailStationHeroCard.d.ts",
       "import": "./components/RailStationHeroCard.js",
@@ -136,6 +142,11 @@
       "types": "./use-transition-value.d.ts",
       "import": "./use-transition-value.js",
       "default": "./use-transition-value.js"
+    },
+    "./components/NetworkVehicleHeroCard": {
+      "types": "./components/NetworkVehicleHeroCard.d.ts",
+      "import": "./components/NetworkVehicleHeroCard.js",
+      "default": "./components/NetworkVehicleHeroCard.js"
     }
   },
   "files": [
@@ -151,7 +162,7 @@
     "**/*.css"
   ],
   "dependencies": {
-    "@motionstudies/core": "0.1.0-alpha.11"
+    "@motionstudies/core": "0.1.0-alpha.12"
   },
   "peerDependencies": {
     "react": "^19.2.8",