@matchstick-trading/primitives 0.0.10

package/src/ScrubberParts.tsx

@@ -0,0 +1,207 @@
+import { createContext, useCallback, useContext, useMemo, useRef, useState, type CSSProperties, type KeyboardEvent, type PointerEvent, type ReactNode } from 'react';
+import { clampFraction, fractionFromPointer, isActiveScrubPointer, isPrimaryScrubPointer, reduceScrubGesture, resolveScrubKey, type ScrubGestureEvent } from './core/scrubber-gesture.js';
+
+/**
+ * Scrubber as parts: Root, Track, Thumb, Mark. Headless: the parts render the elements the evidence
+ * ruler always did, add `data-state` / `data-disabled`, and work in fractions of the track. The host owns what a
+ * fraction means (a place in its session), the copy, and the look.
+ *
+ * Root renders no DOM. It owns the preview while a pointer is down, so `useScrubber()` gives a readout the live
+ * fraction; nothing is committed until release, and then exactly once through `onCommit`.
+ */
+interface ScrubberContext {
+  /** Where the thumb is drawn: the preview while dragging, else the committed fraction. */
+  fraction: number;
+  committedFraction: number;
+  dragging: boolean;
+  loading: boolean;
+  trackHandlers: {
+    onPointerDown: (event: PointerEvent<HTMLElement>) => void;
+    onPointerMove: (event: PointerEvent<HTMLElement>) => void;
+    onPointerUp: (event: PointerEvent<HTMLElement>) => void;
+    onPointerCancel: (event: PointerEvent<HTMLElement>) => void;
+  };
+  onThumbKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+}
+
+const Context = createContext<ScrubberContext | null>(null);
+
+/** The live scrub state, for a readout that must follow the preview. Throws a plain message outside a `Scrubber.Root`. */
+export function useScrubber(): Pick<ScrubberContext, 'fraction' | 'committedFraction' | 'dragging' | 'loading'> {
+  const context = useContext(Context);
+  if (!context) throw new Error('useScrubber needs a Scrubber.Root above it: there is no scrub state to read.');
+  const { fraction, committedFraction, dragging, loading } = context;
+  return { fraction, committedFraction, dragging, loading };
+}
+
+export interface ScrubberRootProps {
+  /** Where the host's cursor sits on the track, 0 to 1. */
+  fraction: number;
+  /** Another navigation is running: a new scrub does not start, keys do nothing, and a release does not commit. */
+  loading?: boolean;
+  onBeginScrub?: () => void;
+  onEndScrub?: () => void;
+  /** A release (or Home, End, PageUp, PageDown) resolved to this fraction. Called once per gesture. */
+  onCommit: (fraction: number) => void;
+  /** An arrow key: step one event in this direction. The host decides what "one event" is. */
+  onStep: (direction: -1 | 1) => void;
+  children?: ReactNode;
+}
+
+function Root({ fraction: committedInput, loading = false, onBeginScrub, onEndScrub, onCommit, onStep, children }: ScrubberRootProps) {
+  const committedFraction = committedInput;
+  const [dragFraction, setDragFraction] = useState<number | null>(null);
+  // Which pointer owns the drag: a ref, because the very next pointer event of the same gesture must read it
+  // before any state update has been applied.
+  const activePointerId = useRef<number | null>(null);
+  const live = useRef({ dragFraction, loading, onBeginScrub, onEndScrub, onCommit, onStep, committedFraction });
+  live.current = { dragFraction, loading, onBeginScrub, onEndScrub, onCommit, onStep, committedFraction };
+
+  const apply = useCallback((event: ScrubGestureEvent) => {
+    const now = live.current;
+    const result = reduceScrubGesture(event, now.dragFraction);
+    // The ref is updated here as well as at render, so two events in one frame still see the latest preview.
+    live.current = { ...now, dragFraction: result.dragFraction };
+    setDragFraction(result.dragFraction);
+    if (result.begin) now.onBeginScrub?.();
+    if (result.end) now.onEndScrub?.();
+    if (result.commit !== null) now.onCommit(result.commit);
+  }, []);
+
+  const fractionAt = (event: PointerEvent<HTMLElement>) => {
+    const rect = event.currentTarget.getBoundingClientRect();
+    return fractionFromPointer(event.clientX, rect.left, rect.width);
+  };
+
+  const trackHandlers = useMemo<ScrubberContext['trackHandlers']>(() => ({
+    onPointerDown(event) {
+      if (live.current.loading) return;
+      // Gate before capturing: a right-click must reach the browser's own menu, and a second finger must not start a scrub.
+      if (!isPrimaryScrubPointer(event)) return;
+      // Without this, a press after a text selection starts a native drag and the browser cancels the pointer.
+      event.preventDefault();
+      // preventDefault also stops the browser focusing what was pressed, so a press on the thumb focuses it here.
+      const pressed = event.target instanceof Element ? event.target.closest<HTMLElement>('[tabindex]') : null;
+      if (pressed && event.currentTarget.contains(pressed)) pressed.focus({ preventScroll: true });
+      activePointerId.current = event.pointerId;
+      event.currentTarget.setPointerCapture(event.pointerId);
+      apply({ type: 'down', fraction: fractionAt(event) });
+    },
+    onPointerMove(event) {
+      if (!isActiveScrubPointer(event.pointerId, activePointerId.current)) return;
+      apply({ type: 'move', fraction: fractionAt(event) });
+    },
+    onPointerUp(event) {
+      if (!isActiveScrubPointer(event.pointerId, activePointerId.current)) return;
+      activePointerId.current = null;
+      // The release's own coordinate, read the same way as a move; the last move may lag it.
+      apply({ type: 'up', fraction: fractionAt(event), loading: live.current.loading });
+      event.currentTarget.releasePointerCapture(event.pointerId);
+    },
+    onPointerCancel(event) {
+      if (!isActiveScrubPointer(event.pointerId, activePointerId.current)) return;
+      activePointerId.current = null;
+      apply({ type: 'cancel' });
+    },
+  }), [apply]);
+
+  const onThumbKeyDown = useCallback((event: KeyboardEvent<HTMLElement>) => {
+    const now = live.current;
+    if (now.loading) return;
+    const action = resolveScrubKey(event.key, now.committedFraction);
+    if (!action) return;
+    event.preventDefault();
+    if (action.type === 'step') {
+      // A host may also listen for arrows on the window; letting this bubble would step twice.
+      event.stopPropagation();
+      now.onStep(action.direction);
+    } else {
+      now.onCommit(action.fraction);
+    }
+  }, []);
+
+  const dragging = dragFraction !== null;
+  const context = useMemo<ScrubberContext>(() => ({
+    fraction: dragFraction ?? committedFraction,
+    committedFraction,
+    dragging,
+    loading,
+    trackHandlers,
+    onThumbKeyDown,
+  }), [dragFraction, committedFraction, dragging, loading, trackHandlers, onThumbKeyDown]);
+  return <Context.Provider value={context}>{children}</Context.Provider>;
+}
+
+function useContextOrThrow(part: string): ScrubberContext {
+  const context = useContext(Context);
+  if (!context) throw new Error(`Scrubber.${part} needs a Scrubber.Root above it.`);
+  return context;
+}
+
+/** The pressable area. Pointer handlers live here; marks and the thumb go inside it. */
+function Track({ className, children }: { className?: string; children?: ReactNode }) {
+  const { trackHandlers, dragging, loading } = useContextOrThrow('Track');
+  return (
+    <div className={className} {...trackHandlers} data-part="scrubber-track" data-state={dragging ? 'dragging' : 'idle'} data-disabled={loading ? '' : undefined}>
+      {children}
+    </div>
+  );
+}
+
+export interface ScrubberThumbProps {
+  className?: string;
+  /** Accessible name. */
+  label?: string;
+  /** What the position means in words (the host's readout); announced with the value. */
+  valueText?: string;
+  /** Ids of elements that describe the thumb, such as the first few gap marks. */
+  describedBy?: string;
+}
+
+const percent = (fraction: number) => `${(clampFraction(fraction) * 100).toFixed(3)}%`;
+
+/** The one tab stop: `role="slider"`, positioned at the live fraction. Arrows step, Home/End/PageUp/PageDown jump. */
+function Thumb({ className, label = 'Session position', valueText, describedBy }: ScrubberThumbProps) {
+  const { fraction, loading, onThumbKeyDown } = useContextOrThrow('Thumb');
+  return (
+    <div
+      className={className}
+      data-part="scrubber-thumb"
+      role="slider"
+      tabIndex={0}
+      aria-label={label}
+      aria-describedby={describedBy}
+      aria-disabled={loading || undefined}
+      aria-valuemin={0}
+      aria-valuemax={100}
+      aria-valuenow={Math.round(clampFraction(fraction) * 100)}
+      aria-valuetext={valueText}
+      style={{ left: percent(fraction) }}
+      onKeyDown={onThumbKeyDown}
+    />
+  );
+}
+
+export interface ScrubberMarkProps {
+  /** Left edge on the track, 0 to 1. */
+  at: number;
+  /** Width on the track, 0 to 1; leave out for a point. */
+  span?: number;
+  /** Accessible name; the mark is an image, not a control, and never a tab stop. */
+  label: string;
+  /** What kind of mark: lets a host style gaps and checkpoints apart. */
+  kind?: string;
+  title?: string;
+  /** `-1` makes the mark focusable by pointer but never a tab stop; leave out for a plain image. */
+  tabIndex?: -1;
+  id?: string;
+  className?: string;
+}
+
+/** A position on the track that informs but cannot be activated (a declared gap, a verified checkpoint). */
+function Mark({ at, span, label, kind, title, tabIndex, id, className }: ScrubberMarkProps) {
+  const style: CSSProperties = span === undefined ? { left: percent(at) } : { left: percent(at), width: percent(Math.max(0, span)) };
+  return <span id={id} className={className} data-part="scrubber-mark" data-kind={kind} style={style} role="img" tabIndex={tabIndex} title={title} aria-label={label} />;
+}
+
+export { Root, Track, Thumb, Mark };

package/src/Selection.tsx

@@ -0,0 +1,12 @@
+import type { Series as StudySeries } from './core/studies.js';
+import { Root, Layer, SeriesRoot, Select, Options } from './SelectionParts.js';
+
+// The parts live in SelectionParts.js (a client module). The namespace objects are built here, outside it, so a server
+// component can write `Selection.Root` and `Series.Root`: a property of an object exported from a client module is not
+// reachable there.
+export * from './SelectionParts.js';
+export const Selection = { Root, Layer };
+// `Series` is also the name of the study-values type in the core (`Series`, an array of numbers). A type and a value may
+// share a name, so the type keeps its meaning for anyone who already imports it.
+export type Series = StudySeries;
+export const Series = { Root: SeriesRoot, Select, Options };

package/src/SelectionParts.tsx

@@ -0,0 +1,251 @@
+import { useCallback, useContext, useEffect, useMemo, useRef, useState, type CSSProperties, type ReactNode } from 'react';
+import { buttonFace, type NameProps } from './accessible-name.js';
+import { useChart } from './ChartParts.js';
+import { SelectionContext, SeriesContext, type SelectionContextValue, type SelectionGuard, type SeriesContextValue } from './selection-context.js';
+import { describeSelection, sameSelection, selectionAfterEscape, selectionAfterTap, type ChartSelection, type SelectionNames } from './core/selection.js';
+
+/**
+ * Selection as parts: Selection.Root, Selection.Layer, and Series.Root, Series.Select, Series.Options. One thing is
+ * selected on a chart at a time: a drawing, the bar series or a study. Headless: the parts set `data-part` and
+ * `data-state='selected'`; the host gives them a look and fills the options panel with its own controls.
+ *
+ * Root holds the selection (controlled or not) and says each change in a polite live region. Everything is opt-in:
+ * without a Root above them, Drawings and Studies behave as they always did.
+ */
+
+export interface SelectionRootProps {
+  /** Controlled selection; without it Root keeps its own. */
+  selection?: ChartSelection;
+  onSelectionChange?: (selection: ChartSelection) => void;
+  children?: ReactNode;
+}
+
+// Visually hidden, still announced. Inline so the live region works without a stylesheet.
+const HIDDEN: CSSProperties = { position: 'absolute', width: 1, height: 1, margin: -1, padding: 0, overflow: 'hidden', clip: 'rect(0 0 0 0)', whiteSpace: 'nowrap', border: 0 };
+
+/** Holds the selection and announces changes. Wrap the Chart, the Drawings.Root and the series and study controls in it. */
+function Root({ selection, onSelectionChange, children }: SelectionRootProps) {
+  const [inner, setInner] = useState<ChartSelection>(null);
+  const current = selection !== undefined ? selection : inner;
+  // `latest` is the selection as the host supplied it, plus any change requested in the event being handled, so two parts
+  // agreeing on one tap report once. It goes back to the rendered value as soon as the event is over: a controlled host
+  // that declines a request is never left with a selection it did not accept.
+  const latest = useRef(current);
+  const rendered = useRef(current);
+  latest.current = current;
+  rendered.current = current;
+  const select = useCallback((next: ChartSelection) => {
+    if (sameSelection(latest.current, next)) return;
+    latest.current = next;
+    queueMicrotask(() => { latest.current = rendered.current; });
+    if (selection === undefined) setInner(next);
+    onSelectionChange?.(next);
+  }, [selection, onSelectionChange]);
+  const currentRef = useCallback(() => latest.current, []);
+
+  const [series, setSeries] = useState<{ id: string; label: string } | null>(null);
+  const selectRef = useRef(select);
+  selectRef.current = select;
+  const mounted = useRef<{ id: string; label: string } | null>(null);
+  const registerSeries = useCallback((next: { id: string; label: string }) => {
+    mounted.current = next;
+    setSeries(next);
+    return () => {
+      if (mounted.current === next) mounted.current = null;
+      setSeries((was) => (was && was.id === next.id ? null : was));
+      // A series that goes away cannot stay selected. A new label, or React replaying the effect, registers again in the
+      // same commit, so only a series still gone after that is removed.
+      queueMicrotask(() => {
+        const now = latest.current;
+        if (mounted.current?.id !== next.id && now && now.kind === 'series' && now.id === next.id) selectRef.current(null);
+      });
+    };
+  }, []);
+
+  const [names, setNames] = useState<SelectionNames>({});
+  const namesRef = useRef(names);
+  namesRef.current = names;
+  const setName = useCallback((kind: 'drawing' | 'series' | 'study', id: string, name: string) => {
+    setNames((was) => (was[kind]?.[id] === name ? was : { ...was, [kind]: { ...was[kind], [id]: name } }));
+    return () => {};
+  }, []);
+
+  const guard = useRef<SelectionGuard | null>(null);
+  const value = useMemo<SelectionContextValue>(
+    () => ({ selection: current, select, current: currentRef, series, registerSeries, setName, guard }),
+    [current, select, currentRef, series, registerSeries, setName],
+  );
+
+  const [status, setStatus] = useState('');
+  const seen = useRef(current === null ? '' : `${current.kind}:${current.id}`);
+  const usedId = useRef(false); // the last announcement had no name yet and said the id
+  const key = current === null ? '' : `${current.kind}:${current.id}`;
+  const nameNow = current === null ? undefined : names[current.kind]?.[current.id];
+  useEffect(() => {
+    if (seen.current === key && !(usedId.current && nameNow !== undefined)) return;
+    seen.current = key;
+    usedId.current = current !== null && nameNow === undefined;
+    setStatus(describeSelection(current, names));
+  }, [key, current, names, nameNow]);
+
+  return (
+    <SelectionContext.Provider value={value}>
+      {children}
+      <span data-part="selection-status" role="status" aria-live="polite" style={HIDDEN}>{status}</span>
+    </SelectionContext.Provider>
+  );
+}
+
+function useSelection(part: string): SelectionContextValue {
+  const context = useContext(SelectionContext);
+  if (!context) throw new Error(`${part} needs a Selection.Root above it.`);
+  return context;
+}
+
+const TAP_SLOP = 6;
+const TAP_MS = 600;
+
+/**
+ * The tap and Escape rules for the chart. Put it inside `Chart.Plot`, next to `Drawings.Layer` if there is one. It draws
+ * nothing. A tap (not a drag) on clear chart puts a selection away; with nothing selected and a `Series.Root` mounted
+ * it selects the series; a tap on a study's line or band (a `Study.Line` or `Study.Band` with an `id`) selects that study.
+ * Escape, with the chart focused, clears the selection (a half-placed drawing or an armed tool take the first Escape).
+ * A press on a drawing is Drawings.Layer's, and a drag is the chart panning, so neither counts.
+ */
+function Layer() {
+  const ctx = useSelection('Selection.Layer');
+  const chart = useChart('Selection.Layer');
+  const ref = useRef<SVGGElement | null>(null);
+  const live = useRef({ ctx, chart });
+  live.current = { ctx, chart };
+
+  useEffect(() => {
+    const svg = ref.current?.ownerSVGElement;
+    if (!svg) return;
+    // `before` is the selection at the press: another listener on the same tap (Drawings.Layer putting a drawing away) may change it before the release.
+    let tap: { pointerId: number; x: number; y: number; at: number; hit: ChartSelection; before: ChartSelection; inMain: boolean } | null = null;
+    const down = new Set<number>();
+    const onDown = (event: PointerEvent) => {
+      if (event.isPrimary) down.clear();
+      down.add(event.pointerId);
+      // A second finger is a pinch, not a tap.
+      if (down.size > 1) { tap = null; return; }
+      if (event.button !== 0) return;
+      const { ctx: c, chart: ch } = live.current;
+      const point = ch.toChart(event.clientX, event.clientY);
+      if (!point || point.x < 0 || point.x >= ch.frame.plotWidth || point.y < 0 || point.y >= ch.plotBottom) return;
+      if (c.guard.current?.owns(event.clientX, event.clientY, event.pointerType)) return;
+      // A line of a study or of a series in a panel (data-select-id) is a hit; clear chart below the first panel is not the bar series'.
+      const hitEl = (event.target as Element | null)?.closest?.("[data-part='study-hit'],[data-part='series-hit']");
+      const hitId = hitEl?.getAttribute('data-select-id');
+      const hit: ChartSelection = hitId ? { kind: hitEl?.getAttribute('data-part') === 'series-hit' ? 'series' : 'study', id: hitId } : null;
+      tap = { pointerId: event.pointerId, x: event.clientX, y: event.clientY, at: event.timeStamp, hit, before: c.current(), inMain: point.y < ch.frame.plotHeight };
+    };
+    const onMove = (event: PointerEvent) => {
+      if (tap && tap.pointerId === event.pointerId && Math.hypot(event.clientX - tap.x, event.clientY - tap.y) > TAP_SLOP) tap = null;
+    };
+    const onUp = (event: PointerEvent) => {
+      down.delete(event.pointerId);
+      if (!tap || tap.pointerId !== event.pointerId) return;
+      const t = tap;
+      tap = null;
+      if (event.type !== 'pointerup' || Math.hypot(event.clientX - t.x, event.clientY - t.y) > TAP_SLOP || event.timeStamp - t.at >= TAP_MS) return;
+      const { ctx: c } = live.current;
+      c.select(selectionAfterTap(t.before, t.hit, t.inMain ? c.series?.id ?? null : null));
+    };
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key !== 'Escape' || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return;
+      const { ctx: c } = live.current;
+      if (c.guard.current?.busy()) return;
+      c.select(selectionAfterEscape(c.current()));
+    };
+    svg.addEventListener('pointerdown', onDown);
+    svg.addEventListener('pointermove', onMove);
+    svg.addEventListener('pointerup', onUp);
+    svg.addEventListener('pointercancel', onUp);
+    svg.addEventListener('keydown', onKey);
+    return () => {
+      svg.removeEventListener('pointerdown', onDown);
+      svg.removeEventListener('pointermove', onMove);
+      svg.removeEventListener('pointerup', onUp);
+      svg.removeEventListener('pointercancel', onUp);
+      svg.removeEventListener('keydown', onKey);
+    };
+  }, []);
+  return <g ref={ref} data-part="selection-layer" aria-hidden="true" />;
+}
+
+export interface SeriesRootProps {
+  /** The selection id of the series. Unique on the chart. */
+  id: string;
+  /** What the series is called: the button's name, the panel's label and the live-region text. */
+  label: string;
+  children?: ReactNode;
+}
+
+/**
+ * Says that a bar series exists, so a tap on clear chart can select it (with a Selection.Layer in the plot). It draws
+ * nothing. Put it above the chart and the Series.Select and Series.Options. The selected series shows
+ * `data-state='selected'` on its `Chart.Candles`.
+ */
+function SeriesRoot({ id, label, children }: SeriesRootProps) {
+  const ctx = useSelection('Series.Root');
+  const { registerSeries, setName } = ctx;
+  useEffect(() => {
+    const undo = registerSeries({ id, label });
+    setName('series', id, label);
+    return undo;
+  }, [registerSeries, setName, id, label]);
+  const selected = ctx.selection !== null && ctx.selection.kind === 'series' && ctx.selection.id === id;
+  const value = useMemo<SeriesContextValue>(() => ({ id, label, selected }), [id, label, selected]);
+  return <SeriesContext.Provider value={value}>{children}</SeriesContext.Provider>;
+}
+
+function useSeries(part: string): SeriesContextValue {
+  const context = useContext(SeriesContext);
+  if (!context) throw new Error(`Series.${part} needs a Series.Root above it.`);
+  return context;
+}
+
+/**
+ * A button that selects the series, and puts the selection away when pressed again: the keyboard and touch path to what
+ * a tap on clear chart does. `aria-pressed` carries the state. Its name is the series label unless you give a `label`
+ * or children.
+ */
+function Select({ className, icon, label, hideLabel, children }: NameProps & { className?: string; children?: ReactNode }) {
+  const ctx = useSelection('Series.Select');
+  const series = useSeries('Select');
+  const face = buttonFace(series.label, { icon, label, hideLabel, children });
+  return (
+    <button
+      type="button"
+      className={className}
+      data-mt=""
+      data-touch-target=""
+      data-part="series-select"
+      data-state={series.selected ? 'selected' : undefined}
+      aria-label={face['aria-label']}
+      aria-pressed={series.selected}
+      onClick={() => ctx.select(series.selected ? null : { kind: 'series', id: series.id })}
+    >
+      {face.content}
+    </button>
+  );
+}
+
+/**
+ * A headless panel for the series' options. It shows its children only while the series is selected. The primitives
+ * ship no option fields: put your own controls inside (an interval list, an instrument picker) and decide what a change
+ * means. `label` names the group; the default is the series label and "options".
+ */
+function Options({ className, label, children }: { className?: string; label?: string; children?: ReactNode }) {
+  const series = useSeries('Options');
+  if (!series.selected) return null;
+  return (
+    <div className={className} role="group" aria-label={label ?? `${series.label} options`} data-mt="" data-part="series-options" data-series={series.id}>
+      {children}
+    </div>
+  );
+}
+
+export { Root, Layer, SeriesRoot, Select, Options, useSelection };

package/src/Studies.tsx

@@ -0,0 +1,6 @@
+import { Root, Line, Band, Legend } from './StudiesParts.js';
+
+// The parts live in StudiesParts.js (a client module). The namespace object is built here, outside it, so a server
+// component can write `Study.Root`: a property of an object exported from a client module is not reachable there.
+export * from './StudiesParts.js';
+export const Study = { Root, Line, Band, Legend };