@eifi1/ui-kit 0.4.0 → 0.5.0

package/dist/components/series-chart.js

@@ -0,0 +1,223 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { CartesianGrid, Label, Line, LineChart, ReferenceLine, XAxis, YAxis } from "recharts";
+import { ChartContainer, ChartTooltip, ChartTooltipContent } from "./chart.js";
+import { DEFAULT_Y_AXIS, withChartZoom } from "./chart-zoom.js";
+import { STEP_DASH, strokeDash } from "./toggle-legend.js";
+import { DEFAULT_SERIES_CHART_LABELS } from "./series-chart-labels.js";
+import { paletteFor } from "../theme/chart-palette.js";
+import { useKitLabels, useKitLocale } from "../i18n/kit-labels.js";
+import { cn } from "../lib/cn.js";
+const AXIS_TITLE_STRIP = 16;
+const AXIS_TITLE_OFFSET = 10;
+const AXIS_TICK_WIDTH = 48;
+const AUTO_PAD = 0.04;
+function paddedDomain(values) {
+  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);
+}
+function padBand(low, high) {
+  if (!(low <= high)) return void 0;
+  const pad = (high - low) * AUTO_PAD || Math.abs(high) * AUTO_PAD || 1;
+  return [low - pad, high + pad];
+}
+function axisBandWidth(tickWidth, titled) {
+  return (tickWidth ?? AXIS_TICK_WIDTH) + (titled ? AXIS_TITLE_STRIP : 0);
+}
+function soleSeriesColor(axis, series) {
+  const mine = series.filter((entry) => (entry.axis ?? DEFAULT_Y_AXIS) === axis.id);
+  return mine.length === 1 ? axis.color : void 0;
+}
+function oneAxis(format, title, width, orientation) {
+  return [{ id: DEFAULT_Y_AXIS, format, title, width, orientation }];
+}
+function mergeSeries(sources) {
+  const byAbscissa = /* @__PURE__ */ new Map();
+  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);
+}
+function seriesKey(...parts) {
+  const key = parts.map((part) => String(part).replace(/[^A-Za-z0-9_-]/g, "_")).join("_");
+  return /^[A-Za-z_]/.test(key) ? key : `_${key}`;
+}
+function useDefaultFormat(localeProp) {
+  const locale = useKitLocale(localeProp);
+  return useMemo(() => {
+    const format = new Intl.NumberFormat(locale, { maximumFractionDigits: 2 });
+    return (value) => format.format(value);
+  }, [locale]);
+}
+const ONE_UNTITLED_AXIS = [{ id: DEFAULT_Y_AXIS, title: "" }];
+function StaticSeriesChart({
+  rows,
+  x = {},
+  series,
+  axes = ONE_UNTITLED_AXIS,
+  valueFormat,
+  height = "h-72",
+  connectNulls,
+  empty,
+  animationMs = 0,
+  spans,
+  zoom,
+  labels: labelsProp,
+  locale,
+  className
+}) {
+  const labels = useKitLabels("seriesChart", DEFAULT_SERIES_CHART_LABELS, labelsProp);
+  const number = useDefaultFormat(locale);
+  if (!rows.length || !series.length) {
+    return /* @__PURE__ */ jsx("div", { className: cn("flex w-full items-center justify-center px-2 text-center", height), children: empty !== void 0 ? empty : /* @__PURE__ */ jsx("p", { className: "text-xs text-[var(--text-muted)]", children: labels.empty }) });
+  }
+  const xKey = x.key ?? "x";
+  const xFormat = x.format ?? number;
+  const config = Object.fromEntries(
+    series.map((entry, index) => [
+      entry.key,
+      { label: entry.label, color: entry.color ?? paletteFor(index) }
+    ])
+  );
+  const visible = axes.filter((axis) => !axis.hide);
+  const gridAxis = (visible[0] ?? axes[0])?.id ?? DEFAULT_Y_AXIS;
+  const onLeft = visible.some((axis) => (axis.orientation ?? "left") === "left");
+  const onRight = visible.some((axis) => axis.orientation === "right");
+  const margin = {
+    top: 8,
+    right: onRight ? 0 : 10,
+    left: onLeft ? 0 : 10,
+    // Under the ticks, not under the whole axis: whatever comes next owns the gap.
+    bottom: x.title ? 18 : 2
+  };
+  const fittedX = zoom?.xDomain ?? paddedDomain(rows.map((row) => row[xKey]));
+  const fittedY = (axis) => zoom?.yDomains[axis.id] ?? axis.domain ?? paddedDomain(
+    series.filter((entry) => (entry.axis ?? DEFAULT_Y_AXIS) === axis.id).flatMap((entry) => rows.map((row) => row[entry.key]))
+  );
+  return /* @__PURE__ */ jsx(ChartContainer, { config, className: cn("w-full", height, className), children: /* @__PURE__ */ jsxs(LineChart, { data: rows, margin, children: [
+    /* @__PURE__ */ jsx(CartesianGrid, { yAxisId: gridAxis }),
+    /* @__PURE__ */ jsx(
+      XAxis,
+      {
+        dataKey: xKey,
+        type: "number",
+        domain: fittedX ?? ["dataMin", "dataMax"],
+        allowDataOverflow: zoom?.xDomain !== void 0,
+        tickLine: false,
+        axisLine: false,
+        minTickGap: 32,
+        tick: x.ticks === false ? false : void 0,
+        height: x.ticks === false && !x.title ? 4 : void 0,
+        tickFormatter: xFormat,
+        children: x.title && /* @__PURE__ */ jsx(
+          Label,
+          {
+            value: x.title,
+            position: "insideBottom",
+            offset: -12,
+            className: "fill-[var(--text-muted)] text-[11px]"
+          }
+        )
+      }
+    ),
+    axes.map((axis) => /* @__PURE__ */ jsx(
+      YAxis,
+      {
+        yAxisId: axis.id,
+        hide: axis.hide,
+        domain: fittedY(axis),
+        allowDataOverflow: zoom?.yDomains[axis.id] !== void 0,
+        orientation: axis.orientation ?? "left",
+        width: axisBandWidth(axis.width, Boolean(axis.title) && !axis.hide),
+        tickLine: false,
+        axisLine: false,
+        tickFormatter: axis.format ?? number,
+        tick: axis.color ? { fill: axis.color } : void 0,
+        children: axis.title && !axis.hide && /* @__PURE__ */ jsx(
+          Label,
+          {
+            value: axis.title,
+            angle: axis.orientation === "right" ? 90 : -90,
+            position: axis.orientation === "right" ? "insideRight" : "insideLeft",
+            style: { textAnchor: "middle", fill: soleSeriesColor(axis, series) },
+            offset: AXIS_TITLE_OFFSET,
+            className: "fill-[var(--text-muted)] text-[11px]"
+          }
+        )
+      },
+      axis.id
+    )),
+    /* @__PURE__ */ jsx(
+      ChartTooltip,
+      {
+        content: /* @__PURE__ */ jsx(
+          ChartTooltipContent,
+          {
+            labelFormatter: (value) => (x.label ?? xFormat)(Number(value)),
+            valueFormatter: valueFormat ?? number
+          }
+        )
+      }
+    ),
+    series.map((entry) => /* @__PURE__ */ jsx(
+      Line,
+      {
+        yAxisId: entry.axis ?? DEFAULT_Y_AXIS,
+        type: entry.step ? "stepAfter" : "monotone",
+        dataKey: entry.key,
+        stroke: `var(--color-${entry.key})`,
+        strokeWidth: entry.step ? 1.5 : 2,
+        strokeDasharray: strokeDash(
+          entry.step ? STEP_DASH : entry.dash ?? (entry.dashed ? 1 : 0)
+        ),
+        dot: false,
+        connectNulls,
+        isAnimationActive: animationMs > 0,
+        animationDuration: animationMs,
+        animationEasing: "ease-out"
+      },
+      entry.key
+    )),
+    spans?.map((span) => /* @__PURE__ */ jsx(
+      ReferenceLine,
+      {
+        yAxisId: span.axis ?? DEFAULT_Y_AXIS,
+        segment: [
+          { x: span.x, y: span.from },
+          { x: span.x, y: span.to }
+        ],
+        stroke: span.color ?? "var(--text-muted)",
+        strokeWidth: 2,
+        ifOverflow: "discard"
+      },
+      span.key
+    )),
+    zoom?.layer
+  ] }) });
+}
+const SeriesChart = withChartZoom(StaticSeriesChart);
+export {
+  AXIS_TICK_WIDTH,
+  AXIS_TITLE_STRIP,
+  SeriesChart,
+  StaticSeriesChart,
+  axisBandWidth,
+  mergeSeries,
+  oneAxis,
+  padBand,
+  paddedDomain,
+  seriesKey,
+  soleSeriesColor
+};
+//# sourceMappingURL=series-chart.js.map

package/dist/components/series-chart.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/series-chart.tsx"],"sourcesContent":["// The measurement plot: series against a swept numeric abscissa, any number of y axes,\n// dash patterns, vertical spans, and drag-to-zoom. Lifted out of lenkbank, where every\n// chart on every screen is this one arrangement of the kit's shell — so the arrangement\n// lives here once instead of as thirteen hand-assembled copies drifting apart.\n//\n// Built on `ChartContainer` + `ChartTooltipContent`, so it themes with the rest of the\n// chart kit: series default to the `--chart-N` ramp, axis text and grid take the\n// shell's tokens. It stays domain-free — every unit, title and number format is the\n// caller's, and the few words it can say itself are the `seriesChart` label namespace.\n//\n// **Every series may keep its own scale.** Position runs in millimetres and jerk in\n// hundreds of thousands of them per second cubed; on one axis the position line is\n// flat against the bottom. Normalising each series to its peak makes the y axis mean\n// nothing, so a caller declares an axis per incomparable channel instead, and may hide\n// all but the ones worth a column of numbers.\n//\n// Charts are drawn left-to-right in every writing direction — an abscissa is a number\n// line, not text — so `orientation` below is physical, and only the HTML chrome (the\n// reset button) is placed by logical side.\nimport { useMemo } from \"react\";\nimport type { ReactNode } from \"react\";\nimport { CartesianGrid, Label, Line, LineChart, ReferenceLine, XAxis, YAxis } from \"recharts\";\nimport { ChartContainer, ChartTooltip, ChartTooltipContent, type ChartConfig } from \"./chart\";\nimport { DEFAULT_Y_AXIS, withChartZoom, type ZoomBinding } from \"./chart-zoom\";\nimport { STEP_DASH, strokeDash } from \"./toggle-legend\";\nimport { DEFAULT_SERIES_CHART_LABELS, type SeriesChartLabels } from \"./series-chart-labels\";\nimport { paletteFor } from \"../theme/chart-palette\";\nimport { useKitLabels, useKitLocale } from \"../i18n/kit-labels\";\nimport { cn } from \"../lib/cn\";\n\nexport interface SeriesChartSeries {\n  /** The row key this line reads — and the `--color-<key>` it is painted with, so it\n   *  must be a CSS identifier. Build keys out of data with {@link seriesKey}. */\n  key: string;\n  label: ReactNode;\n  /** Any CSS colour the chart shell accepts (hex, rgb/hsl, `var(--token)`). Default:\n   *  the kit's categorical ramp by position, `paletteFor(index)`. */\n  color?: string;\n  /** Marks the PAIRED line of a pair — the return stroke against the out-stroke, the\n   *  reference against the measurement. Shorthand for `dash: 1`. */\n  dashed?: boolean;\n  /** Which of {@link STROKE_PATTERNS} this line takes, for charts where the stroke says\n   *  WHICH QUANTITY and the colour says WHICH MEASUREMENT. */\n  dash?: number;\n  /** `stepAfter`, for a whole-number channel that jumps rather than travels — a\n   *  straight line between index 0 and index 1 draws an index of 0.5, which does not\n   *  exist. Drawn in the {@link STEP_DASH} pattern, whatever `dash` says. */\n  step?: boolean;\n  /** Which of `axes` this line is measured on. Default: `\"y\"`, the single one. */\n  axis?: string;\n}\n\ninterface SeriesChartAxisShape {\n  id: string;\n  /**\n   * Which side of the plot the ticks stand on. Left unless said otherwise — and said\n   * otherwise for the right-hand chart of a FACING pair (see `facingAxes`), whose\n   * scales go on the outside so neither column of numbers stands between two pictures\n   * being compared.\n   */\n  orientation?: \"left\" | \"right\";\n  /** Tints the ticks — and the title too, when exactly one series is measured on this\n   *  axis (see {@link soleSeriesColor}). */\n  color?: string;\n  /** What the TICKS need, in px. The title's strip is added on top. Default 48. */\n  width?: number;\n  /**\n   * Pin the scale instead of fitting it to this chart's data. For a ROW of charts\n   * read against each other: auto-fitted, a 200 N loop and a 2000 N one draw the\n   * identical picture, and the comparison the layout promises is the one it fails.\n   */\n  domain?: [number, number];\n  /** A tick, formatted — as a BARE number. The unit is said once, in the title; the\n   *  tooltip gets it from `valueFormat`. Default: `Intl.NumberFormat` in the kit's\n   *  locale, up to two fraction digits. */\n  format?: (value: number) => string;\n}\n\n/**\n * A y axis — and a VISIBLE one says what it measures.\n *\n * A union rather than an optional field, so the rule is the type's: a column of numbers\n * whose quantity and unit are not written down is a column somebody reads as whatever\n * they expected. `title: \"\"` is the explicit opt-out (the right-hand chart of a facing\n * pair, whose neighbour already said it). A HIDDEN axis scales its lines and draws\n * nothing, so there is nowhere for a title to go.\n */\nexport type SeriesChartAxis = SeriesChartAxisShape &\n  ({ title: string; hide?: false } | { title?: string; hide: true });\n\nexport interface SeriesChartX {\n  /** Row key of the abscissa. Default `\"x\"`, which is what {@link mergeSeries} writes. */\n  key?: string;\n  /** What the abscissa is, with its unit. Drawn under the axis. */\n  title?: string;\n  /** A tick, formatted — bare, like the y axes'. */\n  format?: (value: number) => string;\n  /**\n   * Whether this chart prints the abscissa's ticks. On by default; off for every chart\n   * of a stack sharing one x window but the bottom one, which prints them for all. It\n   * costs no alignment: the x mapping is decided by the margins and the y bands.\n   */\n  ticks?: boolean;\n  /** The tooltip's heading. Default: the abscissa value through `format`. */\n  label?: (value: number) => ReactNode;\n}\n\n/**\n * A vertical segment in data coordinates — two y at one x, which a row-per-abscissa\n * chart structurally cannot draw. For CLOSING a shape the series already drew: the\n * turnarounds of a hysteresis loop, where the abscissa stands still while the value\n * falls from one branch to the other.\n */\nexport interface SeriesChartSpan {\n  /** Distinct within the chart. */\n  key: string;\n  /** Which y axis `from`/`to` are measured on. Default `\"y\"`. */\n  axis?: string;\n  x: number;\n  from: number;\n  to: number;\n  /** Default: `var(--text-muted)`. */\n  color?: string;\n}\n\nexport interface SeriesChartProps {\n  /** One row per abscissa value. A missing key is a hole (see `connectNulls`). */\n  rows: Record<string, number>[];\n  series: SeriesChartSeries[];\n  /** Default: one untitled axis, `\"y\"`. */\n  axes?: SeriesChartAxis[];\n  x?: SeriesChartX;\n  /** A value in the tooltip, where a number stands on its own and needs its unit.\n   *  Default: `Intl.NumberFormat` in the kit's locale. */\n  valueFormat?: (value: number) => string;\n  /** Tailwind height class. Default `h-72`. The empty state takes it too, so a chart\n   *  losing its last line does not relayout the page under it. */\n  height?: string;\n  /** Bridge holes left by sources sampled on different grids. See {@link mergeSeries}. */\n  connectNulls?: boolean;\n  /** Shown, centred at the chart's height, instead of an empty chart. Default: the\n   *  `seriesChart.empty` label. `null` shows nothing. */\n  empty?: ReactNode;\n  /**\n   * Milliseconds for a line to draw itself in. Off by default: a chart beside a live\n   * editor re-renders on every keystroke, and an animation restarted mid-flight reads\n   * as the curve twitching. Turn it on where series come and go by choice.\n   */\n  animationMs?: number;\n  spans?: SeriesChartSpan[];\n  /** Supplied by `withChartZoom` and by nothing else. */\n  zoom?: ZoomBinding;\n  /** Per-chart strings over `<UiKitProvider labels={{ seriesChart }}>`. */\n  labels?: Partial<SeriesChartLabels>;\n  /** BCP 47 tag for the default number formats. Default: the provider's. */\n  locale?: string;\n  /** Onto the chart's root (`ChartContainer`) — e.g. an app's own grid ink. */\n  className?: string;\n}\n\n/** How much of an axis band the rotated title takes, in px. Reserved rather than\n *  shared with the ticks: a title merely offset inside the band prints on top of a\n *  five-figure tick, and which gives way depends on the data. */\nexport const AXIS_TITLE_STRIP = 16;\n\n/** Where inside its strip the rotated title sits. */\nconst AXIS_TITLE_OFFSET = 10;\n\n/** The width the ticks of a y axis get when a caller does not say. */\nexport const AXIS_TICK_WIDTH = 48;\n\n/**\n * How much air a FITTED axis leaves between the data and its frame, as a fraction of\n * the range. Recharts fits `[dataMin, dataMax]`, which draws a peak half a stroke\n * outside the plot and a curve running to its limit indistinguishable from the frame.\n */\nconst AUTO_PAD = 0.04;\n\n/** The band a fitted axis draws, padded — and a real band for constant data, which is\n *  a zero-height domain recharts cannot scale into. `undefined` when nothing finite. */\nexport function paddedDomain(values: Iterable<number>): [number, number] | undefined {\n  let low = Infinity;\n  let high = -Infinity;\n  for (const value of values) {\n    if (!Number.isFinite(value)) continue;\n    if (value < low) low = value;\n    if (value > high) high = value;\n  }\n  return padBand(low, high);\n}\n\n/**\n * {@link paddedDomain} for a caller that has already walked its own data — so a row\n * of charts can share one scale without building an array to find two numbers in, and\n * without a second padding rule. `low > high` means \"nothing was seen\": `undefined`.\n */\nexport function padBand(low: number, high: number): [number, number] | undefined {\n  if (!(low <= high)) return undefined;\n  const pad = (high - low) * AUTO_PAD || Math.abs(high) * AUTO_PAD || 1;\n  return [low - pad, high + pad];\n}\n\n/** The whole band a y axis occupies: its ticks, and its title when it draws one. For\n *  lining a heading up over a PLOT rather than over its column. */\nexport function axisBandWidth(tickWidth: number | undefined, titled: boolean): number {\n  return (tickWidth ?? AXIS_TICK_WIDTH) + (titled ? AXIS_TITLE_STRIP : 0);\n}\n\n/**\n * The colour an axis TITLE takes, or `undefined` for the neutral one.\n *\n * An axis measuring exactly one line is that line's, and saying so in the title lets a\n * reader find a channel's scale without counting axes. An axis measuring several is\n * nobody's — a title in the first one's colour would be claiming it. Counted off the\n * series, so toggling a second line onto an axis gives the colour up in the same render.\n */\nexport function soleSeriesColor(\n  axis: Pick<SeriesChartAxisShape, \"id\" | \"color\">,\n  series: readonly Pick<SeriesChartSeries, \"axis\">[],\n): string | undefined {\n  const mine = series.filter((entry) => (entry.axis ?? DEFAULT_Y_AXIS) === axis.id);\n  return mine.length === 1 ? axis.color : undefined;\n}\n\n/** The single-axis case, which is most charts. `width` is what the TICKS need;\n *  `orientation` is which side they stand on. */\nexport function oneAxis(\n  format: ((value: number) => string) | undefined,\n  title: string,\n  width?: number,\n  orientation?: \"left\" | \"right\",\n): SeriesChartAxis[] {\n  return [{ id: DEFAULT_Y_AXIS, format, title, width, orientation }];\n}\n\n/** One source's samples: an abscissa and the channels measured against it. */\nexport interface SeriesSource {\n  x: number[];\n  channels: Record<string, number[]>;\n}\n\n/**\n * Merge sources sampled on different grids into rows the chart can draw.\n *\n * Merged ON THE ABSCISSA VALUE ITSELF, never interpolated onto a common grid: a line\n * through invented points looks exactly like one through measured ones. Where a source\n * has no sample the key is absent, and `connectNulls` bridges the hole with the same\n * straight segment an interpolation would have drawn — without claiming a measurement.\n */\nexport function mergeSeries(sources: SeriesSource[]): Record<string, number>[] {\n  const byAbscissa = new Map<number, Record<string, number>>();\n  for (const source of sources) {\n    source.x.forEach((value, index) => {\n      const row = byAbscissa.get(value) ?? { x: value };\n      for (const [key, channel] of Object.entries(source.channels)) row[key] = channel[index];\n      byAbscissa.set(value, row);\n    });\n  }\n  return [...byAbscissa.values()].sort((a, b) => a.x - b.x);\n}\n\n/**\n * A series key built out of parts — as a CSS identifier.\n *\n * The chart shell paints each series through `--color-<key>`, and skips (with a\n * console warning) any key that is not `[A-Za-z_][A-Za-z0-9_-]*`. A line whose colour\n * was skipped has no stroke at all: an axis, a grid and nothing between them. So a key\n * assembled out of DATA — an id, an enum, a side — goes through here: every other\n * character becomes `_`, the parts are joined with `_`, and a key that would start with\n * a digit or a hyphen gets a leading `_`.\n */\nexport function seriesKey(...parts: (string | number)[]): string {\n  const key = parts.map((part) => String(part).replace(/[^A-Za-z0-9_-]/g, \"_\")).join(\"_\");\n  return /^[A-Za-z_]/.test(key) ? key : `_${key}`;\n}\n\n/** The number format every default falls back to. */\nfunction useDefaultFormat(localeProp: string | undefined): (value: number) => string {\n  const locale = useKitLocale(localeProp);\n  return useMemo(() => {\n    const format = new Intl.NumberFormat(locale, { maximumFractionDigits: 2 });\n    return (value: number) => format.format(value);\n  }, [locale]);\n}\n\n/** The Y-axis list a chart draws when the caller gave none. */\nconst ONE_UNTITLED_AXIS: SeriesChartAxis[] = [{ id: DEFAULT_Y_AXIS, title: \"\" }];\n\n/**\n * {@link SeriesChart} without the zoom: the same picture, no drag layer, no reset\n * button. For a thumbnail, a print view, or a chart the consumer wraps in its own\n * interaction.\n */\nexport function StaticSeriesChart({\n  rows,\n  x = {},\n  series,\n  axes = ONE_UNTITLED_AXIS,\n  valueFormat,\n  height = \"h-72\",\n  connectNulls,\n  empty,\n  animationMs = 0,\n  spans,\n  zoom,\n  labels: labelsProp,\n  locale,\n  className,\n}: SeriesChartProps) {\n  const labels = useKitLabels(\"seriesChart\", DEFAULT_SERIES_CHART_LABELS, labelsProp);\n  const number = useDefaultFormat(locale);\n\n  // The empty state takes the chart's own height and is centred in it: a chart that\n  // shrank to its \"nothing to draw\" sentence moved everything under it up the page\n  // the moment a legend entry was switched off.\n  if (!rows.length || !series.length) {\n    return (\n      <div className={cn(\"flex w-full items-center justify-center px-2 text-center\", height)}>\n        {empty !== undefined ? (\n          empty\n        ) : (\n          <p className=\"text-xs text-[var(--text-muted)]\">{labels.empty}</p>\n        )}\n      </div>\n    );\n  }\n\n  const xKey = x.key ?? \"x\";\n  const xFormat = x.format ?? number;\n  const config: ChartConfig = Object.fromEntries(\n    series.map((entry, index) => [\n      entry.key,\n      { label: entry.label, color: entry.color ?? paletteFor(index) },\n    ]),\n  );\n  const visible = axes.filter((axis) => !axis.hide);\n  // The grid hangs its horizontal rules off ONE y axis, and recharts looks for the one\n  // whose id is its own default (`0`). Every axis here is named, so without saying\n  // which, it finds none and draws no horizontal rules at all. The first visible axis,\n  // because those are the ticks a reader puts a ruler on.\n  const gridAxis = (visible[0] ?? axes[0])?.id ?? DEFAULT_Y_AXIS;\n  const onLeft = visible.some((axis) => (axis.orientation ?? \"left\") === \"left\");\n  const onRight = visible.some((axis) => axis.orientation === \"right\");\n  // The margins are what is left once the axes have their bands: an axis band IS the\n  // gutter on its side, so a margin beside one is a second gutter. What remains is the\n  // overhang of the first/last x tick where no y axis covers it.\n  const margin = {\n    top: 8,\n    right: onRight ? 0 : 10,\n    left: onLeft ? 0 : 10,\n    // Under the ticks, not under the whole axis: whatever comes next owns the gap.\n    bottom: x.title ? 18 : 2,\n  };\n\n  // Fitted with air around it, unless the reader has zoomed or the caller pinned it.\n  const fittedX = zoom?.xDomain ?? paddedDomain(rows.map((row) => row[xKey]));\n  const fittedY = (axis: SeriesChartAxis) =>\n    zoom?.yDomains[axis.id] ??\n    axis.domain ??\n    paddedDomain(\n      series\n        .filter((entry) => (entry.axis ?? DEFAULT_Y_AXIS) === axis.id)\n        .flatMap((entry) => rows.map((row) => row[entry.key])),\n    );\n\n  return (\n    <ChartContainer config={config} className={cn(\"w-full\", height, className)}>\n      <LineChart data={rows} margin={margin}>\n        {/* Both ways: a measurement plot is read by putting a ruler on it, and a\n            horizontal-only grid answers half of those questions. */}\n        <CartesianGrid yAxisId={gridAxis} />\n        <XAxis\n          dataKey={xKey}\n          // Numeric, not categorical: a measured sweep is unevenly spaced, and a\n          // category axis would straighten exactly the curvature the chart is for.\n          type=\"number\"\n          domain={fittedX ?? [\"dataMin\", \"dataMax\"]}\n          // Clip the lines to a zoom window instead of recharts widening it back out.\n          allowDataOverflow={zoom?.xDomain !== undefined}\n          tickLine={false}\n          axisLine={false}\n          minTickGap={32}\n          tick={x.ticks === false ? false : undefined}\n          // With neither ticks nor title there is nothing to reserve the band for, and\n          // recharts' own 30 px would leave a gap under every chart of a stack.\n          height={x.ticks === false && !x.title ? 4 : undefined}\n          tickFormatter={xFormat}\n        >\n          {x.title && (\n            <Label\n              value={x.title}\n              position=\"insideBottom\"\n              offset={-12}\n              className=\"fill-[var(--text-muted)] text-[11px]\"\n            />\n          )}\n        </XAxis>\n        {axes.map((axis) => (\n          <YAxis\n            key={axis.id}\n            yAxisId={axis.id}\n            hide={axis.hide}\n            domain={fittedY(axis)}\n            allowDataOverflow={zoom?.yDomains[axis.id] !== undefined}\n            orientation={axis.orientation ?? \"left\"}\n            width={axisBandWidth(axis.width, Boolean(axis.title) && !axis.hide)}\n            tickLine={false}\n            axisLine={false}\n            tickFormatter={axis.format ?? number}\n            // With an axis per channel the tint is the only thing saying which\n            // numbers belong to which line.\n            tick={axis.color ? { fill: axis.color } : undefined}\n          >\n            {axis.title && !axis.hide && (\n              <Label\n                value={axis.title}\n                // Rotated so both sides read upward from the bottom of their axis.\n                angle={axis.orientation === \"right\" ? 90 : -90}\n                position={axis.orientation === \"right\" ? \"insideRight\" : \"insideLeft\"}\n                // Inline, so a sole series' colour beats the class's neutral fill —\n                // and absent for a shared axis, so the class draws it.\n                style={{ textAnchor: \"middle\", fill: soleSeriesColor(axis, series) }}\n                offset={AXIS_TITLE_OFFSET}\n                className=\"fill-[var(--text-muted)] text-[11px]\"\n              />\n            )}\n          </YAxis>\n        ))}\n        <ChartTooltip\n          content={\n            <ChartTooltipContent\n              labelFormatter={(value) => (x.label ?? xFormat)(Number(value))}\n              valueFormatter={valueFormat ?? number}\n            />\n          }\n        />\n        {series.map((entry) => (\n          <Line\n            key={entry.key}\n            yAxisId={entry.axis ?? DEFAULT_Y_AXIS}\n            type={entry.step ? \"stepAfter\" : \"monotone\"}\n            dataKey={entry.key}\n            stroke={`var(--color-${entry.key})`}\n            strokeWidth={entry.step ? 1.5 : 2}\n            strokeDasharray={strokeDash(\n              entry.step ? STEP_DASH : (entry.dash ?? (entry.dashed ? 1 : 0)),\n            )}\n            dot={false}\n            connectNulls={connectNulls}\n            isAnimationActive={animationMs > 0}\n            animationDuration={animationMs}\n            animationEasing=\"ease-out\"\n          />\n        ))}\n        {spans?.map((span) => (\n          <ReferenceLine\n            key={span.key}\n            yAxisId={span.axis ?? DEFAULT_Y_AXIS}\n            segment={[\n              { x: span.x, y: span.from },\n              { x: span.x, y: span.to },\n            ]}\n            stroke={span.color ?? \"var(--text-muted)\"}\n            strokeWidth={2}\n            // Discarded rather than clamped when zoomed past: a span clamped to the\n            // window's edge draws a vertical line at an abscissa it never stood at.\n            ifOverflow=\"discard\"\n          />\n        ))}\n        {zoom?.layer}\n      </LineChart>\n    </ChartContainer>\n  );\n}\n\n/**\n * The series chart, zoomable. Drag across the plot to zoom (the drag's shape picks the\n * axes), double-click or press the reset button to go back; wrap several in\n * `SharedXZoom` to move their x windows together.\n */\nexport const SeriesChart = withChartZoom(StaticSeriesChart);\n"],"mappings":"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","names":[]}

package/dist/components/settings-fields.d.ts

@@ -1,5 +1,6 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
+import { SelectProps } from './ui.js';
 import { ThemePreference } from '../theme/theme-store.js';
 import 'zustand/middleware';
 import 'zustand';
@@ -11,7 +12,14 @@ import 'zustand';
  * The app owns WHERE these render (its own settings page) and any app-specific
  * fields around them.
  */
-interface ThemeSettingProps {
+/**
+ * Everything a {@link Select} takes, minus the two this component owns: the value is a
+ * {@link ThemePreference} rather than a string, and `onChange` hands over the preference
+ * itself because no caller of this wants the event. The rest — `disabled`, `required`,
+ * `invalid`, `error`, a `data-tour` anchor — passes straight through, which is what makes
+ * this a settings FIELD rather than a fixed widget.
+ */
+interface ThemeSettingProps extends Omit<SelectProps, "value" | "onChange" | "children"> {
     value: ThemePreference;
     onChange: (value: ThemePreference) => void;
     label: ReactNode;
@@ -23,8 +31,10 @@ interface ThemeSettingProps {
     };
     id?: string;
 }
-declare function ThemeSetting({ value, onChange, label, optionLabels, id }: ThemeSettingProps): react.JSX.Element;
-interface LanguageSettingProps {
+declare function ThemeSetting({ value, onChange, label, optionLabels, id, ...rest }: ThemeSettingProps): react.JSX.Element;
+/** See {@link ThemeSettingProps}: a `Select`'s props with the value and the change
+ *  handler re-typed to the language CODE the caller stores. */
+interface LanguageSettingProps extends Omit<SelectProps, "value" | "onChange" | "children"> {
     value: string;
     onChange: (code: string) => void;
     label: ReactNode;
@@ -34,6 +44,6 @@ interface LanguageSettingProps {
     }[];
     id?: string;
 }
-declare function LanguageSetting({ value, onChange, label, options, id }: LanguageSettingProps): react.JSX.Element;
+declare function LanguageSetting({ value, onChange, label, options, id, ...rest }: LanguageSettingProps): react.JSX.Element;
 
 export { LanguageSetting, type LanguageSettingProps, ThemeSetting, type ThemeSettingProps };

package/dist/components/settings-fields.js

@@ -1,14 +1,25 @@
+"use client";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { Select } from "./ui.js";
-function ThemeSetting({ value, onChange, label, optionLabels, id }) {
-  return /* @__PURE__ */ jsxs(Select, { id, label, value, onChange: (e) => onChange(e.target.value), children: [
-    /* @__PURE__ */ jsx("option", { value: "system", children: optionLabels.system }),
-    /* @__PURE__ */ jsx("option", { value: "light", children: optionLabels.light }),
-    /* @__PURE__ */ jsx("option", { value: "dark", children: optionLabels.dark })
-  ] });
+function ThemeSetting({ value, onChange, label, optionLabels, id, ...rest }) {
+  return /* @__PURE__ */ jsxs(
+    Select,
+    {
+      ...rest,
+      id,
+      label,
+      value,
+      onChange: (e) => onChange(e.target.value),
+      children: [
+        /* @__PURE__ */ jsx("option", { value: "system", children: optionLabels.system }),
+        /* @__PURE__ */ jsx("option", { value: "light", children: optionLabels.light }),
+        /* @__PURE__ */ jsx("option", { value: "dark", children: optionLabels.dark })
+      ]
+    }
+  );
 }
-function LanguageSetting({ value, onChange, label, options, id }) {
-  return /* @__PURE__ */ jsx(Select, { id, label, value, onChange: (e) => onChange(e.target.value), children: options.map((o) => /* @__PURE__ */ jsx("option", { value: o.code, children: o.label }, o.code)) });
+function LanguageSetting({ value, onChange, label, options, id, ...rest }) {
+  return /* @__PURE__ */ jsx(Select, { ...rest, id, label, value, onChange: (e) => onChange(e.target.value), children: options.map((o) => /* @__PURE__ */ jsx("option", { value: o.code, children: o.label }, o.code)) });
 }
 export {
   LanguageSetting,

package/dist/components/settings-fields.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/settings-fields.tsx"],"sourcesContent":["import type { ReactNode } from \"react\";\nimport { Select } from \"./ui\";\nimport type { ThemePreference } from \"../theme/theme-store\";\n\n/**\n * App-agnostic settings-field components (feedback #333): the language + theme\n * controls that every app's settings page needs, so they live in @hb/ui and the\n * app just supplies the current value, a change handler and translated labels.\n * The app owns WHERE these render (its own settings page) and any app-specific\n * fields around them.\n */\n\nexport interface ThemeSettingProps {\n  value: ThemePreference;\n  onChange: (value: ThemePreference) => void;\n  label: ReactNode;\n  /** Translated option labels. */\n  optionLabels: { system: string; light: string; dark: string };\n  id?: string;\n}\n\nexport function ThemeSetting({ value, onChange, label, optionLabels, id }: ThemeSettingProps) {\n  return (\n    <Select id={id} label={label} value={value} onChange={(e) => onChange(e.target.value as ThemePreference)}>\n      <option value=\"system\">{optionLabels.system}</option>\n      <option value=\"light\">{optionLabels.light}</option>\n      <option value=\"dark\">{optionLabels.dark}</option>\n    </Select>\n  );\n}\n\nexport interface LanguageSettingProps {\n  value: string;\n  onChange: (code: string) => void;\n  label: ReactNode;\n  options: { code: string; label: string }[];\n  id?: string;\n}\n\nexport function LanguageSetting({ value, onChange, label, options, id }: LanguageSettingProps) {\n  return (\n    <Select id={id} label={label} value={value} onChange={(e) => onChange(e.target.value)}>\n      {options.map((o) => (\n        <option key={o.code} value={o.code}>\n          {o.label}\n        </option>\n      ))}\n    </Select>\n  );\n}\n"],"mappings":"AAuBI,SACE,KADF;AAtBJ,SAAS,cAAc;AAoBhB,SAAS,aAAa,EAAE,OAAO,UAAU,OAAO,cAAc,GAAG,GAAsB;AAC5F,SACE,qBAAC,UAAO,IAAQ,OAAc,OAAc,UAAU,CAAC,MAAM,SAAS,EAAE,OAAO,KAAwB,GACrG;AAAA,wBAAC,YAAO,OAAM,UAAU,uBAAa,QAAO;AAAA,IAC5C,oBAAC,YAAO,OAAM,SAAS,uBAAa,OAAM;AAAA,IAC1C,oBAAC,YAAO,OAAM,QAAQ,uBAAa,MAAK;AAAA,KAC1C;AAEJ;AAUO,SAAS,gBAAgB,EAAE,OAAO,UAAU,OAAO,SAAS,GAAG,GAAyB;AAC7F,SACE,oBAAC,UAAO,IAAQ,OAAc,OAAc,UAAU,CAAC,MAAM,SAAS,EAAE,OAAO,KAAK,GACjF,kBAAQ,IAAI,CAAC,MACZ,oBAAC,YAAoB,OAAO,EAAE,MAC3B,YAAE,SADQ,EAAE,IAEf,CACD,GACH;AAEJ;","names":[]}
+{"version":3,"sources":["../../src/components/settings-fields.tsx"],"sourcesContent":["import type { ReactNode } from \"react\";\nimport { Select } from \"./ui\";\nimport type { SelectProps } from \"./ui\";\nimport type { ThemePreference } from \"../theme/theme-store\";\n\n/**\n * App-agnostic settings-field components (feedback #333): the language + theme\n * controls that every app's settings page needs, so they live in @hb/ui and the\n * app just supplies the current value, a change handler and translated labels.\n * The app owns WHERE these render (its own settings page) and any app-specific\n * fields around them.\n */\n\n/**\n * Everything a {@link Select} takes, minus the two this component owns: the value is a\n * {@link ThemePreference} rather than a string, and `onChange` hands over the preference\n * itself because no caller of this wants the event. The rest — `disabled`, `required`,\n * `invalid`, `error`, a `data-tour` anchor — passes straight through, which is what makes\n * this a settings FIELD rather than a fixed widget.\n */\nexport interface ThemeSettingProps\n  extends Omit<SelectProps, \"value\" | \"onChange\" | \"children\"> {\n  value: ThemePreference;\n  onChange: (value: ThemePreference) => void;\n  label: ReactNode;\n  /** Translated option labels. */\n  optionLabels: { system: string; light: string; dark: string };\n  id?: string;\n}\n\nexport function ThemeSetting({ value, onChange, label, optionLabels, id, ...rest }: ThemeSettingProps) {\n  return (\n    <Select\n      {...rest}\n      id={id}\n      label={label}\n      value={value}\n      onChange={(e) => onChange(e.target.value as ThemePreference)}\n    >\n      <option value=\"system\">{optionLabels.system}</option>\n      <option value=\"light\">{optionLabels.light}</option>\n      <option value=\"dark\">{optionLabels.dark}</option>\n    </Select>\n  );\n}\n\n/** See {@link ThemeSettingProps}: a `Select`'s props with the value and the change\n *  handler re-typed to the language CODE the caller stores. */\nexport interface LanguageSettingProps\n  extends Omit<SelectProps, \"value\" | \"onChange\" | \"children\"> {\n  value: string;\n  onChange: (code: string) => void;\n  label: ReactNode;\n  options: { code: string; label: string }[];\n  id?: string;\n}\n\nexport function LanguageSetting({ value, onChange, label, options, id, ...rest }: LanguageSettingProps) {\n  return (\n    <Select {...rest} id={id} label={label} value={value} onChange={(e) => onChange(e.target.value)}>\n      {options.map((o) => (\n        <option key={o.code} value={o.code}>\n          {o.label}\n        </option>\n      ))}\n    </Select>\n  );\n}\n"],"mappings":";AAgCI,SAOE,KAPF;AA/BJ,SAAS,cAAc;AA6BhB,SAAS,aAAa,EAAE,OAAO,UAAU,OAAO,cAAc,IAAI,GAAG,KAAK,GAAsB;AACrG,SACE;AAAA,IAAC;AAAA;AAAA,MACE,GAAG;AAAA,MACJ;AAAA,MACA;AAAA,MACA;AAAA,MACA,UAAU,CAAC,MAAM,SAAS,EAAE,OAAO,KAAwB;AAAA,MAE3D;AAAA,4BAAC,YAAO,OAAM,UAAU,uBAAa,QAAO;AAAA,QAC5C,oBAAC,YAAO,OAAM,SAAS,uBAAa,OAAM;AAAA,QAC1C,oBAAC,YAAO,OAAM,QAAQ,uBAAa,MAAK;AAAA;AAAA;AAAA,EAC1C;AAEJ;AAaO,SAAS,gBAAgB,EAAE,OAAO,UAAU,OAAO,SAAS,IAAI,GAAG,KAAK,GAAyB;AACtG,SACE,oBAAC,UAAQ,GAAG,MAAM,IAAQ,OAAc,OAAc,UAAU,CAAC,MAAM,SAAS,EAAE,OAAO,KAAK,GAC3F,kBAAQ,IAAI,CAAC,MACZ,oBAAC,YAAoB,OAAO,EAAE,MAC3B,YAAE,SADQ,EAAE,IAEf,CACD,GACH;AAEJ;","names":[]}

package/dist/components/signature-pad.d.ts

@@ -0,0 +1,119 @@
+import * as react from 'react';
+import { ComponentPropsWithoutRef, ReactNode } from 'react';
+
+/**
+ * A drawn signature, captured on a canvas and handed back as a PNG data URL.
+ *
+ * Kastlan wrote the first one (`features/handover/components/signature-pad.tsx`) for
+ * the handover protocol, where tenant and inspector each sign on the same phone. This
+ * keeps its contract — draw, get a PNG — and fixes what a copy per app would keep
+ * getting wrong:
+ *
+ *  1. **Strokes are data, not pixels.** Each stroke is kept as a list of points, and
+ *     the canvas is a VIEW of them. That is what lets a resize (a phone rotating
+ *     mid-signature) keep the drawing instead of wiping it — setting `canvas.width`
+ *     clears the bitmap, so a pixels-only pad loses everything — and what makes undo
+ *     one `pop()`. The pixel buffer is sized to `devicePixelRatio`, so a stroke is
+ *     sharp on a 3× screen rather than upscaled from a 1× bitmap.
+ *  2. **Smooth, and pressure-aware.** Segments are quadratic curves through the
+ *     midpoints between samples, so a fast stroke is a curve, not a polyline; a pen
+ *     that reports pressure varies the width, a mouse or finger (whose `pressure` is a
+ *     constant 0.5, or junk) draws at the base width.
+ *  3. **Two inks.** On screen the ink is the computed `color` of the canvas, which is
+ *     `--text-primary` — so it reads in the dark theme, where a hard-coded near-black
+ *     stroke vanished into the surface. The exported PNG is re-rendered from the same
+ *     strokes in `exportInk` (near-black by default) on a transparent background. A
+ *     signature is a DOCUMENT artefact: it is printed on the protocol, shown on a white
+ *     card, embedded in a PDF — none of which follow the signer's theme. Exporting
+ *     the on-screen ink would have produced a pale-grey-on-transparent PNG for every
+ *     dark-mode signer, invisible on white paper.
+ *
+ * **Accessibility.** A canvas has no content a screen reader or a keyboard can reach,
+ * and no amount of ARIA changes that — drawing is a pointer act. What the pad does:
+ * the canvas is `role="img"`, named by the visible label and described by the
+ * instructions and by its state ("Nothing drawn yet" / "Signature drawn"), so a
+ * screen-reader user knows what the box is and whether it holds anything; undo and
+ * clear are real buttons, and their effect is announced. What it cannot do is let
+ * someone sign without a pointer — hence `allowTypedName`, which offers a typed name
+ * instead. It is OPT-IN, because whether a typed name counts as a signature is a
+ * product and legal decision, not a UI one (Kastlan's handover accepts one; a flow
+ * that needs a drawn mark would not). Where a drawn mark is not strictly required,
+ * turn it on.
+ */
+/** Every string the pad renders or speaks. */
+interface SignaturePadLabels {
+    /** Visible label above the pad, and the canvas's accessible name. The `label`
+     *  prop overrides it per instance. */
+    label: string;
+    /** Under the label, and part of the canvas's description. */
+    instructions: string;
+    /** Appended to the instructions when `allowTypedName` is on. */
+    typedFallbackHint: string;
+    /** The canvas's state for a screen reader. */
+    empty: string;
+    signed: string;
+    undo: string;
+    clear: string;
+    /** Only rendered when `onSave` is given. */
+    save: string;
+    /** The mode switch (`allowTypedName`). */
+    useTyped: string;
+    useDrawn: string;
+    /** Label of the typed-name field. */
+    typedName: string;
+    /** Live-region messages after the matching button. */
+    cleared: string;
+    undone: string;
+}
+declare const DEFAULT_SIGNATURE_PAD_LABELS: SignaturePadLabels;
+/** How the value handed back was made. */
+interface SignatureDetail {
+    method: "drawn" | "typed";
+    /** The name as typed, when `method` is `"typed"` — the PNG shows it, but a host
+     *  that stores a typed name as TEXT (Kastlan does) wants the string. */
+    typedName?: string;
+}
+/** The imperative handle: `ref.current.toDataURL()` at submit time, for a form that
+ *  does not want to mirror the value into state on every stroke. */
+interface SignaturePadHandle {
+    /** Remove every stroke and the typed name. Fires `onChange(null)`. */
+    clear: () => void;
+    /** The PNG, rendered in `exportInk` — or `null` while nothing is signed. */
+    toDataURL: () => string | null;
+    isEmpty: () => boolean;
+}
+interface SignaturePadProps extends Omit<ComponentPropsWithoutRef<"div">, "onChange"> {
+    /** Visible label; defaults to `labels.label`. */
+    label?: ReactNode;
+    /** Replaces `labels.instructions` for this instance (e.g. a legal note). */
+    description?: ReactNode;
+    /**
+     * After every finished stroke, undo, clear and typed-name edit: the PNG, or `null`
+     * once the pad is empty. Not called mid-stroke — encoding a PNG per pointer move
+     * would stall the drawing on a phone.
+     */
+    onChange?: (dataUrl: string | null, detail: SignatureDetail) => void;
+    /** Renders a Save button, enabled once something is signed. */
+    onSave?: (dataUrl: string, detail: SignatureDetail) => void;
+    disabled?: boolean;
+    /** Paints the pad as wrong and sets `aria-invalid`. See {@link Input}'s `invalid`. */
+    invalid?: boolean;
+    /** Message under the pad; implies `invalid` and is attached with
+     *  `aria-describedby`, like the kit's other fields. */
+    error?: ReactNode;
+    /** Offer a typed name as an alternative to drawing. See the accessibility note. */
+    allowTypedName?: boolean;
+    /** Ink of the exported PNG. Default near-black, legible on white. */
+    exportInk?: string;
+    /** Fill behind the exported PNG. Default transparent. */
+    exportBackground?: string;
+    /** Base stroke width in CSS pixels. Default 2.5. */
+    lineWidth?: number;
+    /** Classes for the canvas — its height, chiefly (default `h-40`). */
+    canvasClassName?: string;
+    /** User-facing strings; see {@link SignaturePadLabels}. */
+    labels?: Partial<SignaturePadLabels>;
+}
+declare const SignaturePad: react.ForwardRefExoticComponent<SignaturePadProps & react.RefAttributes<SignaturePadHandle>>;
+
+export { DEFAULT_SIGNATURE_PAD_LABELS, type SignatureDetail, SignaturePad, type SignaturePadHandle, type SignaturePadLabels, type SignaturePadProps };