@eifi1/ui-kit 0.33.1 → 0.35.0

package/src/components/select.tsx

@@ -0,0 +1,302 @@
+import { useId } from "react";
+import type { KeyboardEvent, MouseEvent, ReactNode, Ref, SelectHTMLAttributes } from "react";
+import { cn } from "../lib/cn";
+import type { CommitScope } from "./write-lock";
+import {
+  LockedReason,
+  mergeDescribedBy,
+  type DisabledReasonDisplay,
+  useFieldError,
+  useFieldHint,
+  useLockReason,
+} from "./field-parts";
+import {
+  FIELD_BASE,
+  FIELD_FLOATING_PAD,
+  FIELD_INVALID,
+  FieldChevron,
+  FieldGroup,
+  FloatingField,
+  fieldBelow,
+} from "./field-base";
+
+export interface SelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>, "size"> {
+  label?: ReactNode;
+  /** See {@link Input}'s `invalid`. */
+  invalid?: boolean;
+  /** See {@link Input}'s `error`. */
+  error?: ReactNode;
+  /** A {@link FieldHint} for the label line — see {@link FloatingField}. Plain
+   *  TEXT (a string or a number) is a caption instead, and goes UNDER the field
+   *  like every other field's hint, attached through `aria-describedby`: the label
+   *  line is 11px of strip shared with the label, and a sentence placed there was
+   *  set in the value's type on top of both the label and the value. On an
+   *  UNLABELLED Select (no label line) a FieldHint sits at the field's end edge,
+   *  outside the box. Since 0.34 a FieldHint is the caption at Large and on a touch
+   *  screen, as on Input (`useInlineHint`); a `HelpPopover` stays a "?". */
+  hint?: ReactNode;
+  /**
+   * `"sm"`: a 28px, 12px-type select for a toolbar or a table header, where the
+   * 36px field stands a head taller than the buttons beside it. `"md"` (default)
+   * is the field every form uses. Unlabelled selects only — a floating label needs
+   * the tall box to float in, so a labelled Select ignores `"sm"`.
+   *
+   * A NUMBER is still the native attribute (the rows of a list box) and is passed
+   * straight through, so the one HTML meaning of `size` keeps working. Above 1 (as
+   * with `multiple`) the browser draws a list box, and the Select drops its chevron
+   * and the end padding reserved for it.
+   */
+  size?: "sm" | "md" | number;
+  /** Classes for the `<select>` itself. `className` styles the WRAPPER — the box
+   *  the chevron is positioned against — so it could set a width and nothing
+   *  else; this is the way to the element. See {@link Input}'s `inputClassName`. */
+  selectClassName?: string;
+  /**
+   * Why the choice cannot be changed — {@link Button}'s `disabledReason`, for a select
+   * that SAVES on change (a role picker in a members table, a status in a row). keksdose
+   * K3: those sat inside a hand-rolled `SaveGuard` that forced a native `disabled`, which
+   * took the field out of the tab order so the reason never reached a keyboard.
+   *
+   * With a reason the select is `aria-disabled` instead — still focusable, still showing
+   * its value — its list does not open (pointer and keys are swallowed, Tab and Escape
+   * excepted), `onChange` is never called, and the reason is a line under the field at
+   * Large and on a touch screen, else in the kit {@link Tooltip} (`disabledReasonDisplay`),
+   * and on `aria-describedby`. It wears the settled look of a disabled field and drops
+   * its chevron, as a disabled Select does (dev#474). It wins over `disabled`.
+   *
+   * Use it CONTROLLED (`value` + `onChange`): React puts a controlled value back after
+   * the swallowed change. A touch platform's own picker may still open; nothing it picks
+   * is kept or reported.
+   */
+  disabledReason?: ReactNode;
+  /**
+   * Where the reason shows — {@link Button}'s `disabledReasonDisplay`: by default a line
+   * under the field at Large and on a touch screen, the tooltip otherwise (§4 "No fact
+   * only in a tooltip"; DUP-3, refactor audit 2026-10).
+   */
+  disabledReasonDisplay?: DisabledReasonDisplay;
+  /**
+   * This select COMMITS — choosing saves. Under a locked {@link WriteLockProvider} it is
+   * locked the `disabledReason` way with the lock's reason (which wins over its own).
+   * No provider, or an unlocked one: no effect. Button's `commit`, for keksdose K3; a
+   * {@link CommitScope} since 0.33.
+   */
+  commit?: CommitScope;
+  /** The `<select>`. A React 19 ref prop since 0.34 — see {@link InputProps.ref}. */
+  ref?: Ref<HTMLSelectElement>;
+}
+
+// The compact select: the field's colours, a toolbar button's height. `py-0` and a
+// fixed height rather than a smaller padding, so the box is 28px whatever line
+// height the caller's type brings with it.
+const SELECT_SM = "h-7 py-0 ps-2 pe-7 text-xs";
+
+/** Keys a locked select still answers: leaving it, and dismissing its tooltip. Every
+ *  other key would open the list or step the value. */
+const LOCKED_SELECT_KEYS = new Set(["Tab", "Escape", "Shift"]);
+
+/** FIELD_BASE's `disabled:` look, for a select that is locked without being `disabled`
+ *  (the `:disabled` variants cannot match it). */
+const FIELD_LOCKED = "cursor-not-allowed bg-surface-2 text-muted";
+
+export function Select(props: SelectProps) {
+  const {
+    ref,
+    className,
+    label,
+    id,
+    children,
+    invalid,
+    error,
+    hint: hintProp,
+    size,
+    selectClassName,
+    disabledReason,
+    disabledReasonDisplay,
+    commit,
+    onMouseDown,
+    onKeyDown,
+    onChange,
+    ...rest
+  } = props;
+  // See Input's `reserve`.
+  const reserve = "error" in props || "hint" in props || "showCount" in props;
+  const generated = useId();
+  const lock = useLockReason(commit, disabledReason);
+  const locked = lock.locked;
+  // Only a number reaches the DOM; the two words are this component's own.
+  const nativeSize = typeof size === "number" ? size : undefined;
+  // A numeric size above 1 (or `multiple`) makes the browser draw a LIST BOX — all
+  // the rows in the field, no menu to drop. The dropdown dress did not fit it: the
+  // chevron was centred on a box several rows tall, sat on top of the rows' text
+  // at the end edge, and `pe-9` clipped every option nine units early. A list box
+  // gets the plain field instead — its own native scroll, no chevron, even padding.
+  const listBox = (nativeSize !== undefined && nativeSize > 1) || Boolean(rest.multiple);
+  const small = size === "sm" && label === undefined;
+  const fieldId = id ?? generated;
+  // Text is a caption under the field; a FieldHint rides the label line — and at Large
+  // and on a touch screen is its words, a caption like any text (§4; a HelpPopover stays
+  // on the label line, §10.23). See `hint` above. Through useFieldHint since 0.34, not a
+  // copy of its rule (DUP-2, refactor audit 2026-10).
+  const hintParts = useFieldHint(hintProp, rest["aria-describedby"]);
+  const hint = hintParts.labelHint;
+  const { isInvalid, describedBy, errorEl } = useFieldError(
+    error,
+    invalid,
+    // The caption goes in BEFORE the error — the standing advice first, the news
+    // second, the order useFieldError keeps for a caller's own description. A lock's
+    // reason sits between the two.
+    mergeDescribedBy(hintParts.describedBy, locked && lock.reasonId),
+    rest["aria-invalid"],
+  );
+  const below = fieldBelow(hintParts, null, errorEl);
+  // Custom chevron (native arrow hidden via appearance-none) so it sits a touch
+  // in from the end border and matches both themes — feedback #223. A DISABLED
+  // select has no menu to drop, so it drops the chevron too: the arrow is the one
+  // thing on the control that promises a choice (Keksdose dev#474, where the
+  // account type became read-only and still looked exactly like a picker). A locked
+  // one has no menu either.
+  const chevron =
+    rest.disabled || listBox || locked ? null : (
+      <FieldChevron className={small ? "end-1.5 size-3.5" : undefined} />
+    );
+  // `pe-9` is the room the chevron takes; a list box has none to make room for.
+  //
+  // A list box's height is `size` rows plus its padding, but its rows are clipped at
+  // the PADDING edge, not the content edge — so FIELD_BASE's `pb-2` showed the next
+  // row through the bottom padding: `size={4}` drew four and a half. The vertical room
+  // moves onto the rows instead (option padding counts toward the row height the
+  // browser sizes the box by), and the box keeps no bottom padding: exactly `size`
+  // whole rows, at any width.
+  const dress = listBox ? "overflow-y-auto [&_option]:py-1" : "appearance-none pe-9";
+  // Locked: focusable, but nothing opens the list or moves the value, and nothing is
+  // reported. The no-op `onChange` keeps a controlled select's value where React put
+  // it (and keeps React from warning about a `value` with no handler).
+  const interaction = locked
+    ? {
+        disabled: undefined,
+        "aria-disabled": true as const,
+        onMouseDown: (e: MouseEvent<HTMLSelectElement>) => e.preventDefault(),
+        onKeyDown: (e: KeyboardEvent<HTMLSelectElement>) => {
+          if (!LOCKED_SELECT_KEYS.has(e.key) && !e.ctrlKey && !e.metaKey) e.preventDefault();
+        },
+        onChange: () => {},
+      }
+    : { onMouseDown, onKeyDown, onChange };
+  // While locked the field sits in the reason's frame (the line, or the Tooltip), which
+  // becomes the outermost box — so `className` (a width, a grid cell) moves onto it, and
+  // the form keeps its layout. `block` so a full-width field stays full width inside it.
+  const boxClass = locked ? undefined : className;
+  const withReason = (box: ReactNode) =>
+    locked ? (
+      <LockedReason lock={lock} display={disabledReasonDisplay} className={cn("block", className)}>
+        {box}
+      </LockedReason>
+    ) : (
+      box
+    );
+  if (label === undefined) {
+    const select = (
+      <select
+        ref={ref}
+        // `id` is destructured out of the props to feed `fieldId`, and this branch
+        // never put it back — so an UNLABELLED Select swallowed it and the
+        // consumer's own `<label for="…">` pointed at nothing. The control stayed
+        // in the tab order with no accessible name at all: reachable, and silent
+        // when it was reached. Input and Textarea both forward it here; this is
+        // the third one doing the same thing.
+        id={id}
+        size={nativeSize}
+        {...rest}
+        {...interaction}
+        // OR-ed with the spread for the reason spelled out on Input's copy: this
+        // branch wrote `invalid || undefined`, so passing `aria-invalid` by hand
+        // to a Select — which is what a caller does when the validity is
+        // `"grammar"` or `"spelling"`, or when the paint is not wanted — had the
+        // attribute silently dropped. Input has never done that.
+        aria-invalid={isInvalid || rest["aria-invalid"] || undefined}
+        aria-describedby={describedBy}
+        className={cn(
+          FIELD_BASE,
+          dress,
+          listBox && "py-0",
+          small && SELECT_SM,
+          locked && FIELD_LOCKED,
+          selectClassName,
+          isInvalid && FIELD_INVALID,
+        )}
+      >
+        {children}
+      </select>
+    );
+    // A FieldHint with no label line to ride (0.15.5 P8): an unlabelled Select — named
+    // by `aria-label` or a `<label>` of the caller's — dropped a non-text `hint`
+    // without a trace, so the "?" a caller passed never rendered and a test looking
+    // for its button found none. It goes at the end of the field instead, outside the
+    // box, as the label line's own hint goes at the end of the label.
+    if (hint !== undefined) {
+      return (
+        <FieldGroup errorEl={below} reserve={reserve}>
+          {withReason(
+            <div className={cn("flex items-center gap-1.5", boxClass)}>
+              <div className="relative min-w-0 flex-1">
+                {select}
+                {chevron}
+              </div>
+              <span className="flex shrink-0 items-center">{hint}</span>
+            </div>,
+          )}
+        </FieldGroup>
+      );
+    }
+    return (
+      <FieldGroup errorEl={below} reserve={reserve}>
+        {withReason(
+          <div className={cn("relative", boxClass)}>
+            {select}
+            {chevron}
+          </div>,
+        )}
+      </FieldGroup>
+    );
+  }
+  return (
+    <FieldGroup errorEl={below} reserve={reserve}>
+      {withReason(
+        <FloatingField
+          className={boxClass}
+          htmlFor={fieldId}
+          label={label}
+          staticLabel
+          hint={hint}
+        >
+          <select
+            ref={ref}
+            id={fieldId}
+            size={nativeSize}
+            {...rest}
+            {...interaction}
+            aria-invalid={isInvalid || rest["aria-invalid"] || undefined}
+            aria-describedby={describedBy}
+            className={cn(
+              FIELD_BASE,
+              // The floated label takes the top strip of a list box too, so its first
+              // row starts under the label rather than behind it. No bottom padding — see
+              // `dress`.
+              // At Large the label stands above the field (§10.17): no strip.
+              listBox ? "pt-5 pb-0 large:pt-2" : FIELD_FLOATING_PAD,
+              "peer",
+              dress,
+              locked && FIELD_LOCKED,
+              selectClassName,
+              isInvalid && FIELD_INVALID,
+            )}
+          >
+            {children}
+          </select>
+          {chevron}
+        </FloatingField>,
+      )}
+    </FieldGroup>
+  );
+}

package/src/components/separator.tsx

@@ -1,7 +1,7 @@
-import type { ComponentPropsWithoutRef } from "react";
+import type { ComponentPropsWithRef } from "react";
 import { cn } from "../lib/cn";
 
-export interface SeparatorProps extends Omit<ComponentPropsWithoutRef<"div">, "children" | "role"> {
+export interface SeparatorProps extends Omit<ComponentPropsWithRef<"div">, "children" | "role"> {
   orientation?: "horizontal" | "vertical";
   /**
    * `false` (default, as in Radix): a real `role="separator"`, which a reader

package/src/components/series-chart-axes.ts

@@ -0,0 +1,329 @@
+// The series chart's pure half: the axis bands, the padded and anchored domains, the
+// series keys and colours, and the abscissa reduced to a number line. No React, no
+// recharts and no JSX here (chart-zoom-core lends the one name `DEFAULT_Y_AXIS`) —
+// arithmetic over rows and axes, which is why apps import some of it in
+// files that draw no chart (Kurvenschmiede's curve-chart-model.ts builds its series
+// keys with `seriesKey`).
+//
+// Moved out of series-chart.tsx as it was (MOD-9, refactor audit 2026-10). The public
+// names are still exported from series-chart.tsx, so `/chart` and the barrel are
+// unchanged; this module is not an entry of its own. The names below that series-chart
+// does not re-export (the tick-band constants, `xModel`, `finite`, …) stay internal.
+import { DEFAULT_Y_AXIS } from "./chart-zoom-core";
+import type { TimeTickUnit } from "./series-chart-ticks";
+import { paletteFor } from "../theme/chart-palette";
+import type {
+  SeriesChartAxis,
+  SeriesChartRow,
+  SeriesChartSeries,
+  SeriesChartTickValues,
+  SeriesChartX,
+  SeriesChartXValue,
+} from "./series-chart";
+
+/** How much of an axis band the rotated title takes, in px at Normal — × the text size's
+ *  scale on the chart (§3.2), since the title is text. Reserved rather than shared with
+ *  the ticks: a title merely offset inside the band prints on top of a five-figure tick,
+ *  and which gives way depends on the data. */
+export const AXIS_TITLE_STRIP = 16;
+
+/** Where inside its strip the rotated title sits. */
+export const AXIS_TITLE_OFFSET = 10;
+
+/** The tallest band tilted x ticks reserve, in px at Normal (× the scale). A category
+ *  name longer than this at its angle is clipped rather than squeezing the plot down to
+ *  a strip. */
+const MAX_TILTED_TICK_BAND = 120;
+
+/** What one character of a tick label is taken to be, in px at Normal, for the tilted
+ *  band — the shell's `text-xs`. An estimate: the SVG is not laid out yet when the band
+ *  is decided. Both grow with the text size, as `text-xs` does (§3.2). */
+const TICK_CHAR_WIDTH = 7;
+const TICK_LINE_HEIGHT = 12;
+/** recharts' gap between the axis line and a bottom tick's text — px, at every size:
+ *  recharts draws it, not the type. */
+const TICK_GAP = 8;
+/** recharts' own band under level x ticks. */
+const LEVEL_TICK_BAND = 30;
+/** The least room recharts' x ticks keep between labels, in px at Normal. */
+export const MIN_TICK_GAP = 32;
+
+/**
+ * The height the x axis reserves for its ticks at a text `scale`: tilted by `angle`
+ * degrees, the rotated box of the longest label, from its length; level, recharts' own
+ * 30 px grown with the labels. `undefined` for level ticks at Normal, where recharts'
+ * default is exactly that.
+ */
+export function tiltedTickBand(labels: readonly string[], angle: number, scale = 1): number | undefined {
+  if (!angle) return scale === 1 ? undefined : Math.ceil(LEVEL_TICK_BAND * scale);
+  const rad = (Math.abs(angle) * Math.PI) / 180;
+  const longest = Math.max(0, ...labels.map((label) => label.length)) * TICK_CHAR_WIDTH * scale;
+  const band = Math.sin(rad) * longest + Math.cos(rad) * TICK_LINE_HEIGHT * scale + TICK_GAP;
+  return Math.min(Math.round(MAX_TILTED_TICK_BAND * scale), Math.max(Math.ceil(LEVEL_TICK_BAND * scale), Math.ceil(band)));
+}
+
+/** The width the ticks of a y axis get when a caller does not say, in px at Normal. */
+export const AXIS_TICK_WIDTH = 48;
+
+/**
+ * How much air a FITTED axis leaves between the data and its frame, as a fraction of
+ * the range. Recharts fits `[dataMin, dataMax]`, which draws a peak half a stroke
+ * outside the plot and a curve running to its limit indistinguishable from the frame.
+ */
+const AUTO_PAD = 0.04;
+
+/** The band a fitted axis draws, padded — and a real band for constant data, which is
+ *  a zero-height domain recharts cannot scale into. `undefined` when nothing finite. */
+export function paddedDomain(values: Iterable<number>): [number, number] | undefined {
+  let low = Infinity;
+  let high = -Infinity;
+  for (const value of values) {
+    if (!Number.isFinite(value)) continue;
+    if (value < low) low = value;
+    if (value > high) high = value;
+  }
+  return padBand(low, high);
+}
+
+/**
+ * {@link paddedDomain} for a caller that has already walked its own data — so a row
+ * of charts can share one scale without building an array to find two numbers in, and
+ * without a second padding rule. `low > high` means "nothing was seen": `undefined`.
+ */
+export function padBand(low: number, high: number): [number, number] | undefined {
+  if (!(low <= high)) return undefined;
+  const pad = (high - low) * AUTO_PAD || Math.abs(high) * AUTO_PAD || 1;
+  return [low - pad, high + pad];
+}
+
+/**
+ * The whole band a y axis occupies: its ticks, and its title when it draws one. For
+ * lining a heading up over a PLOT rather than over its column.
+ *
+ * `scale` is the text size's (`useTextSize().scale`, §3.2, §10.10): the chart draws every
+ * band — the default 48 px and a caller's own `width` alike (keksdose's
+ * `MONEY_AXIS_WIDTH`) — this many times wider, because the ticks in it are `text-xs`
+ * and grow with the text. A heading lined up over the plot has to pass the same scale.
+ * One factor for both sides of a facing pair, so the mirrored bands stay equal.
+ */
+export function axisBandWidth(tickWidth: number | undefined, titled: boolean, scale = 1): number {
+  const band = (tickWidth ?? AXIS_TICK_WIDTH) + (titled ? AXIS_TITLE_STRIP : 0);
+  return scale === 1 ? band : Math.round(band * scale);
+}
+
+/**
+ * The colour an axis TITLE takes, or `undefined` for the neutral one.
+ *
+ * An axis measuring exactly one line is that line's, and saying so in the title lets a
+ * reader find a channel's scale without counting axes. An axis measuring several is
+ * nobody's — a title in the first one's colour would be claiming it. Counted off the
+ * series, so toggling a second line onto an axis gives the colour up in the same render.
+ */
+export function soleSeriesColor(
+  axis: Pick<SeriesChartAxis, "id" | "color">,
+  series: readonly Pick<SeriesChartSeries, "axis">[],
+): string | undefined {
+  const mine = series.filter((entry) => (entry.axis ?? DEFAULT_Y_AXIS) === axis.id);
+  return mine.length === 1 ? axis.color : undefined;
+}
+
+/** The single-axis case, which is most charts. `width` is what the TICKS need;
+ *  `orientation` is which side they stand on. */
+export function oneAxis(
+  format: ((value: number) => string) | undefined,
+  title: string,
+  width?: number,
+  orientation?: "left" | "right",
+): SeriesChartAxis[] {
+  return [{ id: DEFAULT_Y_AXIS, format, title, width, orientation }];
+}
+
+/** One source's samples: an abscissa and the channels measured against it. */
+export interface SeriesSource {
+  x: number[];
+  channels: Record<string, number[]>;
+}
+
+/**
+ * Merge sources sampled on different grids into rows the chart can draw.
+ *
+ * Merged ON THE ABSCISSA VALUE ITSELF, never interpolated onto a common grid: a line
+ * through invented points looks exactly like one through measured ones. Where a source
+ * has no sample the key is absent, and `connectNulls` bridges the hole with the same
+ * straight segment an interpolation would have drawn — without claiming a measurement.
+ */
+export function mergeSeries(sources: SeriesSource[]): Record<string, number>[] {
+  const byAbscissa = new Map<number, Record<string, number>>();
+  for (const source of sources) {
+    source.x.forEach((value, index) => {
+      const row = byAbscissa.get(value) ?? { x: value };
+      for (const [key, channel] of Object.entries(source.channels)) row[key] = channel[index];
+      byAbscissa.set(value, row);
+    });
+  }
+  return [...byAbscissa.values()].sort((a, b) => a.x - b.x);
+}
+
+/**
+ * A series key built out of parts — as a CSS identifier.
+ *
+ * The chart shell paints each series through `--color-<key>`, and skips (with a
+ * console warning) any key that is not `[A-Za-z_][A-Za-z0-9_-]*`. A line whose colour
+ * was skipped has no stroke at all: an axis, a grid and nothing between them. So a key
+ * assembled out of DATA — an id, an enum, a side — goes through here: every other
+ * character becomes `_`, the parts are joined with `_`, and a key that would start with
+ * a digit or a hyphen gets a leading `_`.
+ */
+export function seriesKey(...parts: (string | number)[]): string {
+  const key = parts.map((part) => String(part).replace(/[^A-Za-z0-9_-]/g, "_")).join("_");
+  return /^[A-Za-z_]/.test(key) ? key : `_${key}`;
+}
+
+/**
+ * The band an axis carrying bars or areas draws: the data's extent with ZERO in it,
+ * padded only on the sides that are not zero — bars standing on a frame's bottom edge,
+ * not floating four per cent above it on a band of air nobody asked for.
+ * `undefined` when there is nothing to fit.
+ */
+export function anchoredBand(extent: readonly [number, number] | undefined): [number, number] | undefined {
+  if (!extent) return undefined;
+  const low = Math.min(0, extent[0]);
+  const high = Math.max(0, extent[1]);
+  const pad = (high - low) * AUTO_PAD || 1;
+  return [low < 0 ? low - pad : 0, high > 0 ? high + pad : 0];
+}
+
+/**
+ * Series with their colours settled BEFORE any are switched off.
+ *
+ * A series with no `color` takes `paletteFor(its position)` — and a legend toggle that
+ * hands the chart a shorter list moves every later series one position up, repainting
+ * it in its neighbour's colour on each click. Resolving the colours on the full list
+ * and filtering after keeps each series in the colour its legend entry shows.
+ */
+export function visibleSeries(
+  series: readonly SeriesChartSeries[],
+  hidden: ReadonlySet<string>,
+): SeriesChartSeries[] {
+  return series
+    .map((entry, index) => ({ ...entry, color: entry.color ?? paletteFor(index) }))
+    .filter((entry) => !hidden.has(entry.key));
+}
+
+/** Where a category or time chart keeps each row's plotted position. Not the caller's
+ *  key: that one still holds their own value, which `format` and a hit hand back. */
+const PLOTTED_X = "__seriesChartX";
+
+/** A finite number, or `undefined` — the only thing a row cell counts as a sample. */
+export const finite = (value: unknown): number | undefined =>
+  typeof value === "number" && Number.isFinite(value) ? value : undefined;
+
+/** A time value as epoch ms. A date-only ISO string is LOCAL midnight (see
+ *  `SeriesChartX.type`); anything unreadable is `undefined`, i.e. not plotted. */
+function toTime(value: unknown): number | undefined {
+  if (value instanceof Date) return finite(value.getTime());
+  if (typeof value === "number") return finite(value);
+  if (typeof value !== "string") return undefined;
+  const day = /^(\d{4})-(\d{2})(?:-(\d{2}))?$/.exec(value);
+  if (day) return new Date(Number(day[1]), Number(day[2]) - 1, Number(day[3] ?? 1)).getTime();
+  return finite(Date.parse(value));
+}
+
+/** A category's identity, so a Date matches another Date of the same instant. */
+const categoryId = (value: unknown) =>
+  value instanceof Date ? `d:${value.getTime()}` : `${typeof value}:${String(value)}`;
+
+/**
+ * The abscissa, reduced to a number line — which is all the plot, the ticks and the
+ * zoom ever deal in. A number stays itself; a category becomes its slot index; a time
+ * its epoch ms. Everything the caller sees (ticks, tooltip, hits) is turned back.
+ */
+export interface XModel {
+  kind: "number" | "category" | "time";
+  /** The caller's key, still holding their value. */
+  sourceKey: string;
+  /** The key the plot reads. The same as `sourceKey` on a number line. */
+  plotKey: string;
+  /** The rows as plotted. The caller's own on a number line. */
+  rows: readonly SeriesChartRow[];
+  /** The caller's rows, which dots and hits hand back. */
+  source: readonly SeriesChartRow[];
+  position: (value: unknown) => number | undefined;
+  valueAt: (position: number) => SeriesChartXValue;
+}
+
+export function xModel(rows: readonly SeriesChartRow[], x: SeriesChartX): XModel {
+  const sourceKey = x.key ?? "x";
+  if (x.type === "category") {
+    const slots = new Map<string, number>();
+    rows.forEach((row, index) => {
+      const id = categoryId(row[sourceKey]);
+      if (!slots.has(id)) slots.set(id, index);
+    });
+    return {
+      kind: "category",
+      sourceKey,
+      plotKey: PLOTTED_X,
+      rows: rows.map((row, index) => ({ ...row, [PLOTTED_X]: index })),
+      source: rows,
+      position: (value) => slots.get(categoryId(value)),
+      valueAt: (position) => rows[Math.round(position)]?.[sourceKey] as SeriesChartXValue,
+    };
+  }
+  if (x.type === "time") {
+    return {
+      kind: "time",
+      sourceKey,
+      plotKey: PLOTTED_X,
+      rows: rows.map((row) => ({ ...row, [PLOTTED_X]: toTime(row[sourceKey]) })),
+      source: rows,
+      position: toTime,
+      valueAt: (position) => new Date(position),
+    };
+  }
+  return {
+    kind: "number",
+    sourceKey,
+    plotKey: sourceKey,
+    rows,
+    source: rows,
+    position: finite,
+    valueAt: (position) => position,
+  };
+}
+
+/** Caller ticks, as positions inside the domain on show. */
+export function resolveTicks<T>(
+  values: SeriesChartTickValues<T> | undefined,
+  domain: [number, number] | undefined,
+  position: (value: T) => number | undefined,
+): number[] | undefined {
+  if (!values || !domain) return undefined;
+  const list = typeof values === "function" ? values(domain) : values;
+  if (!list) return undefined;
+  const slack = (domain[1] - domain[0]) * 1e-9;
+  return list
+    .map(position)
+    .filter((at): at is number => at !== undefined && at >= domain[0] - slack && at <= domain[1] + slack);
+}
+
+/** A low/high pair widened by some values, or `undefined` if there is still none. */
+export function extend(
+  span: readonly [number, number] | undefined,
+  values: readonly (number | undefined)[],
+): [number, number] | undefined {
+  let out: [number, number] | undefined = span ? [span[0], span[1]] : undefined;
+  for (const value of values) {
+    if (value === undefined || !Number.isFinite(value)) continue;
+    out = out ? [Math.min(out[0], value), Math.max(out[1], value)] : [value, value];
+  }
+  return out;
+}
+
+/** How a time tick is written, by what one step of the ticks is. */
+export const TIME_TICK_FORMAT: Record<TimeTickUnit, Intl.DateTimeFormatOptions> = {
+  hour: { hour: "2-digit", minute: "2-digit" },
+  day: { day: "numeric", month: "short" },
+  month: { month: "short", year: "2-digit" },
+  year: { year: "numeric" },
+};