@motionstudies/web 0.1.0-alpha.21 → 0.1.0-alpha.23

package/README.md

@@ -259,3 +259,11 @@ The lab's **Fields** specimen renders a synthetic archipelago of seven instrumen
 ## Recorded power days
 
 `@motionstudies/core/domain/power-day` exports `readPowerDay`, `powerPeriod`, `unitPower`, `plannedPower`, `sumPower` and `fuelMixAt`, plus their data types. A complete civil day declares its timezone, UTC bounds, half-hour intervals, MWh settlement quantities and MW plans/aggregates. Missing values remain null; signed quantities remain signed. Interval energy becomes average power only through the explicit interval duration. Declarations are interpolated only within one unambiguous segment; fuel samples expire after five minutes. Callers choose aggregate membership and receive a missing-contributor count. The reader validates source links, settlement run labels, identities, placement coordinates and safe evidence-artifact paths without fetching data. Source adapters, placement policy and the composition stay outside core. See [power ownership](../docs/POWER.md#ownership-and-handoff).
+
+## Activity timeline
+
+`@motionstudies/core/timeline` supplies validated interval geometry, lookup, time mapping and service-time formatting. `@motionstudies/web/components/StudyTimeline` renders a controlled activity chart and scrubber; import `@motionstudies/web/study-timeline.css`. Pass `bins: {start, end, value}[]`, the time window, current `time` and `onSeek`. A `null` value means missing evidence; zero is a measured zero. `variant="bars"` (default) or `"line"` shares the same time axis. `maximum` optionally fixes the scale for comparisons. Playback and loading remain consumer-owned. See [the full contract](https://github.com/emmettl/motionstudies/blob/main/docs/STUDY-TIMELINE.md) and the Timeline lab specimen.
+
+Canvas editions can import `PausedVehicleFrame` from `@motionstudies/core/render-frame` without loading Three.js. The existing Three.js entry point re-exports the same class. Record only a frame actually submitted; change its visibility revision (or replace the tracker) when data, projection, size or selection changes. Time changes invalidate even while paused.
+
+Plain playback bars can use `@motionstudies/web/components/TimelineScrubber` with `@motionstudies/web/timeline-scrubber.css`: the same visible rail and 44px interaction area as `StudyTimeline`, without activity bins. Pass the time window, time, seek callback and accessible time label.

package/components/StudyTimeline.d.ts

@@ -0,0 +1,25 @@
+import { type TimelineBin } from '@motionstudies/core/timeline';
+export interface StudyTimelineProps {
+    bins: readonly TimelineBin[];
+    windowStart: number;
+    windowEnd: number;
+    time: number;
+    onSeek: (time: number) => void;
+    label: string;
+    ariaLabel?: string;
+    description?: string;
+    variant?: 'bars' | 'line';
+    step?: number;
+    maximum?: number;
+    disabled?: boolean;
+    formatTime?: (time: number) => string;
+    formatValue?: (value: number) => string;
+    missingLabel?: string;
+    emptyLabel?: string;
+    scaleLabel?: string;
+    onScrubStart?: () => void;
+    onScrubEnd?: () => void;
+    className?: string;
+}
+/** Controlled chart and scrubber. Playback, loading and date/timezone policy belong to the study. */
+export declare function StudyTimeline({ bins, windowStart, windowEnd, time, onSeek, label, ariaLabel, description, variant, step, maximum, disabled, formatTime, formatValue, missingLabel, emptyLabel, scaleLabel, onScrubStart, onScrubEnd, className }: StudyTimelineProps): import("react").JSX.Element;

package/components/StudyTimeline.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useMemo, useState } from 'react';
+import { TimelineScrubber } from './TimelineScrubber.js';
+import { createTimelineModel, formatTimelineTime, timelineBinAt, timelinePosition, timelineTime } from '@motionstudies/core/timeline';
+const formatCount = (value) => value.toLocaleString();
+/** Controlled chart and scrubber. Playback, loading and date/timezone policy belong to the study. */
+export function StudyTimeline({ bins, windowStart, windowEnd, time, onSeek, label, ariaLabel = label, description, variant = 'bars', step = 1, maximum, disabled = false, formatTime = formatTimelineTime, formatValue = formatCount, missingLabel = 'No observation', emptyLabel = 'No observations in this window', scaleLabel = 'Scale', onScrubStart, onScrubEnd, className = '' }) {
+    const id = useId(), [hover, setHover] = useState();
+    const model = useMemo(() => createTimelineModel(bins, { start: windowStart, end: windowEnd }, maximum), [bins, windowStart, windowEnd, maximum]);
+    const value = Number(timelineTime(timelinePosition(time, model.window), model.window, step).toPrecision(12)), position = timelinePosition(value, model.window);
+    const active = timelineBinAt(model, value), inspected = timelineBinAt(model, hover ?? value);
+    const reading = (amount) => amount == null ? missingLabel : formatValue(amount);
+    return _jsxs("div", { className: `ms-study-timeline ${className}`, "data-variant": variant, "data-disabled": disabled || undefined, children: [_jsxs("div", { className: "ms-study-timeline__heading", children: [_jsx("span", { id: `${id}-label`, children: label }), _jsxs("span", { className: "ms-study-timeline__reading", children: [formatTime(hover ?? value), " \u00B7 ", reading(inspected?.value)] })] }), _jsx(TimelineScrubber, { className: "ms-study-timeline__plot", windowStart: windowStart, windowEnd: windowEnd, time: value, onSeek: onSeek, step: step, disabled: disabled, ariaLabel: ariaLabel, describedBy: description ? `${id}-description` : undefined, ariaValueText: `${formatTime(value)} · ${reading(active?.value)}`, onScrubStart: onScrubStart, onScrubEnd: onScrubEnd, onInspect: setHover, children: _jsxs("div", { className: "ms-study-timeline__graph", "aria-hidden": "true", children: [_jsx("svg", { viewBox: "0 0 1000 100", preserveAspectRatio: "none", focusable: "false", children: variant === 'bars' ? model.bars.filter(bar => bar.value !== null && bar.value > 0).map(bar => _jsx("rect", { x: bar.x * 1000, y: (1 - bar.height) * 100, width: bar.width * 1000 * .8, height: bar.height * 100 }, bar.start)) : model.lines.map((line, i) => line.length === 1 ? _jsx("line", { x1: line[0].x * 1000 - 1, x2: line[0].x * 1000 + 1, y1: line[0].y * 100, y2: line[0].y * 100 }, i) : _jsx("polyline", { points: line.map(p => `${p.x * 1000},${p.y * 100}`).join(' ') }, i)) }), _jsx("span", { className: "ms-study-timeline__cursor", style: { left: `${position * 100}%` } }), !model.bars.some(bar => bar.value !== null) && _jsx("span", { className: "ms-study-timeline__empty", children: emptyLabel })] }) }), _jsx("div", { className: "ms-study-timeline__ticks", "aria-hidden": "true", children: [0, .25, .5, .75, 1].map(fraction => _jsx("span", { children: formatTime(windowStart + fraction * (windowEnd - windowStart)) }, fraction)) }), _jsxs("div", { className: "ms-study-timeline__footnote", children: [description && _jsx("span", { id: `${id}-description`, children: description }), _jsxs("span", { children: [scaleLabel, " 0\u2013", formatValue(model.maximum)] })] })] });
+}

package/components/TimelineScrubber.d.ts

@@ -0,0 +1,19 @@
+import { type ReactNode } from 'react';
+export interface TimelineScrubberProps {
+    windowStart: number;
+    windowEnd: number;
+    time: number;
+    onSeek: (time: number) => void;
+    ariaLabel: string;
+    ariaValueText?: string;
+    describedBy?: string;
+    step?: number;
+    disabled?: boolean;
+    onScrubStart?: () => void;
+    onScrubEnd?: () => void;
+    onInspect?: (time: number | undefined) => void;
+    children?: ReactNode;
+    className?: string;
+}
+/** Shared visible rail and native range interaction; the caller owns the clock. */
+export declare function TimelineScrubber({ windowStart, windowEnd, time, onSeek, ariaLabel, ariaValueText, describedBy, step, disabled, onScrubStart, onScrubEnd, onInspect, children, className }: TimelineScrubberProps): import("react").JSX.Element;

package/components/TimelineScrubber.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useRef } from 'react';
+import { timelinePosition, timelineTime } from '@motionstudies/core/timeline';
+/** Shared visible rail and native range interaction; the caller owns the clock. */
+export function TimelineScrubber({ windowStart, windowEnd, time, onSeek, ariaLabel, ariaValueText, describedBy, step = 1, disabled = false, onScrubStart, onScrubEnd, onInspect, children, className = '' }) {
+    const id = useId(), scrubbing = useRef(false);
+    const window = { start: windowStart, end: windowEnd };
+    const position = timelinePosition(time, window);
+    const value = Number.isFinite(time) ? Math.max(windowStart, Math.min(windowEnd, time)) : windowStart;
+    if (!Number.isFinite(step) || step <= 0)
+        throw new Error('Timeline step must be positive');
+    const begin = () => { if (!disabled && !scrubbing.current) {
+        scrubbing.current = true;
+        onScrubStart?.();
+    } };
+    const finish = () => { if (scrubbing.current) {
+        scrubbing.current = false;
+        onScrubEnd?.();
+    } };
+    return _jsxs("div", { className: `ms-timeline-scrubber ${className}`, "data-disabled": disabled || undefined, style: { '--ms-timeline-position': `${position * 100}%` }, children: [children, _jsxs("div", { className: "ms-timeline-scrubber__rail", "aria-hidden": "true", children: [_jsx("span", { className: "ms-timeline-scrubber__fill" }), _jsx("span", { className: "ms-timeline-scrubber__thumb" })] }), _jsx("input", { id: id, type: "range", "aria-label": ariaLabel, "aria-valuetext": ariaValueText, "aria-describedby": describedBy, min: windowStart, max: windowEnd, step: step, value: value, disabled: disabled, onChange: event => onSeek(Number(event.target.value)), onPointerDown: event => { if (!disabled) {
+                    event.currentTarget.setPointerCapture(event.pointerId);
+                    begin();
+                } }, onPointerUp: finish, onPointerCancel: finish, onLostPointerCapture: finish, onBlur: () => { finish(); onInspect?.(undefined); }, onKeyDown: event => { if (['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End', 'PageUp', 'PageDown'].includes(event.key))
+                    begin(); }, onKeyUp: finish, onPointerMove: event => { if (disabled || event.pointerType === 'touch' || !onInspect)
+                    return; const box = event.currentTarget.getBoundingClientRect(); onInspect(timelineTime((event.clientX - box.left - 22) / Math.max(1, box.width - 44), window, step)); }, onPointerLeave: () => onInspect?.(undefined) })] });
+}

package/components/study-timeline.css

@@ -0,0 +1,8 @@
+@import "./timeline-scrubber.css";
+.ms-study-timeline{--ms-timeline-ink:#dce7eb;--ms-timeline-muted:#8ba3af;--ms-timeline-accent:#e2bc7c;--ms-timeline-chart:#668b9e;--ms-timeline-height:48px;min-width:0;color:var(--ms-timeline-ink);font:10px/1.5 ui-monospace,monospace}
+.ms-study-timeline__heading{display:flex;align-items:baseline;justify-content:space-between;gap:12px;min-height:20px}.ms-study-timeline__reading{white-space:nowrap;color:var(--ms-timeline-accent);font-variant-numeric:tabular-nums}
+.ms-study-timeline__plot{position:relative;height:calc(var(--ms-timeline-height) + 44px);margin-top:4px;isolation:isolate}.ms-study-timeline__graph{position:absolute;inset:4px 22px 22px;border-bottom:1px solid var(--ms-timeline-muted);pointer-events:none}.ms-study-timeline svg{display:block;width:100%;height:100%;overflow:visible}.ms-study-timeline rect{fill:var(--ms-timeline-chart)}.ms-study-timeline polyline,.ms-study-timeline line{fill:none;stroke:var(--ms-timeline-chart);stroke-width:1.5;vector-effect:non-scaling-stroke;stroke-linecap:round;stroke-linejoin:round}
+.ms-study-timeline__cursor{position:absolute;top:0;bottom:-1px;width:1px;background:var(--ms-timeline-accent);transform:translateX(-.5px)}
+.ms-study-timeline__ticks{display:flex;justify-content:space-between;gap:8px;padding:0 22px;font-size:9px;font-variant-numeric:tabular-nums;color:var(--ms-timeline-muted)}.ms-study-timeline__footnote{display:flex;justify-content:space-between;flex-wrap:wrap;gap:4px 14px;margin-top:8px;font-size:9px;color:var(--ms-timeline-muted)}.ms-study-timeline__footnote>span:last-child{margin-left:auto}.ms-study-timeline__empty{position:absolute;inset:0;display:grid;place-items:center;color:var(--ms-timeline-muted);font-size:10px}.ms-study-timeline[data-disabled] input{cursor:default}
+@media(max-width:480px){.ms-study-timeline__heading{gap:4px;flex-wrap:wrap;font-size:9px}.ms-study-timeline__ticks,.ms-study-timeline__footnote{font-size:8px}}
+@media(forced-colors:active){.ms-study-timeline{--ms-timeline-ink:CanvasText;--ms-timeline-muted:CanvasText;--ms-timeline-accent:Highlight;--ms-timeline-chart:CanvasText}}

package/components/timeline-scrubber.css

@@ -0,0 +1,16 @@
+.ms-timeline-scrubber{position:relative;min-width:44px;min-height:44px;direction:ltr;isolation:isolate}
+.ms-timeline-scrubber__rail{position:absolute;left:22px;right:22px;bottom:18px;height:8px;border-radius:4px;background:var(--ms-timeline-track,#334650);box-shadow:inset 0 0 0 1px var(--ms-timeline-track-border,#627780);pointer-events:none}
+.ms-timeline-scrubber__fill{position:absolute;inset:0 auto 0 0;width:var(--ms-timeline-position);border-radius:inherit;background:var(--ms-timeline-accent,#acc9b9)}
+.ms-timeline-scrubber__thumb{position:absolute;left:var(--ms-timeline-position);top:50%;width:20px;height:20px;box-sizing:border-box;border:2px solid var(--ms-timeline-accent,#acc9b9);border-radius:50%;background:var(--ms-timeline-accent,#acc9b9);transform:translate(-50%,-50%);box-shadow:0 0 0 3px var(--ms-timeline-halo,#0c172080)}
+.ms-timeline-scrubber input[type=range]{position:absolute;inset:0;display:block;box-sizing:border-box;width:100%;height:100%;min-height:44px;margin:0;padding:0;border:0;opacity:0;cursor:grab;touch-action:pan-y;appearance:none;-webkit-appearance:none;direction:ltr}
+.ms-timeline-scrubber input[type=range]:active{cursor:grabbing}
+.ms-timeline-scrubber input[type=range]::-webkit-slider-thumb{appearance:none;-webkit-appearance:none;box-sizing:border-box;width:44px;height:44px;margin:0;border:0;border-radius:0;background:transparent;box-shadow:none}
+.ms-timeline-scrubber input[type=range]::-moz-range-thumb{width:44px;height:44px;box-sizing:border-box;border:0;border-radius:0}
+.ms-timeline-scrubber:focus-within{outline:2px solid var(--ms-timeline-accent,#acc9b9);outline-offset:2px;border-radius:4px}
+.ms-timeline-scrubber[data-disabled]{opacity:.55}.ms-timeline-scrubber[data-disabled] input{cursor:default}
+@media(forced-colors:active){.ms-timeline-scrubber{--ms-timeline-accent:Highlight;--ms-timeline-track:Canvas;--ms-timeline-track-border:CanvasText;--ms-timeline-halo:Canvas}.ms-timeline-scrubber__rail{border:1px solid CanvasText;box-sizing:border-box}.ms-timeline-scrubber__fill,.ms-timeline-scrubber__thumb{forced-color-adjust:none}}
+
+.ms-timeline-scrubber input[type=range]::-webkit-slider-runnable-track{height:44px;border:0;background:transparent}
+.ms-timeline-scrubber input[type=range]::-moz-range-track{height:44px;border:0;background:transparent}
+
+.ms-timeline-scrubber input[type=range]:disabled{opacity:0;cursor:default}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionstudies/web",
-  "version": "0.1.0-alpha.21",
+  "version": "0.1.0-alpha.23",
   "private": false,
   "type": "module",
   "description": "Browser controls and loaders for Motion Studies.",
@@ -154,7 +154,19 @@
       "default": "./components/NetworkVehicleHeroCard.js"
     },
     "./study-layout.css": "./study-layout.css",
-    "./fonts.css": "./fonts.css"
+    "./fonts.css": "./fonts.css",
+    "./components/StudyTimeline": {
+      "types": "./components/StudyTimeline.d.ts",
+      "import": "./components/StudyTimeline.js",
+      "default": "./components/StudyTimeline.js"
+    },
+    "./study-timeline.css": "./components/study-timeline.css",
+    "./components/TimelineScrubber": {
+      "types": "./components/TimelineScrubber.d.ts",
+      "import": "./components/TimelineScrubber.js",
+      "default": "./components/TimelineScrubber.js"
+    },
+    "./timeline-scrubber.css": "./components/timeline-scrubber.css"
   },
   "files": [
     "**/*.js",
@@ -171,7 +183,7 @@
     "**/*.css"
   ],
   "dependencies": {
-    "@motionstudies/core": "0.1.0-alpha.21"
+    "@motionstudies/core": "0.1.0-alpha.23"
   },
   "peerDependencies": {
     "react": "^19.2.8",