@matchstick-trading/primitives 0.0.10

package/src/Cursor.tsx

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

package/src/CursorParts.tsx

@@ -0,0 +1,77 @@
+import { createContext, useCallback, useContext, useMemo, useRef, useState, type ReactNode } from 'react';
+
+/**
+ * Cursor: the one owner of "where in the session are we". Every view (Transport, Scrubber,
+ * Ladder, DiffTable) reads this one value instead of keeping its own copy, so linked panels cannot disagree
+ * about time. Renders no DOM.
+ *
+ * The value is the engine's own cursor shape, sequence and timestamp as bigint: an exact integer, never a
+ * float. (A wire form with decimal strings belongs at the contract boundary, not in this React state.)
+ *
+ * Controlled (`value` + `onValueChange`) or uncontrolled (`defaultValue`), the same three-prop pattern the
+ * headless libraries use. A controlled Root never changes the value itself: `setValue` only calls
+ * `onValueChange`, and the host decides.
+ */
+export type CursorValue =
+  | { readonly position: 'initial' }
+  | { readonly position: 'event'; readonly sequence: bigint; readonly timestamp: bigint };
+
+export type CursorState = 'idle' | 'playing' | 'seeking';
+export type CursorBoundary = 'start' | 'end' | null;
+
+export const CURSOR_START: CursorValue = { position: 'initial' };
+
+/** True when both are the same place in the session. */
+export function sameCursor(a: CursorValue, b: CursorValue): boolean {
+  if (a.position === 'initial' || b.position === 'initial') return a.position === b.position;
+  return a.sequence === b.sequence && a.timestamp === b.timestamp;
+}
+
+export interface CursorRootProps {
+  value?: CursorValue;
+  defaultValue?: CursorValue;
+  onValueChange?: (value: CursorValue) => void;
+  /** What the host is doing with the cursor. Exposed as `data-state` to every view that asks for attributes. */
+  state?: CursorState;
+  /** Set when the cursor is at the start or end of the session. */
+  boundary?: CursorBoundary;
+  children?: ReactNode;
+}
+
+interface CursorContext {
+  value: CursorValue;
+  setValue: (value: CursorValue) => void;
+  state: CursorState;
+  boundary: CursorBoundary;
+}
+
+const Context = createContext<CursorContext | null>(null);
+
+function Root({ value, defaultValue = CURSOR_START, onValueChange, state = 'idle', boundary = null, children }: CursorRootProps) {
+  const controlled = value !== undefined;
+  const [inner, setInner] = useState<CursorValue>(defaultValue);
+  const current = controlled ? value : inner;
+  // The latest callback and mode, read at call time, so `setValue` keeps one identity for the life of the Root.
+  const live = useRef({ controlled, onValueChange, current });
+  live.current = { controlled, onValueChange, current };
+  const setValue = useCallback((next: CursorValue) => {
+    const { controlled: isControlled, onValueChange: notify, current: now } = live.current;
+    if (sameCursor(now, next)) return;
+    if (!isControlled) setInner(next);
+    notify?.(next);
+  }, []);
+  const context = useMemo(() => ({ value: current, setValue, state, boundary }), [current, setValue, state, boundary]);
+  return <Context.Provider value={context}>{children}</Context.Provider>;
+}
+
+/** Reads the shared cursor. Throws a plain message when there is no `Cursor.Root` above, rather than guessing a position. */
+export function useCursor(): CursorContext & { attributes: { 'data-state': CursorState; 'data-boundary'?: 'start' | 'end' } } {
+  const context = useContext(Context);
+  if (!context) throw new Error('useCursor needs a Cursor.Root above it: there is no shared cursor to read.');
+  const attributes = context.boundary
+    ? { 'data-state': context.state, 'data-boundary': context.boundary }
+    : { 'data-state': context.state };
+  return { ...context, attributes };
+}
+
+export { Root };

package/src/DepthProfile.tsx

@@ -0,0 +1,6 @@
+import { Root, Plot, Bids, Asks, Axis, Crosshair, Readout, Table } from './DepthProfileParts.js';
+
+// The parts live in DepthProfileParts.js (a client module). The namespace object is built here, outside it, so a server
+// component can write `DepthProfile.Root`: a property of an object exported from a client module is not reachable there.
+export * from './DepthProfileParts.js';
+export const DepthProfile = { Root, Plot, Bids, Asks, Axis, Crosshair, Readout, Table };

package/src/DepthProfileParts.tsx

@@ -0,0 +1,154 @@
+import { createContext, useCallback, useContext, useId, useMemo, useState, type KeyboardEvent, type PointerEvent, type ReactNode } from 'react';
+import { DEPTH_HEIGHT, DEPTH_WIDTH, depthGeometry, depthLevelId, nextDepthIndex, resolveDepthKey, type DepthGeometry, type DepthLevel } from './core/depth-profile.js';
+
+/**
+ * DepthProfile as parts: Root, Plot, Bids, Asks, Axis, Crosshair, Readout, Table. Headless: the
+ * parts draw cumulative depth for each side and add `data-side`. A chart alone is a picture, so the same levels are
+ * also a Table; a keyboard user moves a crosshair level by level and a Readout says where it is in words.
+ *
+ * Prices and sizes are exact decimal strings and are printed as given. A tap or click on the Plot puts the crosshair on the
+ * nearest level (a touch screen has no arrow keys); the keyboard and the Table are the other ways in.
+ */
+interface DepthContext extends DepthGeometry {
+  active: number | null;
+  setActive: (index: number | null) => void;
+  readoutId: string;
+}
+const Context = createContext<DepthContext | null>(null);
+
+function useDepth(part: string): DepthContext {
+  const context = useContext(Context);
+  if (!context) throw new Error(`DepthProfile.${part} needs a DepthProfile.Root above it.`);
+  return context;
+}
+
+export interface DepthProfileRootProps {
+  /** Best price first on each side. */
+  levels: readonly DepthLevel[];
+  /** Controlled crosshair: the `side:price` id of the level, or null for none. */
+  active?: string | null;
+  onActiveChange?: (id: string | null) => void;
+  className?: string;
+  'aria-label'?: string;
+  children?: ReactNode;
+}
+
+function Root({ levels: given, active, onActiveChange, className, 'aria-label': label = 'Cumulative order-book depth', children }: DepthProfileRootProps) {
+  const levels = useMemo(() => (Array.isArray(given) ? given.filter((level) => level != null) : []), [given]); // no list, or a hole in it, is left out
+  const geometry = useMemo(() => depthGeometry(levels), [levels]);
+  const [inner, setInner] = useState<string | null>(null);
+  const controlled = active !== undefined;
+  const activeId = controlled ? active : inner;
+  const index = activeId === null ? -1 : geometry.ordered.findIndex((l) => depthLevelId(l) === activeId);
+  const readoutId = useId();
+  const setActive = useCallback((next: number | null) => {
+    const id = next === null ? null : depthLevelId(geometry.ordered[next]);
+    if (!controlled) setInner(id);
+    onActiveChange?.(id);
+  }, [geometry, controlled, onActiveChange]);
+  const context = useMemo<DepthContext>(() => ({ ...geometry, active: index < 0 ? null : index, setActive, readoutId }), [geometry, index, setActive, readoutId]);
+  return (
+    <Context.Provider value={context}>
+      <figure className={className} aria-label={label}>{children}</figure>
+    </Context.Provider>
+  );
+}
+
+/** The drawing. One tab stop; a tap or click picks the nearest level; ArrowLeft/Right move the crosshair, Home/End jump to the ends, Escape clears it. */
+function Plot({ className, label = 'Bid and ask cumulative depth', children }: { className?: string; label?: string; children?: ReactNode }) {
+  const { ordered, active, setActive, readoutId, x } = useDepth('Plot');
+  const onKeyDown = (event: KeyboardEvent<SVGSVGElement>) => {
+    const action = resolveDepthKey(event);
+    if (!action) return;
+    event.preventDefault();
+    event.stopPropagation(); // arrows, Home and End are also transport shortcuts on the page
+    setActive(nextDepthIndex(ordered, active, action));
+  };
+  const onPointerDown = (event: PointerEvent<SVGSVGElement>) => {
+    const svg = event.currentTarget;
+    const matrix = svg.getScreenCTM();
+    if (!ordered.length || !matrix) return;
+    // Through the inverse screen transform, so the letterboxing of preserveAspectRatio is accounted for.
+    const point = svg.createSVGPoint();
+    point.x = event.clientX;
+    point.y = event.clientY;
+    const at = point.matrixTransform(matrix.inverse()).x;
+    let nearest = 0;
+    for (let i = 1; i < ordered.length; i++) {
+      if (Math.abs(x(ordered[i].price) - at) < Math.abs(x(ordered[nearest].price) - at)) nearest = i;
+    }
+    setActive(nearest);
+  };
+  return (
+    <svg className={className} viewBox={`0 0 ${DEPTH_WIDTH} ${DEPTH_HEIGHT}`} role="group" aria-label={label} aria-describedby={readoutId} tabIndex={0} onKeyDown={onKeyDown} onPointerDown={onPointerDown}>
+      {children}
+    </svg>
+  );
+}
+
+function Bids({ className }: { className?: string }) {
+  const { bidPoints } = useDepth('Bids');
+  return <polygon className={className} data-part="depth-bids" data-side="bid" points={bidPoints} />;
+}
+
+function Asks({ className }: { className?: string }) {
+  const { askPoints } = useDepth('Asks');
+  return <polygon className={className} data-part="depth-asks" data-side="ask" points={askPoints} />;
+}
+
+/** The lowest and highest price on the plot, as recorded, at its two ends. */
+function Axis({ className }: { className?: string }) {
+  const { ordered } = useDepth('Axis');
+  if (ordered.length === 0) return null;
+  const low = ordered[0].price;
+  const high = ordered[ordered.length - 1].price;
+  return (
+    <g className={className} data-part="depth-axis" aria-hidden="true">
+      <text x={0} y={DEPTH_HEIGHT - 2} textAnchor="start">{low}</text>
+      <text x={DEPTH_WIDTH} y={DEPTH_HEIGHT - 2} textAnchor="end">{high}</text>
+    </g>
+  );
+}
+
+/** A line and a point at the active level; nothing is drawn while there is none. */
+function Crosshair({ className }: { className?: string }) {
+  const { ordered, active, x, y } = useDepth('Crosshair');
+  if (active === null) return null;
+  const level = ordered[active];
+  return (
+    <g className={className} data-part="depth-crosshair" data-side={level.side} aria-hidden="true">
+      <line x1={x(level.price)} x2={x(level.price)} y1={0} y2={DEPTH_HEIGHT} />
+      <circle cx={x(level.price)} cy={y(level.cumulative)} r={4} />
+    </g>
+  );
+}
+
+/** The active level in words, announced politely. The host may pass its own wording. */
+function Readout({ className, format }: { className?: string; format?: (level: DepthLevel) => string }) {
+  const { ordered, active, readoutId } = useDepth('Readout');
+  const level = active === null ? null : ordered[active];
+  const text = level === null ? '' : format ? format(level) : `${level.side === 'bid' ? 'Bid' : 'Ask'} ${level.price}, cumulative size ${level.cumulative}`;
+  return <output id={readoutId} className={className} aria-live="polite" data-side={level?.side}>{text}</output>;
+}
+
+/** The same levels as a table: the text equivalent of the plot. Prices run low to high. */
+function Table({ className, caption = 'Cumulative depth by price level' }: { className?: string; caption?: string }) {
+  const { ordered, active } = useDepth('Table');
+  return (
+    <table className={className}>
+      <caption>{caption}</caption>
+      <thead><tr><th scope="col">Side</th><th scope="col">Price</th><th scope="col">Cumulative size</th></tr></thead>
+      <tbody>
+        {ordered.map((level, i) => (
+          <tr key={depthLevelId(level)} data-side={level.side} aria-current={i === active ? 'true' : undefined}>
+            <td>{level.side === 'bid' ? 'Bid' : 'Ask'}</td>
+            <td data-mt-numeric>{level.price}</td>
+            <td data-mt-numeric>{level.cumulative}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+
+export { Root, Plot, Bids, Asks, Axis, Crosshair, Readout, Table };

package/src/DiffTable.tsx

@@ -0,0 +1,6 @@
+import { Root, Header, Row, Price, QtyA, QtyB, Delta, ChangeMark } from './DiffTableParts.js';
+
+// The parts live in DiffTableParts.js (a client module). The namespace object is built here, outside it, so a server
+// component can write `DiffTable.Root`: a property of an object exported from a client module is not reachable there.
+export * from './DiffTableParts.js';
+export const DiffTable = { Root, Header, Row, Price, QtyA, QtyB, Delta, ChangeMark };

package/src/DiffTableParts.tsx

@@ -0,0 +1,160 @@
+import { createContext, useCallback, useContext, useMemo, useRef, useState, type KeyboardEvent, type ReactNode } from 'react';
+import { primitiveAttributes } from './attributes.js';
+import { DIFF_CHANGE_LABEL, diffRowId, holdDiffOrder, nextDiffIndex, nextDiffSort, resolveDiffKey, signedDelta, sortDiffRows, type DiffChange, type DiffSort, type DiffTableRow } from './core/diff-table.js';
+
+/**
+ * DiffTable as parts: Root, Header, Row, Price, QtyA, QtyB, Delta, ChangeMark. Headless: the parts
+ * are real table elements and add `data-side`, `data-diff` and `data-sorted`; the host chooses the columns.
+ *
+ * Rows hold their order while the pointer is over the table. Keys: arrows, Home and End move between rows, Enter or
+ * Space picks the row, `a` and `b` ask the host to focus the A or B cursor control (the pair itself stays with the
+ * host's Cursor), `s` cycles the sort. Values are exact decimal strings and are printed as given.
+ */
+interface DiffContext {
+  activeId: string | null;
+  firstId: string | null;
+  setActive: (id: string) => void;
+}
+const Context = createContext<DiffContext | null>(null);
+
+function useDiff(part: string): DiffContext {
+  const context = useContext(Context);
+  if (!context) throw new Error(`DiffTable.${part} needs a DiffTable.Root above it.`);
+  return context;
+}
+
+export interface DiffTableRootProps {
+  rows: readonly DiffTableRow[];
+  /** Controlled sort; leave out for an uncontrolled table that starts as `book`. */
+  sort?: DiffSort;
+  onSortChange?: (sort: DiffSort) => void;
+  /** Enter or Space on a focused row. */
+  onSelect?: (row: DiffTableRow) => void;
+  /** The `a` or `b` key: focus that cursor control. */
+  onFocusCursor?: (which: 'a' | 'b') => void;
+  className?: string;
+  caption?: string;
+  captionClassName?: string;
+  /** The parts, given the rows in the order to show them (sorted, and held while the pointer is over the table). */
+  children: (rows: DiffTableRow[]) => ReactNode;
+}
+
+function Root({ rows, sort, onSortChange, onSelect, onFocusCursor, className, caption, captionClassName, children }: DiffTableRootProps) {
+  const [innerSort, setInnerSort] = useState<DiffSort>('book');
+  const controlled = sort !== undefined;
+  const current = controlled ? sort : innerSort;
+  const [held, setHeld] = useState<string[] | null>(null);
+  const [activeId, setActiveId] = useState<string | null>(null);
+  const table = useRef<HTMLTableElement>(null);
+
+  const sorted = useMemo(() => sortDiffRows(rows, current), [rows, current]);
+  const shown = useMemo(() => (held ? holdDiffOrder(held, sorted) : sorted), [held, sorted]);
+  const firstId = shown.length ? diffRowId(shown[0]) : null;
+
+  const changeSort = useCallback(() => {
+    const next = nextDiffSort(current);
+    if (!controlled) setInnerSort(next);
+    setHeld(null); // asking for a new order is the one time the rows may move under the pointer
+    onSortChange?.(next);
+  }, [current, controlled, onSortChange]);
+
+  const focusRow = (id: string) => {
+    setActiveId(id);
+    for (const tr of table.current?.querySelectorAll<HTMLElement>('tbody tr[data-diff-row]') ?? []) {
+      if (tr.dataset.diffRow === id) { tr.focus(); return; }
+    }
+  };
+
+  const onKeyDown = (event: KeyboardEvent<HTMLTableElement>) => {
+    const action = resolveDiffKey(event.nativeEvent);
+    if (!action) return;
+    const onRow = (event.target as HTMLElement).closest('tr[data-diff-row]') as HTMLElement | null;
+    if (action.type === 'select') {
+      if (event.target !== onRow || !onRow) return; // Enter and Space on the pick button are the button's own
+      const row = shown.find((r) => diffRowId(r) === onRow.dataset.diffRow);
+      if (!row || !onSelect) return;
+      event.preventDefault();
+      onSelect(row);
+      return;
+    }
+    if (action.type === 'move' && !onRow) return;
+    event.preventDefault();
+    event.stopPropagation(); // these letters and arrows are also page shortcuts
+    if (action.type === 'move') {
+      const index = shown.findIndex((r) => diffRowId(r) === onRow?.dataset.diffRow);
+      const to = nextDiffIndex(shown.length, index, action.to);
+      if (to >= 0) focusRow(diffRowId(shown[to]));
+    } else if (action.type === 'cursor') onFocusCursor?.(action.which);
+    else changeSort();
+  };
+
+  const context = useMemo<DiffContext>(() => ({ activeId, firstId, setActive: setActiveId }), [activeId, firstId]);
+  return (
+    <Context.Provider value={context}>
+      <table
+        ref={table}
+        className={className}
+        data-mt=""
+        data-sorted={current}
+        onPointerEnter={() => setHeld(sorted.map(diffRowId))}
+        onPointerLeave={() => setHeld(null)}
+        onKeyDown={onKeyDown}
+      >
+        {caption && <caption className={captionClassName}>{caption}</caption>}
+        {children(shown)}
+      </table>
+    </Context.Provider>
+  );
+}
+
+/** The header row. Put the `<th scope="col">` cells inside. */
+function Header({ className, children }: { className?: string; children: ReactNode }) {
+  return <thead><tr className={className}>{children}</tr></thead>;
+}
+
+/** One level. A single tab stop for the table: the active row, or the first. The pointer does not move it. */
+function Row({ row, selected, className, children }: { row: DiffTableRow; selected?: boolean; className?: string; children: ReactNode }) {
+  const { activeId, firstId, setActive } = useDiff('Row');
+  const id = diffRowId(row);
+  const stop = activeId === null ? id === firstId : id === activeId;
+  const { 'data-mt': _scope, ...state } = primitiveAttributes({ side: row.side });
+  return (
+    <tr
+      className={className}
+      {...state}
+      data-diff={row.change === 'unchanged' ? undefined : row.change}
+      data-diff-row={id}
+      aria-selected={selected === undefined ? undefined : selected}
+      tabIndex={stop ? 0 : -1}
+      onFocus={() => setActive(id)}
+    >
+      {children}
+    </tr>
+  );
+}
+
+/** The row header cell: the price as recorded. Pass children to put a control inside. */
+function Price({ row, className, children }: { row: DiffTableRow; className?: string; children?: ReactNode }) {
+  return <th scope="row" className={className} data-mt-numeric="">{children ?? row.price}</th>;
+}
+
+function QtyA({ row, className }: { row: DiffTableRow; className?: string }) {
+  return <td className={className} data-mt-numeric="">{row.qtyA}</td>;
+}
+
+function QtyB({ row, className }: { row: DiffTableRow; className?: string }) {
+  return <td className={className} data-mt-numeric="">{row.qtyB}</td>;
+}
+
+/** qtyB minus qtyA with its sign shown. */
+function Delta({ row, className }: { row: DiffTableRow; className?: string }) {
+  return <td className={className} data-mt-numeric="">{signedDelta(row.delta)}</td>;
+}
+
+/** The change in words; tokens.css adds the mark (+, −, ±) so it never rests on colour alone. */
+function ChangeMark({ change, className, label }: { change: DiffChange; className?: string; label?: string }) {
+  const attributes = primitiveAttributes(change === 'unchanged' ? {} : { diff: change });
+  return <span className={className} {...attributes}>{label ?? DIFF_CHANGE_LABEL[change]}</span>;
+}
+
+export { Root, Header, Row, Price, QtyA, QtyB, Delta, ChangeMark };

package/src/Drawings.tsx

@@ -0,0 +1,6 @@
+import { Root, Layer, Toolbar, List, Remove, Undo, Lock, Edit } from './DrawingsParts.js';
+
+// The parts live in DrawingsParts.js (a client module). The namespace object is built here, outside it, so a server
+// component can write `Drawings.Root`: a property of an object exported from a client module is not reachable there.
+export * from './DrawingsParts.js';
+export const Drawings = { Root, Layer, Toolbar, List, Remove, Undo, Lock, Edit };