@ultimat3/ui 29.4.0 → 30.0.0

package/src/components/bar-chart-view.ts

@@ -1,15 +1,20 @@
 // The geometry of a BarChart, apart from its markup: where each bar sits, how tall it is, where
-// the grid lines fall. Pure, so the server render and a hydrated one cannot draw two charts.
+// zero and the grid lines fall. Signed: a negative bar hangs below a real zero line, `null` is no
+// bar at all, and zero is a 2px stub on the line — three different marks for three facts.
+
+import type { ChartSeries } from './chart-frame-view';
+import { finiteOrNull } from './chart-frame-view';
 
 export interface ChartPoint {
   /** The bar's name — a day, a bucket, a label. Read by `<title>` and the axis. */
   readonly key: string;
-  readonly value: number;
+  /** `null` is unknown: no bar, and the table says so. Never zero-fill a gap. */
+  readonly value: number | null;
   /**
    * A second series, stacked on `value` — failed on top of done. Absent or 0 draws nothing, so a
    * one-series chart is exactly the chart it was.
    */
-  readonly secondary?: number;
+  readonly secondary?: number | undefined;
 }
 
 export interface BarRect {
@@ -30,57 +35,134 @@ export const BAR_CHART = { width: 600, top: 2, plot: 104, height: 108, gap: 3 }
 /** Quarter lines. Four is what a reader can use to judge a bar's height without a y-axis. */
 export const GRID_STEPS = [0.25, 0.5, 0.75, 1] as const;
 
-const finite = (value: number | undefined): number =>
-  value !== undefined && Number.isFinite(value) ? Math.max(0, value) : 0;
+/** The shortest mark a known value draws: a zero is still visibly there, unlike a gap. */
+const STUB = 2;
+
+/** The value range the plot spans: always through zero, never empty, so it always divides. */
+export interface BarExtent {
+  readonly min: number;
+  readonly max: number;
+}
+
+const positive = (value: number | null | undefined): number =>
+  Math.max(0, finiteOrNull(value) ?? 0);
+
+/** Folds `also` (reference values) into a range, keeping it non-empty. */
+function widened(min: number, max: number, also: readonly number[]): BarExtent {
+  const lo = Math.min(min, ...also);
+  const hi = Math.max(max, ...also);
+  return hi === lo ? { min: lo, max: lo + 1 } : { min: lo, max: hi };
+}
 
-/** The busiest point — its whole stack — and never below 1, so an all-zero series still divides. */
-export function maxOf(points: readonly ChartPoint[]): number {
-  let max = 1;
+/**
+ * The lowest and highest point — a stack's whole height — always including zero, and any
+ * reference value in `also`, so a target above every bar is still on the plot.
+ */
+export function barExtent(points: readonly ChartPoint[], also: readonly number[] = []): BarExtent {
+  let min = 0;
+  let max = 0;
   for (const point of points) {
-    const total = finite(point.value) + finite(point.secondary);
-    if (total > max) max = total;
+    const value = finiteOrNull(point.value);
+    if (value !== null && value < 0) min = Math.min(min, value);
+    max = Math.max(max, positive(value) + positive(point.secondary));
+  }
+  return widened(min, max, also);
+}
+
+/** The same over an n-series chart's every value. */
+export function seriesExtent(
+  series: readonly ChartSeries[],
+  also: readonly number[] = [],
+): BarExtent {
+  let min = 0;
+  let max = 0;
+  for (const one of series) {
+    for (const raw of one.values) {
+      const value = finiteOrNull(raw);
+      if (value === null) continue;
+      min = Math.min(min, value);
+      max = Math.max(max, value);
+    }
   }
-  return max;
+  return widened(min, max, also);
 }
 
-/** The y of a grid line at `step` of the plot height (1 = the top line = the busiest point). */
+/** The y of `value` in the plot. */
+export function valueY(value: number, extent: BarExtent): number {
+  return BAR_CHART.top + ((extent.max - value) / (extent.max - extent.min)) * BAR_CHART.plot;
+}
+
+/** The y of the zero line — the plot's floor for an all-positive chart. */
+export function zeroY(extent: BarExtent): number {
+  return valueY(0, extent);
+}
+
+/** The y of a grid line at `step` of the plot height (1 = the top line). */
 export function gridY(step: number): number {
   return BAR_CHART.top + BAR_CHART.plot - step * BAR_CHART.plot;
 }
 
-/** One rect per point, oldest first. At least 2px tall so a zero still draws a visible bar. */
-export function barRects(points: readonly ChartPoint[]): readonly BarRect[] {
-  const count = Math.max(points.length, 1);
-  // The gap gives way before the bars do: at most half of each bar's slot, so past the 201 points
-  // where 3px gaps alone fill the width, every bar is still a positive rect and the row still ends
-  // at the right edge.
-  const gap = Math.min(BAR_CHART.gap, BAR_CHART.width / count / 2);
-  const width = (BAR_CHART.width - gap * (count - 1)) / count;
-  const max = maxOf(points);
+/** `count` slots across the width: the gap gives way before the bars do, at most half a slot. */
+function slots(count: number): { readonly width: number; readonly gap: number } {
+  const n = Math.max(count, 1);
+  const gap = Math.min(BAR_CHART.gap, BAR_CHART.width / n / 2);
+  return { width: (BAR_CHART.width - gap * (n - 1)) / n, gap };
+}
+
+/** A bar from zero to `value` at `x`: up for a positive, down for a negative, a stub for zero. */
+function barAt(x: number, width: number, value: number, extent: BarExtent): BarRect {
+  const zero = zeroY(extent);
+  const height = Math.max(STUB, Math.abs(valueY(value, extent) - zero));
+  return { x, y: value < 0 ? zero : zero - height, width, height };
+}
+
+/** One rect per point, oldest first; `null` where the value is unknown. */
+export function barRects(
+  points: readonly ChartPoint[],
+  extent: BarExtent = barExtent(points),
+): readonly (BarRect | null)[] {
+  const { width, gap } = slots(points.length);
   return points.map((point, index) => {
-    const value = Number.isFinite(point.value) ? Math.max(0, point.value) : 0;
-    const height = Math.max(2, (value / max) * BAR_CHART.plot);
-    return {
-      x: index * (width + gap),
-      y: BAR_CHART.top + BAR_CHART.plot - height,
-      width,
-      height,
-    };
+    const value = finiteOrNull(point.value);
+    return value === null ? null : barAt(index * (width + gap), width, value, extent);
   });
 }
 
 /**
- * The second series' rect per point, stacked on that point's primary bar; `null` where it is 0.
- * Same scale as `barRects`, so a stack is read against the same grid lines.
+ * The second series' rect per point, stacked on the positive part of that point's bar (or on the
+ * zero line); `null` where it is 0. Same scale as `barRects`, read against the same grid.
  */
-export function secondaryRects(points: readonly ChartPoint[]): readonly (BarRect | null)[] {
-  const primary = barRects(points);
-  const max = maxOf(points);
+export function secondaryRects(
+  points: readonly ChartPoint[],
+  extent: BarExtent = barExtent(points),
+): readonly (BarRect | null)[] {
+  const { width, gap } = slots(points.length);
   return points.map((point, index) => {
-    const value = finite(point.secondary);
-    const below = primary[index];
-    if (value === 0 || below === undefined) return null;
-    const height = (value / max) * BAR_CHART.plot;
-    return { x: below.x, y: below.y - height, width: below.width, height };
+    const value = positive(point.secondary);
+    if (value === 0) return null;
+    const base = valueY(positive(point.value), extent);
+    const top = valueY(positive(point.value) + value, extent);
+    return { x: index * (width + gap), y: top, width, height: base - top };
   });
 }
+
+/**
+ * n series over shared keys, side by side within each key's slot — every bar signed on its own,
+ * so a negative in one series never hides another. `[series][key]`, `null` for a gap.
+ */
+export function groupedBarRects(
+  keyCount: number,
+  series: readonly ChartSeries[],
+  extent: BarExtent = seriesExtent(series),
+): readonly (readonly (BarRect | null)[])[] {
+  const slot = slots(keyCount);
+  const inner = Math.min(1, slot.width / Math.max(series.length, 1) / 4);
+  const width = (slot.width - inner * (series.length - 1)) / Math.max(series.length, 1);
+  return series.map((one, s) =>
+    Array.from({ length: keyCount }, (_, k) => {
+      const value = finiteOrNull(one.values[k]);
+      const x = k * (slot.width + slot.gap) + s * (width + inner);
+      return value === null ? null : barAt(x, width, value, extent);
+    }),
+  );
+}

package/src/components/board-view.ts

@@ -0,0 +1,25 @@
+// A board's columns, checked: column ids unique (a move names one) and card keys unique across
+// every column (a card is one node). Refused as X_UI_INVALID_VALUE naming the id.
+
+import { type SortGroup, sortPositions } from '../drag/sort-view';
+import { invalidValueError } from '../errors';
+
+export interface BoardGroupInput<T> {
+  readonly id: string;
+  readonly label: string;
+  readonly items: readonly T[];
+}
+
+export function boardGroups<T, G extends BoardGroupInput<T>>(
+  groups: readonly G[],
+  itemKey: (item: T) => string,
+): readonly G[] {
+  const seen = new Set<string>();
+  for (const group of groups) {
+    if (seen.has(group.id))
+      throw invalidValueError('Board', group.id, 'a column id unique on the board');
+    seen.add(group.id);
+  }
+  sortPositions(groups as readonly SortGroup<T>[], itemKey);
+  return groups;
+}

package/src/components/bottom-nav-view.ts

@@ -0,0 +1,18 @@
+// The bottom bar's one rule beyond `currentOf`: five destinations at most. A sixth no longer fits
+// a 320px phone at a touch target each, and the thumb cannot reach a scroll it cannot see.
+
+import { invalidValueError } from '../errors';
+
+export const BOTTOM_NAV_MAX = 5;
+
+/** `items` unchanged, or `X_UI_INVALID_VALUE` naming the count when there are more than five. */
+export function bottomNavItems<T>(items: readonly T[]): readonly T[] {
+  if (items.length > BOTTOM_NAV_MAX) {
+    throw invalidValueError(
+      'BottomNav',
+      `${items.length} items`,
+      `at most ${BOTTOM_NAV_MAX} destinations — move the rest into AppShell's sidebar (NavList)`,
+    );
+  }
+  return items;
+}

package/src/components/calendar-view.ts

@@ -0,0 +1,226 @@
+// A month as a grid of `PlainDate`s, and every rule a calendar keys on: week start from the
+// locale, 6 rows always so the box never jumps, the arrow step (flipped by `dir`, skipping what is
+// disabled), and the one day holding the tab stop. Pure, over `@ultimat3/time`'s plain dates.
+
+import { cachedFormatter } from '@ultimat3/core';
+import {
+  addPlainDays,
+  addPlainMonths,
+  comparePlainDates,
+  isPlainDate,
+  type PlainDate,
+  plainDateOf,
+  plainDateParts,
+  plainDateToUtcInstant,
+} from '@ultimat3/time';
+import { invalidValueError } from '../errors';
+
+/** ISO weekday: 1 is Monday, 7 is Sunday — `Intl.Locale#getWeekInfo().firstDay`'s numbering. */
+export type Weekday = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+
+export interface CalendarBounds {
+  readonly min?: PlainDate | undefined;
+  readonly max?: PlainDate | undefined;
+  readonly isDisabled?: ((date: PlainDate) => boolean) | undefined;
+}
+
+export interface CalendarDay {
+  readonly date: PlainDate;
+  readonly day: number;
+  /** In the month shown; the others pad the grid to whole weeks. */
+  readonly inMonth: boolean;
+  readonly disabled: boolean;
+}
+
+const WEEKS = 6;
+/** How far an arrow keeps stepping over disabled days before it gives up and stays put. */
+const MAX_SKIP = 366;
+
+/** `value` as a `PlainDate`, or `X_UI_INVALID_VALUE` naming the prop. */
+export function plainDateProp(prop: string, value: unknown): PlainDate {
+  if (!isPlainDate(value)) throw invalidValueError(prop, value, 'a YYYY-MM-DD calendar date');
+  return value;
+}
+
+/** An optional date prop: absent or empty is no date, anything else must be a `PlainDate`. */
+export const optionalDateProp = (prop: string, value: string | undefined): PlainDate | undefined =>
+  value === undefined || value === '' ? undefined : plainDateProp(prop, value);
+
+/** `min` after `max` leaves no day to pick: refused, naming both. */
+export function assertBounds(component: string, bounds: CalendarBounds): void {
+  const { min, max } = bounds;
+  if (min !== undefined) plainDateProp(`${component} min`, min);
+  if (max !== undefined) plainDateProp(`${component} max`, max);
+  if (min !== undefined && max !== undefined && comparePlainDates(min, max) > 0) {
+    throw invalidValueError(
+      `${component} min`,
+      `${min} after max ${max}`,
+      'a min on or before max',
+    );
+  }
+}
+
+interface WeekInfoLocale {
+  getWeekInfo?: () => { readonly firstDay?: number };
+  readonly weekInfo?: { readonly firstDay?: number };
+}
+
+const isWeekday = (value: unknown): value is Weekday =>
+  typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= 7;
+
+/**
+ * The locale's first day of the week, from the platform (`en-US` Sunday, `de` Monday), so no table
+ * ships. `override` wins; an engine without `getWeekInfo` falls back to ISO Monday.
+ */
+export function weekStartOf(locale: string, override?: Weekday | undefined): Weekday {
+  if (override !== undefined) {
+    if (!isWeekday(override))
+      throw invalidValueError('Calendar weekStart', override, 'a weekday 1–7');
+    return override;
+  }
+  const info = new Intl.Locale(locale) as unknown as WeekInfoLocale;
+  const firstDay = (info.getWeekInfo?.() ?? info.weekInfo)?.firstDay;
+  return isWeekday(firstDay) ? firstDay : 1;
+}
+
+/** The ISO weekday of a plain date. */
+export function weekdayOf(date: PlainDate): Weekday {
+  const sunday0 = plainDateToUtcInstant(date).getUTCDay();
+  return (sunday0 === 0 ? 7 : sunday0) as Weekday;
+}
+
+export const firstOfMonth = (date: PlainDate): PlainDate => {
+  const { year, month } = plainDateParts(date);
+  return plainDateOf({ year, month, day: 1 });
+};
+
+export function isDayDisabled(date: PlainDate, bounds: CalendarBounds): boolean {
+  if (bounds.min !== undefined && comparePlainDates(date, bounds.min) < 0) return true;
+  if (bounds.max !== undefined && comparePlainDates(date, bounds.max) > 0) return true;
+  return bounds.isDisabled?.(date) === true;
+}
+
+/** Six weeks starting on `weekStart`, around `month`'s first day. Always 42 days. */
+export function monthGrid(
+  month: PlainDate,
+  weekStart: Weekday,
+  bounds: CalendarBounds = {},
+): readonly (readonly CalendarDay[])[] {
+  const first = firstOfMonth(month);
+  const lead = (weekdayOf(first) - weekStart + 7) % 7;
+  const start = addPlainDays(first, -lead);
+  const shown = plainDateParts(first).month;
+  return Array.from({ length: WEEKS }, (_, week) =>
+    Array.from({ length: 7 }, (_, weekday) => {
+      const date = addPlainDays(start, week * 7 + weekday);
+      const parts = plainDateParts(date);
+      return {
+        date,
+        day: parts.day,
+        inMonth: parts.month === shown,
+        disabled: isDayDisabled(date, bounds),
+      };
+    }),
+  );
+}
+
+export interface StepOptions extends CalendarBounds {
+  readonly dir: 'ltr' | 'rtl';
+  readonly weekStart: Weekday;
+  readonly shiftKey?: boolean | undefined;
+}
+
+/** One key's move, ignoring what is disabled. `undefined` is a key the grid does not take. */
+function rawStep(from: PlainDate, key: string, options: StepOptions): PlainDate | undefined {
+  const forward = options.dir === 'rtl' ? 'ArrowLeft' : 'ArrowRight';
+  const back = options.dir === 'rtl' ? 'ArrowRight' : 'ArrowLeft';
+  const offset = (weekdayOf(from) - options.weekStart + 7) % 7;
+  switch (key) {
+    case forward:
+      return addPlainDays(from, 1);
+    case back:
+      return addPlainDays(from, -1);
+    case 'ArrowDown':
+      return addPlainDays(from, 7);
+    case 'ArrowUp':
+      return addPlainDays(from, -7);
+    case 'Home':
+      return addPlainDays(from, -offset);
+    case 'End':
+      return addPlainDays(from, 6 - offset);
+    case 'PageDown':
+      return addPlainMonths(from, options.shiftKey === true ? 12 : 1);
+    case 'PageUp':
+      return addPlainMonths(from, options.shiftKey === true ? -12 : -1);
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * The day a key lands on. A disabled day is stepped over one day at a time in the direction the
+ * key moved, so the roving stop never lands on a day that refuses focus. Stays put (`undefined`)
+ * when nothing reachable is left that way.
+ */
+export function stepDay(from: PlainDate, key: string, options: StepOptions): PlainDate | undefined {
+  let target = rawStep(from, key, options);
+  if (target === undefined) return undefined;
+  const ahead = comparePlainDates(target, from) > 0;
+  for (let skipped = 0; skipped < MAX_SKIP; skipped += 1) {
+    if (target === from) return undefined;
+    if (!isDayDisabled(target, options)) return target;
+    const outOfRange =
+      (ahead && options.max !== undefined && comparePlainDates(target, options.max) > 0) ||
+      (!ahead && options.min !== undefined && comparePlainDates(target, options.min) < 0);
+    if (outOfRange) return undefined;
+    target = addPlainDays(target, ahead ? 1 : -1);
+  }
+  return undefined;
+}
+
+/**
+ * The one day carrying `tabindex="0"`: the focused day, else the selected one, else the first
+ * enabled day of the month — each only when it is in the month shown and enabled. `undefined` when
+ * the whole month is disabled, and then nothing is tabbable, which is the correct answer.
+ */
+export function rovingDay(
+  grid: readonly (readonly CalendarDay[])[],
+  candidates: readonly (PlainDate | undefined)[],
+): PlainDate | undefined {
+  const days = grid.flat().filter((day) => day.inMonth && !day.disabled);
+  for (const candidate of candidates) {
+    if (candidate !== undefined && days.some((day) => day.date === candidate)) return candidate;
+  }
+  return days[0]?.date;
+}
+
+const formatters = new Map<string, Intl.DateTimeFormat>();
+/** `timeZone: 'UTC'` on a plain date's UTC midnight: the date named, never shifted by a zone. */
+const formatter = (locale: string, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat =>
+  cachedFormatter(
+    formatters,
+    `${locale}|${JSON.stringify(options)}`,
+    () => new Intl.DateTimeFormat(locale, { ...options, timeZone: 'UTC' }),
+  );
+
+export const monthLabel = (month: PlainDate, locale: string): string =>
+  formatter(locale, { month: 'long', year: 'numeric' }).format(plainDateToUtcInstant(month));
+
+export const dayLabel = (date: PlainDate, locale: string): string =>
+  formatter(locale, { dateStyle: 'full' }).format(plainDateToUtcInstant(date));
+
+/** Seven column headers from `weekStart`: the short name shown, the long one as `abbr`. */
+export function weekdayLabels(
+  locale: string,
+  weekStart: Weekday,
+): readonly { readonly short: string; readonly long: string }[] {
+  // 2024-01-01 is a Monday: ISO weekday `n` is that date plus `n - 1` days.
+  const monday = plainDateOf({ year: 2024, month: 1, day: 1 });
+  return Array.from({ length: 7 }, (_, index) => {
+    const date = plainDateToUtcInstant(addPlainDays(monday, (weekStart - 1 + index) % 7));
+    return {
+      short: formatter(locale, { weekday: 'narrow' }).format(date),
+      long: formatter(locale, { weekday: 'long' }).format(date),
+    };
+  });
+}

package/src/components/chart-checks.ts

@@ -0,0 +1,59 @@
+// The shapes a chart refuses rather than draws wrong: a series whose values do not line up with
+// the keys, x positions that are not ascending, gauge thresholds out of order. A misaligned row
+// drawn anyway puts a value under the wrong key — a chart that lies quietly — so each is coded.
+
+import { renderCauseValue } from '@ultimat3/core';
+import { UI_ERROR_CODES, UiError } from '../errors';
+import type { ChartSeries } from './chart-frame-view';
+
+function refused(cause: string, fix: string): UiError {
+  return new UiError({ code: UI_ERROR_CODES.invalidValue, cause, fix });
+}
+
+/** Every series carries exactly one value per key; `null` is how a gap is said. */
+export function checkSeries(
+  chart: string,
+  keys: readonly string[],
+  series: readonly ChartSeries[],
+): void {
+  for (const one of series) {
+    if (one.values.length === keys.length) continue;
+    throw refused(
+      `<${chart}> series ${renderCauseValue(one.label)} has ${one.values.length} values for ${keys.length} keys`,
+      'values: keys.map((key) => byKey.get(key) ?? null)   # one value per key, null for a gap — never a shorter row',
+    );
+  }
+}
+
+/** True x positions: one per key, finite, strictly ascending. */
+export function checkAt(chart: string, keys: readonly string[], at: readonly number[]): void {
+  const fix =
+    'at: rows.map((row) => row.at.getTime())   # one finite number per key, oldest first, no repeats';
+  if (at.length !== keys.length) {
+    throw refused(`<${chart}> at has ${at.length} positions for ${keys.length} keys`, fix);
+  }
+  for (let i = 0; i < at.length; i += 1) {
+    const value = at[i] as number;
+    if (!Number.isFinite(value) || (i > 0 && value <= (at[i - 1] as number))) {
+      throw refused(
+        `<${chart}> at[${i}] is ${renderCauseValue(value)}, which is not finite and above at[${i - 1}]`,
+        fix,
+      );
+    }
+  }
+}
+
+/** Thresholds ascend by `at`, so "the last one passed" is one answer. */
+export function checkThresholds(
+  chart: string,
+  thresholds: readonly { readonly at: number }[],
+): void {
+  for (let i = 0; i < thresholds.length; i += 1) {
+    const at = thresholds[i]?.at as number;
+    if (Number.isFinite(at) && (i === 0 || at > (thresholds[i - 1]?.at as number))) continue;
+    throw refused(
+      `<${chart}> thresholds[${i}].at is ${renderCauseValue(at)}, which is not finite and above the one before`,
+      "thresholds: [{ at: 70, tone: 'warning' }, { at: 90, tone: 'danger' }]   # ascending by at, in the value's unit",
+    );
+  }
+}

package/src/components/chart-frame-view.ts

@@ -3,6 +3,8 @@
 // no-colour reader get instead of the picture, and how a number becomes text — always in a locale
 // the caller passed, never the runtime's default.
 
+import type { Tone } from './variants';
+
 /** The chart colour roles, `chart-1` … `chart-8` (`--color-chart-N`). */
 export const CHART_SERIES_SLOTS = 8;
 
@@ -144,8 +146,13 @@ export function finiteOrNull(value: number | null | undefined): number | null {
 export interface ChartSeries {
   /** The series' name, already translated: the legend entry and the table's column head. */
   readonly label: string;
-  /** One value per key, in key order; `null` is a gap in the line and an empty table cell. */
+  /** One value per key, in key order; `null` is a gap in the line and `ui.chart.none` in the table. */
   readonly values: readonly (number | null)[];
+  /**
+   * A status colour in place of the slot's — an error rate in `danger`. The dash and marker stay,
+   * so the series is never told apart by colour alone.
+   */
+  readonly tone?: Tone | undefined;
 }
 
 export interface ChartTableRow {
@@ -166,6 +173,8 @@ export interface ChartTableInput {
   readonly keys: readonly string[];
   readonly series: readonly ChartSeries[];
   readonly format: (value: number) => string;
+  /** What a gap's cell says, already translated (`ui.chart.none`) — an empty cell reads as nothing. */
+  readonly none: string;
 }
 
 /** The same numbers the picture draws, as rows a screen reader walks cell by cell. */
@@ -177,7 +186,7 @@ export function chartTable(input: ChartTableInput): ChartTable {
       key,
       cells: input.series.map((series) => {
         const value = finiteOrNull(series.values[index]);
-        return value === null ? '' : input.format(value);
+        return value === null ? input.none : input.format(value);
       }),
     })),
   };
@@ -217,3 +226,25 @@ export function hitEdge(x: number, width: number): 'start' | 'middle' | 'end' {
   if (share > 0.8) return 'end';
   return 'middle';
 }
+
+/**
+ * A point's stable identity across ticks: its series and its key, so a live window that drops the
+ * oldest key keeps every other point's node — and the focus on it. A repeated key gets `#n`, the
+ * first `n` no earlier id holds: a key may itself read `a#1`, and a duplicate id throws in
+ * `keyedRows`, taking the whole chart with it.
+ */
+export function hitIds(series: number, keys: readonly string[]): readonly string[] {
+  const seen = new Map<string, number>();
+  const used = new Set<string>();
+  return keys.map((key) => {
+    let n = seen.get(key) ?? 0;
+    let id = n === 0 ? `${series}:${key}` : `${series}:${key}#${n}`;
+    while (used.has(id)) {
+      n += 1;
+      id = `${series}:${key}#${n}`;
+    }
+    seen.set(key, n + 1);
+    used.add(id);
+    return id;
+  });
+}

package/src/components/chart-reference-view.ts

@@ -0,0 +1,41 @@
+// Reference lines — a target, a limit, last week's mean — as geometry every xy chart shares: a
+// horizontal rule at a value, its label, and its tone. The value widens the chart's range, so a
+// target above every bar is still on the plot rather than silently off it.
+
+import { finiteOrNull } from './chart-frame-view';
+import type { Tone } from './variants';
+
+export interface ChartReference {
+  readonly value: number;
+  /** Already translated: "Target", "SLO 99.9%". Drawn beside the rule with its value. */
+  readonly label: string;
+  /** Default `neutral`. The rule is dashed in every tone, so it never reads as a series. */
+  readonly tone?: Tone | undefined;
+}
+
+export interface ReferenceLine {
+  readonly value: number;
+  readonly y: number;
+  readonly label: string;
+  readonly tone: Tone;
+}
+
+/** The finite values among `references` — what an extent folds in. */
+export function referenceValues(references: readonly ChartReference[] | undefined): number[] {
+  return (references ?? []).flatMap((ref) => {
+    const value = finiteOrNull(ref.value);
+    return value === null ? [] : [value];
+  });
+}
+
+/** Each drawable reference at its y, by the chart's own scale; a non-finite value is dropped. */
+export function referenceLines(
+  references: readonly ChartReference[] | undefined,
+  yOf: (value: number) => number,
+): readonly ReferenceLine[] {
+  return (references ?? []).flatMap((ref) => {
+    const value = finiteOrNull(ref.value);
+    if (value === null) return [];
+    return [{ value, y: yOf(value), label: ref.label, tone: ref.tone ?? 'neutral' }];
+  });
+}