@matchstick-trading/primitives 0.0.10

package/src/ToolbarParts.tsx

@@ -0,0 +1,179 @@
+import { createContext, useCallback, useContext, useEffect, useId, useMemo, useRef, useState, type ButtonHTMLAttributes, type KeyboardEvent as ReactKeyboardEvent, type ReactNode, type RefObject } from 'react';
+import { buttonFace, type NameProps } from './accessible-name.js';
+
+/**
+ * A toolbar as parts: Root, Button and Separator. Headless: parts add `data-part` and `data-mt`; the host gives them looks.
+ *
+ * The toolbar is ONE tab stop (roving tabindex). Inside it the arrow keys along its orientation move between the items,
+ * Home and End jump to the ends, and Escape sends focus to `returnFocusTo` (the chart, for a drawing toolbar). An item
+ * is a Toolbar.Button (a plain button, or a toggle with `pressed`) or a Menu.Trigger.
+ */
+
+type Orientation = 'horizontal' | 'vertical';
+
+interface ToolbarContext {
+  orientation: Orientation;
+  stop: string | null;
+  setStop: (id: string) => void;
+  register: (id: string, element: HTMLElement) => void;
+  unregister: (id: string) => void;
+  /** Ask the root to re-check which item is the tab stop (an item became enabled or disabled). */
+  refresh: () => void;
+}
+const Context = createContext<ToolbarContext | null>(null);
+
+/** The toolbar a part sits in, or null outside one. Menu.Trigger uses it to join the roving tab stop. */
+export function useToolbarContext(): ToolbarContext | null {
+  return useContext(Context);
+}
+
+/** Makes `element` an item of the toolbar above it, if any; returns the tabIndex and focus handler to put on it. */
+export function useToolbarItem(element: RefObject<HTMLElement | null>, disabled?: boolean): { tabIndex: 0 | -1 | undefined; onFocus: (() => void) | undefined } {
+  const toolbar = useContext(Context);
+  const id = useId();
+  const register = toolbar?.register;
+  const unregister = toolbar?.unregister;
+  useEffect(() => {
+    if (!register || !unregister || !element.current) return;
+    register(id, element.current);
+    return () => unregister(id);
+  }, [register, unregister, id, element]);
+  // A disabled item cannot be the tab stop: tell the root when that changes, since the root may not re-render on its own.
+  const refresh = toolbar?.refresh;
+  useEffect(() => { refresh?.(); }, [refresh, disabled]);
+  const setStop = toolbar?.setStop;
+  const onFocus = useCallback(() => setStop?.(id), [setStop, id]);
+  if (!toolbar) return { tabIndex: undefined, onFocus: undefined };
+  return { tabIndex: toolbar.stop === id ? 0 : -1, onFocus };
+}
+
+type DataAttributes = { [attribute: `data-${string}`]: string | number | boolean | undefined };
+
+export interface ToolbarRootProps extends DataAttributes {
+  className?: string;
+  /** Names the toolbar. Default "Toolbar"; give it the real name ("Drawing tools"). */
+  'aria-label'?: string;
+  /** Which arrow keys move between items. Default 'horizontal' (Left and Right); 'vertical' uses Up and Down. */
+  orientation?: Orientation;
+  /**
+   * Where Escape sends focus: an element ref, or a function that returns the element (it is read when Escape is pressed,
+   * so the chart need not exist yet). Without it Escape does nothing here.
+   */
+  returnFocusTo?: RefObject<HTMLElement | SVGElement | null> | (() => HTMLElement | SVGElement | null);
+  children?: ReactNode;
+}
+
+/** role="toolbar" with one tab stop. Put Toolbar.Button and Menu.Trigger inside it, in any wrapper. */
+function Root({ className, 'aria-label': label = 'Toolbar', orientation = 'horizontal', returnFocusTo, children, ...rest }: ToolbarRootProps) {
+  const items = useRef(new Map<string, HTMLElement>());
+  const [stop, setStop] = useState<string | null>(null);
+  const [, setVersion] = useState(0);
+  const register = useCallback((id: string, element: HTMLElement) => { items.current.set(id, element); setVersion((v) => v + 1); }, []);
+  const unregister = useCallback((id: string) => { items.current.delete(id); setVersion((v) => v + 1); }, []);
+
+  /** The enabled items in document order. */
+  const ordered = () => [...items.current.entries()]
+    .filter(([, el]) => el.isConnected && !(el as HTMLButtonElement).disabled)
+    .sort(([, a], [, b]) => (a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1));
+
+  // One item must always be the tab stop: when none is (first render, or the one that was removed), a pressed item is the
+  // stop, else the first. This runs after every render because an item can change `pressed` or `disabled` without telling us.
+  useEffect(() => {
+    const list = ordered();
+    if (list.length === 0 || (stop !== null && list.some(([id]) => id === stop))) return;
+    const pressed = list.find(([, el]) => el.getAttribute('aria-pressed') === 'true');
+    setStop((pressed ?? list[0])[0]);
+  });
+
+  const onKeyDown = (event: ReactKeyboardEvent<HTMLDivElement>) => {
+    if (event.altKey || event.ctrlKey || event.metaKey) return;
+    const list = ordered();
+    const at = list.findIndex(([, el]) => el === event.target);
+    if (at < 0) return; // a key inside an open menu belongs to the menu
+    if (event.key === 'Escape') {
+      const target = typeof returnFocusTo === 'function' ? returnFocusTo() : returnFocusTo?.current;
+      if (!target) return;
+      event.preventDefault();
+      event.stopPropagation();
+      target.focus();
+      return;
+    }
+    // A horizontal toolbar mirrors in right-to-left text, as Menu does: the arrow that points ahead visually moves ahead.
+    const rtl = orientation !== 'vertical' && getComputedStyle(event.currentTarget).direction === 'rtl';
+    const forward = orientation === 'vertical' ? 'ArrowDown' : rtl ? 'ArrowLeft' : 'ArrowRight';
+    const back = orientation === 'vertical' ? 'ArrowUp' : rtl ? 'ArrowRight' : 'ArrowLeft';
+    let next: number;
+    switch (event.key) {
+      case forward: next = (at + 1) % list.length; break;
+      case back: next = (at - 1 + list.length) % list.length; break;
+      case 'Home': next = 0; break;
+      case 'End': next = list.length - 1; break;
+      default: return;
+    }
+    event.preventDefault();
+    event.stopPropagation(); // arrows, Home and End are also transport shortcuts on a replay page
+    setStop(list[next][0]);
+    list[next][1].focus();
+  };
+
+  const refresh = useCallback(() => setVersion((v) => v + 1), []);
+  const context = useMemo<ToolbarContext>(() => ({ orientation, stop, setStop, register, unregister, refresh }), [orientation, stop, register, unregister, refresh]);
+  return (
+    <Context.Provider value={context}>
+      <div data-mt="" data-part="toolbar" {...rest} className={className} role="toolbar" aria-label={label} aria-orientation={orientation} onKeyDown={onKeyDown}>
+        {children}
+      </div>
+    </Context.Provider>
+  );
+}
+
+export interface ToolbarButtonProps extends NameProps, DataAttributes, Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'type'> {
+  /** Makes the button a toggle: `aria-pressed` is this value. Leave it out for a plain button. */
+  pressed?: boolean;
+}
+
+/**
+ * A button in the toolbar. Visible words are `children`, else `label`. With only an icon, set `hideLabel` and `label`:
+ * the label becomes the accessible name. A button with no words at all gets no name, and warns in the console.
+ */
+function Button({ pressed, icon, label, hideLabel, children, className, onClick, ...rest }: ToolbarButtonProps) {
+  const ref = useRef<HTMLButtonElement | null>(null);
+  const item = useToolbarItem(ref, rest.disabled);
+  const face = buttonFace(undefined, { icon, label, hideLabel, children, ariaLabel: rest['aria-label'] });
+  useNameCheck(ref, 'Toolbar.Button');
+  return (
+    <button
+      data-mt=""
+      data-part="toolbar-button"
+      data-touch-target=""
+      {...rest}
+      ref={ref}
+      type="button"
+      className={className}
+      aria-label={face['aria-label']}
+      aria-pressed={pressed}
+      tabIndex={item.tabIndex}
+      onFocus={(event) => { item.onFocus?.(); rest.onFocus?.(event); }}
+      onClick={onClick}
+    >
+      {face.content}
+    </button>
+  );
+}
+
+/** A thin divider between groups of items. */
+function Separator({ className }: { className?: string }) {
+  return <div className={className} data-mt="" data-part="toolbar-separator" role="separator" />;
+}
+
+/** Warns once, in the console, when a control has no accessible name (no text and no aria-label). */
+export function useNameCheck(ref: RefObject<HTMLElement | null>, part: string): void {
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const named = (el.textContent ?? '').trim() !== '' || (el.getAttribute('aria-label') ?? '').trim() !== '' || el.hasAttribute('aria-labelledby');
+    if (!named) console.warn(`${part} has no accessible name: give it children, or a label with hideLabel when it shows only an icon.`);
+  }, [ref, part]);
+}
+
+export { Root, Button, Separator };

package/src/Transport.tsx

@@ -0,0 +1,6 @@
+import { Root, Group, Play, Previous, Next, Start, End, Speed, Readout, Boundary } from './TransportParts.js';
+
+// The parts live in TransportParts.js (a client module). The namespace object is built here, outside it, so a server
+// component can write `Transport.Root`: a property of an object exported from a client module is not reachable there.
+export * from './TransportParts.js';
+export const Transport = { Root, Group, Play, Previous, Next, Start, End, Speed, Readout, Boundary };

package/src/TransportParts.tsx

@@ -0,0 +1,128 @@
+import { createContext, useContext, type ButtonHTMLAttributes, type ReactElement, type ReactNode } from 'react';
+import { Notice } from './Notice.js';
+
+/**
+ * Transport as parts: Root, Group, Play, Previous, Next, Start, End, Speed, Readout, Boundary.
+ * Headless: parts render plain buttons and a readout and add `data-state`,
+ * `data-disabled` and `data-boundary`. The host owns the handlers and the copy. Keyboard shortcuts stay with the
+ * host; a suggested map: Space, ArrowLeft/Right, J/K, Home and End.
+ */
+interface TransportContext {
+  playing: boolean;
+  loading: boolean;
+}
+const Context = createContext<TransportContext>({ playing: false, loading: false });
+
+export interface TransportRootProps {
+  playing: boolean;
+  /** Another operation is running: Previous, Next, Start and End are disabled; Play is aria-disabled and ignores activation. */
+  loading?: boolean;
+  /** Set when the cursor sits at the start or the end of the session. */
+  boundary?: 'start' | 'end' | null;
+  className?: string;
+  'aria-label'?: string;
+  children?: ReactNode;
+}
+
+function Root({ playing, loading = false, boundary = null, className, 'aria-label': label = 'Replay transport', children }: TransportRootProps) {
+  return (
+    <Context.Provider value={{ playing, loading }}>
+      <nav className={className} aria-label={label} data-state={playing ? 'playing' : 'paused'} data-boundary={boundary ?? undefined}>
+        {children}
+      </nav>
+    </Context.Provider>
+  );
+}
+
+function Group({ className, label, children }: { className?: string; label?: string; children?: ReactNode }) {
+  return label ? (
+    <div className={className} role="group" aria-label={label}>{children}</div>
+  ) : (
+    <div className={className}>{children}</div>
+  );
+}
+
+export type PartButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'type' | 'disabled'>;
+
+/** The play toggle is never `disabled`: disabling the focused button would drop focus to <body> mid-gesture. */
+function Play({ onClick, ...rest }: PartButtonProps) {
+  const { playing, loading } = useContext(Context);
+  return (
+    <button
+      type="button"
+      {...rest}
+      onClick={(event) => {
+        if (loading) return;
+        onClick?.(event);
+      }}
+      aria-disabled={loading ? 'true' : undefined}
+      data-state={playing ? 'playing' : 'paused'}
+      data-disabled={loading ? '' : undefined}
+    />
+  );
+}
+
+// The explicit type keeps the emitted .d.ts naming PartButtonProps; inferred, it expands every attribute from the React types
+// the package was built against, and those names (SubmitEventHandler, ToggleEventHandler) do not exist in React 18.
+export type StepButton = { (props: PartButtonProps): ReactElement; displayName?: string };
+function stepButton(name: string): StepButton {
+  const Part: StepButton = (props: PartButtonProps) => {
+    const { loading } = useContext(Context);
+    return <button type="button" {...props} disabled={loading} data-disabled={loading ? '' : undefined} />;
+  };
+  Part.displayName = `Transport.${name}`;
+  return Part;
+}
+const Previous = stepButton('Previous');
+const Next = stepButton('Next');
+const Start = stepButton('Start');
+const End = stepButton('End');
+
+export interface TransportSpeedProps {
+  speed: number;
+  options: readonly number[];
+  onSpeedChange: (speed: number) => void;
+  /** Text for one option, for example `formatSpeed`. */
+  format: (speed: number) => string;
+  className?: string;
+  labelClassName?: string;
+  label?: string;
+  'aria-label'?: string;
+}
+
+function Speed({ speed, options = [], onSpeedChange, format = (value: number) => `${value}x`, className, labelClassName, label = 'Speed', 'aria-label': ariaLabel = 'Playback speed, multiple of real time' }: TransportSpeedProps) {
+  return (
+    <label className={className}>
+      <span className={labelClassName}>{label}</span>
+      <select value={String(speed)} onChange={(event) => onSpeedChange(Number(event.target.value))} aria-label={ariaLabel}>
+        {(options ?? []).map((option) => (
+          <option key={option} value={String(option)}>
+            {format(option)}
+          </option>
+        ))}
+      </select>
+    </label>
+  );
+}
+
+/** Not announced while playing: the readout changes every frame. */
+function Readout({ className, children }: { className?: string; children?: ReactNode }) {
+  const { playing } = useContext(Context);
+  return (
+    <output className={className} aria-live={playing ? 'off' : 'polite'}>
+      {children}
+    </output>
+  );
+}
+
+/** A normal boundary condition, not a failure: polite status text, nothing when no boundary is reached. */
+function Boundary({ label, className }: { label: string | null; className?: string }) {
+  if (!label) return null;
+  return (
+    <Notice as="span" kind="info" className={className}>
+      {label}
+    </Notice>
+  );
+}
+
+export { Root, Group, Play, Previous, Next, Start, End, Speed, Readout, Boundary };

package/src/VolumeProfile.tsx

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

package/src/VolumeProfileParts.tsx

@@ -0,0 +1,106 @@
+import { useMemo, type ReactNode } from 'react';
+import { useChart } from './ChartParts.js';
+import { indexRangeOfTime, volumeProfile, type VolumeProfileResult } from './core/volume-profile.js';
+
+/**
+ * VolumeProfile as parts: Histogram, Table. The Histogram goes inside `Chart.Plot` and draws horizontal bars on the
+ * right of the price pane, one per price row, lined up with the chart's price scale; lines mark the point of control
+ * (the busiest row) and the value area's top and bottom. The Table says the same rows in text.
+ *
+ * Both read the bars in view, or a fixed `{ from, to }` range of timestamps (inclusive). Give both the same options.
+ */
+export interface VolumeProfileOptionsProps {
+  /** Number of price rows. Default 24. */
+  rows?: number;
+  /** Share of the volume the value area holds. Default 0.7. */
+  valueArea?: number;
+  /** A fixed range of Unix-millisecond timestamps instead of the bars in view. */
+  range?: { from: number; to: number };
+}
+
+function useProfile({ rows, valueArea, range }: VolumeProfileOptionsProps): VolumeProfileResult {
+  const { bars, frame } = useChart('VolumeProfile');
+  // The length is a dependency too: a host that pushes onto the same array must still get the new bars counted.
+  const fixed = useMemo(() => (range ? indexRangeOfTime(bars, range.from, range.to) : null), [bars, bars.length, range?.from, range?.to]);
+  const first = fixed ? fixed.first : frame.first;
+  const last = fixed ? fixed.last : frame.last;
+  return useMemo(() => volumeProfile(bars, { first, last, rows, valueArea }), [bars, bars.length, first, last, rows, valueArea]);
+}
+
+export interface VolumeProfileHistogramProps extends VolumeProfileOptionsProps {
+  /** Width of the longest bar in chart units. Default a quarter of the frame. */
+  width?: number;
+  /** Draw the POC, VAH and VAL lines across the plot. Default true. */
+  lines?: boolean;
+  className?: string;
+}
+
+/**
+ * Horizontal bars growing left from the right edge. Each row is a `<g data-part="profile-row">` with an up and a down
+ * rect (`data-change`); `data-value-area` marks rows inside the value area and `data-poc` the busiest row.
+ */
+function Histogram({ width, lines = true, className, ...options }: VolumeProfileHistogramProps) {
+  const { frame, readoutId } = useChart('VolumeProfile.Histogram');
+  const result = useProfile(options);
+  if (result.rows.length === 0 || result.poc < 0) return null;
+  const longest = Math.max(1, Math.min(frame.plotWidth, Number.isFinite(width) ? Math.max(0, width as number) : frame.plotWidth * 0.25));
+  const peak = result.rows[result.poc].volume;
+  const [vaLow, vaHigh] = result.valueAreaRows;
+  const right = frame.plotWidth;
+  const nodes: ReactNode[] = [];
+  result.rows.forEach((row, i) => {
+    const top = frame.y(row.high);
+    const height = Math.max(1, frame.y(row.low) - top);
+    const upWidth = (row.upVolume / peak) * longest;
+    const downWidth = (row.downVolume / peak) * longest;
+    nodes.push(
+      <g key={i} data-part="profile-row" data-value-area={i >= vaLow && i <= vaHigh ? '' : undefined} data-poc={i === result.poc ? '' : undefined}>
+        <rect data-change="up" x={right - upWidth} y={top} width={upWidth} height={height} />
+        <rect data-change="down" x={right - upWidth - downWidth} y={top} width={downWidth} height={height} />
+      </g>,
+    );
+  });
+  const line = (part: 'poc' | 'vah' | 'val', price: number | null) => {
+    if (price === null || !Number.isFinite(price)) return null;
+    const y = frame.y(price);
+    return <line data-part={part} x1={0} x2={frame.plotWidth} y1={y} y2={y} />;
+  };
+  const poc = result.rows[result.poc];
+  return (
+    <g className={className} data-part="volume-profile" clipPath={`url(#${readoutId}-price)`} aria-hidden="true">
+      {nodes}
+      {lines && line('poc', (poc.low + poc.high) / 2)}
+      {lines && line('vah', result.vah)}
+      {lines && line('val', result.val)}
+    </g>
+  );
+}
+
+const volumeText = (v: number) => String(Math.round(v * 100) / 100);
+
+/** The rows as a table, highest price first: price range, volume and share of the total. */
+function Table({ className, caption = 'Volume by price', ...options }: VolumeProfileOptionsProps & { className?: string; caption?: string }) {
+  const { decimals } = useChart('VolumeProfile.Table');
+  const result = useProfile(options);
+  const [vaLow, vaHigh] = result.valueAreaRows;
+  const body: ReactNode[] = [];
+  for (let i = result.rows.length - 1; i >= 0; i--) {
+    const row = result.rows[i];
+    body.push(
+      <tr key={i} data-value-area={i >= vaLow && i <= vaHigh ? '' : undefined} data-poc={i === result.poc ? '' : undefined}>
+        <td data-mt-numeric>{row.low.toFixed(decimals)} – {row.high.toFixed(decimals)}</td>
+        <td data-mt-numeric>{volumeText(row.volume)}</td>
+        <td data-mt-numeric>{result.total > 0 ? `${((row.volume / result.total) * 100).toFixed(1)}%` : '–'}</td>
+      </tr>,
+    );
+  }
+  return (
+    <table className={className}>
+      <caption>{caption}</caption>
+      <thead><tr>{['Price', 'Volume', 'Share'].map((h) => <th key={h} scope="col">{h}</th>)}</tr></thead>
+      <tbody>{body}</tbody>
+    </table>
+  );
+}
+
+export { Histogram, Table };

package/src/accessible-name.tsx

@@ -0,0 +1,34 @@
+import type { ReactNode } from 'react';
+
+/**
+ * The accessible-name rule. A control that is an icon and nothing else still names its action in words: the
+ * words are the `aria-label`, and the icon is a decorative `data-part='icon'` span that assistive technology skips. No
+ * icon ships in this package; `icon` is a slot the host fills.
+ */
+export interface NameProps {
+  /** A graphic for the button, drawn before any words. It is hidden from assistive technology, so give the button words too. */
+  icon?: ReactNode;
+  /** The action in words. It is the visible text unless `hideLabel` is set, and always the accessible name. */
+  label?: string;
+  /** Show only the icon. The `label` then becomes the `aria-label`. Needs `icon`. */
+  hideLabel?: boolean;
+}
+
+/**
+ * What a button shows and what it is called. `fallback` is the part's own word ("Lock", "Reset view"). Visible text is
+ * `children`, else `label`, else `fallback`; with `hideLabel` there is none and the name moves to `aria-label`.
+ */
+export function buttonFace(fallback: string | undefined, { icon, label, hideLabel, children, ariaLabel }: NameProps & { children?: ReactNode; ariaLabel?: string }): { 'aria-label': string | undefined; content: ReactNode } {
+  const hasIcon = icon !== undefined && icon !== null && icon !== false;
+  const visible = hideLabel && hasIcon ? null : (children ?? label ?? fallback ?? null);
+  const name = ariaLabel ?? label ?? (typeof children === 'string' ? children : fallback);
+  return {
+    'aria-label': visible === null || visible === false || visible === '' ? name : ariaLabel,
+    content: (
+      <>
+        {hasIcon && <span aria-hidden="true" data-part="icon">{icon}</span>}
+        {visible}
+      </>
+    ),
+  };
+}

package/src/attributes.ts

@@ -0,0 +1,12 @@
+import type { CSSProperties } from 'react';
+import { numericWidthValue } from './core/attributes.js';
+
+export * from './core/attributes.js';
+
+/**
+ * A column width that holds the widest value without growing: set the result as the element's style and give
+ * the cells `data-mt-numeric`. Counts characters of the longest sample (digits, separator, sign), in `ch`.
+ */
+export function numericWidth(...samples: readonly string[]): CSSProperties {
+  return { ['--mt-numeric-width' as string]: numericWidthValue(...samples) } as CSSProperties;
+}

package/src/core/adapter.ts

@@ -0,0 +1,91 @@
+// An adapter turns something a person has (a file, later a feed) into what the parts draw: bars, any series beside
+// them, and the problems it found, named by line. It is a plain function over its input: it reads, never repairs,
+// never throws, and never writes a zero where the source said nothing. `csvAdapter` is the first; a host can write
+// its own to the same shape and check the result with `seriesSetSchema`.
+
+import { parseBarsCsv, type CsvBarsError, type CsvBarsNote, type CsvBarsOptions } from './csv-bars.js';
+import type { CandleBar } from './chart-scale.js';
+import type { DataSeries, SeriesPoint, SeriesSet } from './series.js';
+
+/** A problem found while reading. `line` is 1-based in the source; 0 means the source as a whole. */
+export type AdapterIssue = CsvBarsError;
+
+export interface AdapterResult {
+  /** Who read it, shown beside the data so a person can tell where it came from. */
+  adapter: { name: string; version: string };
+  bars: CandleBar[];
+  /** Series beside the bars, on the bars' timestamps. */
+  series: DataSeries[];
+  errors: AdapterIssue[];
+  /** Things that were assumed or changed on the way in, in words a status line can show. */
+  notes: string[];
+}
+
+/** The shape every adapter has: a name, a version and a `read` that never throws. */
+export interface DataAdapter<Input, Options = undefined> {
+  name: string;
+  version: string;
+  read(input: Input, options?: Options): AdapterResult;
+}
+
+export type CsvAdapterOptions = Pick<CsvBarsOptions, 'maxRows' | 'utcOffsetMinutes'>;
+
+const NOTES: Record<CsvBarsNote, string> = {
+  sorted: 'The rows were out of time order, so they were sorted.',
+  'no-volume': 'There is no volume column, so volume is 0.',
+  'no-header': 'There was no header row, so the columns were read as time, open, high, low, close, volume.',
+};
+
+/** A header turned into an id: lower case, words joined by a dash, and a number added when two would collide. */
+function idFromHeader(header: string, taken: Set<string>): string {
+  const base = header.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'column';
+  let id = base;
+  for (let n = 2; taken.has(id); n++) id = `${base}-${n}`;
+  taken.add(id);
+  return id;
+}
+
+/**
+ * Reads a CSV of bars and any all-number columns beside them. Times without a zone are UTC unless `utcOffsetMinutes`
+ * says otherwise, and the note says which was used. An extra column's empty cell (or `-`, `NA`, `NaN`, `null`) is an
+ * `unknown` point, because the file does not say why it is empty; a `0` is the value 0. A column with any other text in
+ * it is not a series and is named in the notes.
+ */
+export const csvAdapter: DataAdapter<string, CsvAdapterOptions> = {
+  name: 'csv',
+  version: '1',
+  read(text, options = {}) {
+    const given = options.utcOffsetMinutes;
+    if (given !== undefined && !(Number.isInteger(given) && given >= -720 && given <= 840)) {
+      return { adapter: { name: 'csv', version: '1' }, bars: [], series: [], errors: [{ line: 0, message: `utcOffsetMinutes must be a whole number of minutes from -720 to 840, not ${String(given)}, so nothing was read.` }], notes: [] };
+    }
+    const parsed = parseBarsCsv(text, { ...options, extraColumns: true });
+    const offset = Number.isFinite(options.utcOffsetMinutes) ? (options.utcOffsetMinutes as number) : 0;
+    const notes: string[] = parsed.notes.map((n) => NOTES[n]);
+    if (parsed.bars.length > 0 && (parsed.zoneless ?? 0) > 0) notes.push(offset === 0 ? 'Times with no zone were read as UTC.' : `Times with no zone were read as UTC${offset > 0 ? '+' : '-'}${Math.floor(Math.abs(offset) / 60)}:${String(Math.abs(offset) % 60).padStart(2, '0')}.`);
+    for (const h of parsed.skippedColumns ?? []) notes.push(`Column "${h}" has a cell that is not a number or a no-value word (blank, -, NA, NaN, null), so it was left out and is not a series.`);
+    const taken = new Set<string>(['bars']);
+    const series: DataSeries[] = (parsed.extras ?? []).map((col) => {
+      const points: SeriesPoint[] = parsed.bars.map((bar, i) => {
+        const t = new Date(bar.timestamp).toISOString();
+        const v = col.values[i];
+        return typeof v === 'number' ? { t, kind: 'value', v } : { t, kind: 'unknown' };
+      });
+      return { id: idFromHeader(col.header, taken), label: col.header, points };
+    });
+    return { adapter: { name: 'csv', version: '1' }, bars: parsed.bars, series, errors: parsed.errors, notes };
+  },
+};
+
+/**
+ * The result as one set, with the bars' close as the primary series (`bars`), so `report` can say where another
+ * series has no point or a different kind of gap. The bars must be in time order (every adapter's are).
+ */
+export function toSeriesSet(result: AdapterResult): SeriesSet {
+  const bars: DataSeries = {
+    id: 'bars',
+    label: 'Close',
+    points: result.bars.map((b) => ({ t: new Date(b.timestamp).toISOString(), kind: 'value', v: b.close }) as SeriesPoint),
+  };
+  return { schemaVersion: '0', alignment: { mode: 'exact', primary: 'bars' }, series: [bars, ...result.series] };
+}

package/src/core/attributes.ts

@@ -0,0 +1,51 @@
+/**
+ * The data-attribute vocabulary every primitive speaks. State lives in `data-*`
+ * attributes, never in class names, so a host styles with `[data-side="bid"]` and the tokens in
+ * `tokens.css`. Values are the whole vocabulary: a part never invents another.
+ */
+export type Side = 'bid' | 'ask';
+/** Movement since the previous step. Not the diff status below: `data-change` is movement, `data-diff` is difference. */
+export type Change = 'up' | 'down' | 'flat';
+/** How a level differs between two books; the report's `change` field, as an attribute. */
+export type DiffStatus = 'added' | 'removed' | 'modified';
+export type Quality = 'ok' | 'gap' | 'stale' | 'truncated';
+export type CursorMark = 'a' | 'b';
+
+export interface PrimitiveState {
+  side?: Side;
+  change?: Change;
+  diff?: DiffStatus;
+  quality?: Quality;
+  cursor?: CursorMark;
+  /** True when the value comes from a synthetic session. */
+  synthetic?: boolean;
+}
+
+export type PrimitiveAttributes = {
+  /** Scopes tokens.css to primitive markup. */
+  'data-mt': '';
+  'data-side'?: Side;
+  'data-change'?: Change;
+  'data-diff'?: DiffStatus;
+  'data-quality'?: Quality;
+  'data-cursor'?: CursorMark;
+  'data-synthetic'?: '';
+};
+
+/** Spreads onto a DOM element. Unset states emit nothing, so an attribute selector never matches by accident. */
+export function primitiveAttributes(state: PrimitiveState): PrimitiveAttributes {
+  const out: PrimitiveAttributes = { 'data-mt': '' };
+  if (state.side) out['data-side'] = state.side;
+  if (state.change) out['data-change'] = state.change;
+  if (state.diff) out['data-diff'] = state.diff;
+  if (state.quality) out['data-quality'] = state.quality;
+  if (state.cursor) out['data-cursor'] = state.cursor;
+  if (state.synthetic) out['data-synthetic'] = '';
+  return out;
+}
+
+/** The width that holds the widest sample without growing, in `ch`: the value for `--mt-numeric-width`. */
+export function numericWidthValue(...samples: readonly string[]): string {
+  const longest = samples.reduce((n, s) => Math.max(n, s.length), 0);
+  return `${longest}ch`;
+}

package/src/core/candles.ts

@@ -0,0 +1,22 @@
+import type { CandleBar } from './chart-scale.js';
+
+/** Heikin Ashi bars from ordinary ones: each bar averages its own prices and the previous Heikin Ashi bar. */
+export function heikinAshi(bars: readonly CandleBar[]): CandleBar[] {
+  const out: CandleBar[] = [];
+  for (let i = 0; i < bars.length; i++) {
+    const b = bars[i];
+    const close = (b.open + b.high + b.low + b.close) / 4;
+    const open = i === 0 ? (b.open + b.close) / 2 : (out[i - 1].open + out[i - 1].close) / 2;
+    out.push({ timestamp: b.timestamp, open, close, high: Math.max(b.high, open, close), low: Math.min(b.low, open, close), volume: b.volume });
+  }
+  return out;
+}
+
+const pad = (n: number) => String(n).padStart(2, '0');
+/** The default time-axis label: HH:MM in UTC, with the month and day when the day changes from the previous label. */
+export const formatBarTime = (t: number, previous: number | null) => {
+  const d = new Date(t);
+  const time = `${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}`;
+  const sameDay = previous !== null && new Date(previous).toISOString().slice(0, 10) === d.toISOString().slice(0, 10);
+  return sameDay ? time : `${d.toISOString().slice(5, 10)} ${time}`;
+};