@ultimat3/ui 20.1.6 → 20.2.0

package/src/components/qr-encode.ts

@@ -0,0 +1,187 @@
+// The data half of a pure-TypeScript QR encoder — byte mode, error-correction level M, no
+// dependency: the framework's own docs use a sparkline pulling in a charting library as the
+// cautionary example (see `BarChart.tsx`), and a QR library would be the same mistake for a
+// component that draws one short URL. `qr-matrix.ts` is the placement half.
+//
+// SUPPORTED VERSION RANGE: 1 through 3 ONLY (21x21 through 29x29 modules), byte mode, EC level M.
+// That is not a shortcut that happens to work for `HELLO WORLD` and nothing else: version 3's
+// byte-mode capacity at level M is 42 bytes, and a short URL (`origin + '/' + 6-char slug`) runs
+// roughly 25-30 bytes — comfortably inside version 3, and past version 1's 14-byte and version 2's
+// 26-byte ceilings for anything but the shortest local origin. Encoding a longer payload (a longer
+// domain, a full page URL) throws `X_UI_QR_CAPACITY` naming the byte count and the version-3
+// ceiling, rather than silently truncating a link nobody could then scan.
+//
+// Versions 1-3 are the ones with AT MOST ONE alignment pattern (version 1 has none) and no
+// version-information block (that only starts at version 7) — the two things that make the
+// placement algorithm tractable without the full 1-40 table set a general-purpose encoder needs.
+// Versions 1-3 at level M also always split into exactly ONE Reed-Solomon block, so no
+// interleaving is needed either.
+
+import { qrCapacityError } from '../errors';
+
+/** The one error correction level this module implements — the format-info field for level M. */
+export const EC_LEVEL_M_INDICATOR = 0b00;
+
+/** The largest version this encoder draws. */
+export const MAX_VERSION = 3;
+
+/** Per-version constants, indexed by `version - 1`. Hardcoded because only versions 1-3 exist
+ *  here — a general encoder would read these from the ISO 18004 tables for all 40 versions. */
+const TOTAL_CODEWORDS: readonly number[] = [26, 44, 70];
+const ECC_CODEWORDS_PER_BLOCK: readonly number[] = [10, 16, 26];
+
+/** Alignment pattern center coordinates along one axis; the full set of centers is every pair
+ *  from this list, MINUS the corner that overlaps the top-left finder pattern. Version 1 has no
+ *  alignment pattern at all. */
+export const ALIGNMENT_POSITIONS: readonly (readonly number[])[] = [[], [6, 18], [6, 22]];
+
+const MODE_BYTE = 0b0100;
+/** Versions 1-9 use an 8-bit character-count field for byte mode. */
+const CHAR_COUNT_BITS = 8;
+
+/** Data codewords at `version`: the total minus the error-correction block. */
+export function dataCapacityBytes(version: number): number {
+  return (TOTAL_CODEWORDS[version - 1] ?? 0) - (ECC_CODEWORDS_PER_BLOCK[version - 1] ?? 0);
+}
+
+/** Mode indicator (4 bits) + character count (8 bits) precede the payload in the data stream. */
+const HEADER_BITS = 4 + CHAR_COUNT_BITS;
+
+/** The most payload bytes `version` holds: the data codewords minus the header's 12 bits, which
+ *  cost two whole bytes once the stream is byte-aligned — 14, 26 and 42 for versions 1-3. NOT
+ *  `dataCapacityBytes`: that is 44 at version 3, and an error naming 44 as the ceiling would
+ *  tell the reader a 43-byte value fits when it does not. */
+export function payloadCapacityBytes(version: number): number {
+  return Math.floor((dataCapacityBytes(version) * 8 - HEADER_BITS) / 8);
+}
+
+/** The smallest of versions 1-3 whose data capacity holds `byteLength` bytes of byte-mode
+ *  payload, accounting for the header's own 12 bits (1.5 bytes) and a 4-bit terminator that can
+ *  share the last byte. Throws past version 3's ceiling. */
+export function pickVersion(byteLength: number): number {
+  for (let version = 1; version <= MAX_VERSION; version++) {
+    if (byteLength <= payloadCapacityBytes(version)) return version;
+  }
+  throw qrCapacityError(byteLength, payloadCapacityBytes(MAX_VERSION));
+}
+
+/** Modules per side: 21, 25, 29 for versions 1, 2, 3. */
+export function sizeForVersion(version: number): number {
+  return 4 * version + 17;
+}
+
+// ---------------------------------------------------------------------------------------------
+// GF(256) arithmetic and Reed-Solomon error correction (ISO 18004 Annex A).
+// ---------------------------------------------------------------------------------------------
+
+const GF_EXP = new Uint8Array(512);
+const GF_LOG = new Uint8Array(256);
+
+(function initGaloisField(): void {
+  let x = 1;
+  for (let i = 0; i < 255; i++) {
+    GF_EXP[i] = x;
+    GF_LOG[x] = i;
+    x <<= 1;
+    if ((x & 0x100) !== 0) x ^= 0x11d; // primitive polynomial x^8 + x^4 + x^3 + x^2 + 1
+  }
+  for (let i = 255; i < 512; i++) GF_EXP[i] = GF_EXP[i - 255] ?? 0;
+})();
+
+export function gfMul(a: number, b: number): number {
+  if (a === 0 || b === 0) return 0;
+  return GF_EXP[(GF_LOG[a] ?? 0) + (GF_LOG[b] ?? 0)] ?? 0;
+}
+
+/** The generator polynomial for a Reed-Solomon code with `degree` correction codewords, as the
+ *  coefficients of (x - 2^0)(x - 2^1)...(x - 2^(degree-1)), highest degree first, monic term
+ *  implicit. */
+export function rsGeneratorPolynomial(degree: number): Uint8Array {
+  const coefs = new Uint8Array(degree);
+  coefs[degree - 1] = 1;
+  let root = 1;
+  for (let i = 0; i < degree; i++) {
+    for (let j = 0; j < degree; j++) {
+      coefs[j] = gfMul(coefs[j] ?? 0, root);
+      if (j + 1 < degree) coefs[j] = (coefs[j] ?? 0) ^ (coefs[j + 1] ?? 0);
+    }
+    root = gfMul(root, 2);
+  }
+  return coefs;
+}
+
+/** The Reed-Solomon remainder (the error-correction codewords) of `data` divided by the
+ *  generator polynomial `divisor` — polynomial long division carried out in GF(256). */
+export function rsRemainder(data: readonly number[], divisor: Uint8Array): Uint8Array {
+  const result = new Uint8Array(divisor.length);
+  for (const b of data) {
+    const factor = b ^ (result[0] ?? 0);
+    result.copyWithin(0, 1);
+    result[result.length - 1] = 0;
+    for (let i = 0; i < result.length; i++) {
+      result[i] = (result[i] ?? 0) ^ gfMul(divisor[i] ?? 0, factor);
+    }
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Data encoding: byte mode, terminator, padding, error correction.
+// ---------------------------------------------------------------------------------------------
+
+/** A growable bit buffer, most-significant-bit first — the order every field in a QR symbol's
+ *  data stream is written in. */
+export class BitBuffer {
+  private bits: number[] = [];
+
+  appendBits(value: number, length: number): void {
+    for (let i = length - 1; i >= 0; i--) this.bits.push((value >>> i) & 1);
+  }
+
+  get length(): number {
+    return this.bits.length;
+  }
+
+  /** Pads to a whole byte with zero bits, then returns one byte per 8 bits. */
+  toBytes(): number[] {
+    while (this.bits.length % 8 !== 0) this.bits.push(0);
+    const bytes: number[] = [];
+    for (let i = 0; i < this.bits.length; i += 8) {
+      let byte = 0;
+      for (let j = 0; j < 8; j++) byte = (byte << 1) | (this.bits[i + j] ?? 0);
+      bytes.push(byte);
+    }
+    return bytes;
+  }
+}
+
+/** The pad codewords the standard alternates until the block is full. */
+const PAD = [0xec, 0x11] as const;
+
+/** The full codeword sequence for one QR symbol at `version`: data codewords (byte-mode payload,
+ *  terminated and padded to capacity) followed by the Reed-Solomon error-correction codewords.
+ *  Versions 1-3 at level M are always exactly one block, so no interleaving is needed. */
+export function buildCodewords(payload: Uint8Array, version: number): number[] {
+  const capacity = dataCapacityBytes(version);
+  const buffer = new BitBuffer();
+  buffer.appendBits(MODE_BYTE, 4);
+  buffer.appendBits(payload.length, CHAR_COUNT_BITS);
+  for (const byte of payload) buffer.appendBits(byte, 8);
+
+  // Terminator: up to 4 zero bits, but never past the data capacity — a payload that exactly
+  // fills the capacity gets no terminator at all, per the standard.
+  const terminatorBits = Math.min(4, capacity * 8 - buffer.length);
+  if (terminatorBits > 0) buffer.appendBits(0, terminatorBits);
+
+  const dataBytes = buffer.toBytes();
+  // Pad codewords 0xEC, 0x11 alternating until the block is exactly `capacity` bytes.
+  let padIndex = 0;
+  while (dataBytes.length < capacity) {
+    dataBytes.push(PAD[padIndex % 2] ?? 0);
+    padIndex++;
+  }
+
+  const eccLength = ECC_CODEWORDS_PER_BLOCK[version - 1] ?? 0;
+  const ecc = rsRemainder(dataBytes, rsGeneratorPolynomial(eccLength));
+  return [...dataBytes, ...Array.from(ecc)];
+}

package/src/components/qr-matrix.ts

@@ -0,0 +1,329 @@
+// The placement half of the pure-TypeScript QR encoder: function patterns, data placement,
+// masking and format information over the codewords `qr-encode.ts` builds. Versions 1-3 only
+// (see that file's header for why): at most one alignment pattern, no version-information
+// block, one Reed-Solomon block — the three simplifications that keep this file a page long.
+
+import {
+  ALIGNMENT_POSITIONS,
+  buildCodewords,
+  EC_LEVEL_M_INDICATOR,
+  pickVersion,
+  sizeForVersion,
+} from './qr-encode';
+
+type Module = boolean | undefined;
+
+/** `true`/`false` is a set module (dark/light); `undefined` is not yet claimed by any pattern —
+ *  the placement pass below only ever writes into `undefined` cells, so a function pattern drawn
+ *  first can never be overwritten by data. */
+class Matrix {
+  readonly size: number;
+  private cells: Module[];
+
+  constructor(size: number) {
+    this.size = size;
+    this.cells = new Array<Module>(size * size).fill(undefined);
+  }
+
+  get(row: number, col: number): Module {
+    if (row < 0 || col < 0 || row >= this.size || col >= this.size) return undefined;
+    return this.cells[row * this.size + col];
+  }
+
+  set(row: number, col: number, dark: boolean): void {
+    this.cells[row * this.size + col] = dark;
+  }
+
+  isSet(row: number, col: number): boolean {
+    return this.get(row, col) !== undefined;
+  }
+
+  toBooleans(): boolean[][] {
+    const out: boolean[][] = [];
+    for (let r = 0; r < this.size; r++) {
+      const row: boolean[] = [];
+      for (let c = 0; c < this.size; c++) row.push(this.cells[r * this.size + c] === true);
+      out.push(row);
+    }
+    return out;
+  }
+}
+
+function drawFinderPattern(matrix: Matrix, centerRow: number, centerCol: number): void {
+  for (let dr = -4; dr <= 4; dr++) {
+    for (let dc = -4; dc <= 4; dc++) {
+      const r = centerRow + dr;
+      const c = centerCol + dc;
+      if (r < 0 || c < 0 || r >= matrix.size || c >= matrix.size) continue;
+      const dist = Math.max(Math.abs(dr), Math.abs(dc));
+      // Concentric squares: dark core (0-1), light ring (2), dark ring (3), light border (4).
+      const dark = dist <= 1 || dist === 3;
+      matrix.set(r, c, dark);
+    }
+  }
+}
+
+function drawAlignmentPattern(matrix: Matrix, centerRow: number, centerCol: number): void {
+  for (let dr = -2; dr <= 2; dr++) {
+    for (let dc = -2; dc <= 2; dc++) {
+      const dist = Math.max(Math.abs(dr), Math.abs(dc));
+      matrix.set(centerRow + dr, centerCol + dc, dist !== 1);
+    }
+  }
+}
+
+function drawFunctionPatterns(matrix: Matrix, version: number): void {
+  const size = matrix.size;
+
+  // Three finder patterns, each an 8x8 area (7x7 pattern plus a light separator ring); only the
+  // 7x7 pattern is drawn as dark/light above, so the surrounding separator is drawn explicitly.
+  const corners: readonly (readonly [number, number])[] = [
+    [3, 3],
+    [3, size - 4],
+    [size - 4, 3],
+  ];
+  for (const [row, col] of corners) drawFinderPattern(matrix, row, col);
+  // Separators: the light ring one module beyond each finder pattern, clipped to the matrix.
+  for (const [row, col] of corners) {
+    for (let d = -4; d <= 4; d++) {
+      for (const [r, c] of [
+        [row + d, col - 5],
+        [row + d, col + 5],
+        [row - 5, col + d],
+        [row + 5, col + d],
+      ] as const) {
+        if (r >= 0 && c >= 0 && r < size && c < size && !matrix.isSet(r, c))
+          matrix.set(r, c, false);
+      }
+    }
+  }
+
+  // Timing patterns: row 6 and column 6, alternating dark/light, skipping cells the finder
+  // patterns already claimed.
+  for (let i = 0; i < size; i++) {
+    const dark = i % 2 === 0;
+    if (!matrix.isSet(6, i)) matrix.set(6, i, dark);
+    if (!matrix.isSet(i, 6)) matrix.set(i, 6, dark);
+  }
+
+  // Alignment pattern(s): every (row, col) pair from this version's coordinate list, except the
+  // one that overlaps the top-left finder pattern.
+  const positions = ALIGNMENT_POSITIONS[version - 1] ?? [];
+  for (const row of positions) {
+    for (const col of positions) {
+      if (row === 6 && col === 6) continue;
+      drawAlignmentPattern(matrix, row, col);
+    }
+  }
+
+  // The single dark module every version carries at a fixed offset from the bottom-left finder
+  // pattern — part of the format-information area, not itself format data.
+  matrix.set(4 * version + 9, 8, true);
+
+  // Reserve (as light, for now) the format-information cells around the top-left finder pattern
+  // and the two strips mirroring it — `drawFormatInfo` overwrites the ones that carry a 1 bit.
+  for (let i = 0; i < 8; i++) {
+    if (!matrix.isSet(8, i)) matrix.set(8, i, false);
+    if (!matrix.isSet(i, 8)) matrix.set(i, 8, false);
+    if (!matrix.isSet(8, size - 1 - i)) matrix.set(8, size - 1 - i, false);
+    if (!matrix.isSet(size - 1 - i, 8)) matrix.set(size - 1 - i, 8, false);
+  }
+  if (!matrix.isSet(8, 8)) matrix.set(8, 8, false);
+}
+
+/** BCH(15,5) error-correction over the 5-bit format-info value (2-bit EC level + 3-bit mask
+ *  pattern), XORed with the fixed mask 0b101010000010010 — the exact construction ISO 18004
+ *  §8.9 specifies for the 15-bit format string every QR symbol below version 7 carries twice. */
+export function formatInfoBits(maskPattern: number): number {
+  const GENERATOR = 0b10100110111;
+  const data = (EC_LEVEL_M_INDICATOR << 3) | maskPattern;
+  let value = data << 10;
+  for (let shift = 4; shift >= 0; shift--) {
+    if ((value & (1 << (shift + 10))) !== 0) value ^= GENERATOR << shift;
+  }
+  return ((data << 10) | value) ^ 0b101010000010010;
+}
+
+function drawFormatInfo(matrix: Matrix, maskPattern: number): void {
+  const size = matrix.size;
+  const bits = formatInfoBits(maskPattern);
+  const bit = (i: number): boolean => ((bits >>> i) & 1) === 1;
+
+  // The top-left strip: bits 0-5 down column 8 (skipping the timing row), bits 6-7 continue
+  // down the same column past row 7, bits 8-14 continue along row 8 to the right of column 8
+  // (skipping the timing column) — the standard's own zig from the corner.
+  for (let i = 0; i <= 5; i++) matrix.set(i, 8, bit(i));
+  matrix.set(7, 8, bit(6));
+  matrix.set(8, 8, bit(7));
+  matrix.set(8, 7, bit(8));
+  for (let i = 9; i <= 14; i++) matrix.set(8, 14 - i, bit(i));
+
+  // The mirrored copy: bits 0-7 along row `size-1` down to `size-8` in column 8, bits 8-14 up
+  // column `size-1` down to `size-15` in row 8.
+  for (let i = 0; i <= 7; i++) matrix.set(size - 1 - i, 8, bit(i));
+  for (let i = 8; i <= 14; i++) matrix.set(8, size - 15 + i, bit(i));
+}
+
+/** Whether mask `pattern` (0-7, ISO 18004 §8.8.1) flips the module at `(row, col)`. */
+export function applyMask(row: number, col: number, pattern: number): boolean {
+  switch (pattern) {
+    case 0:
+      return (row + col) % 2 === 0;
+    case 1:
+      return row % 2 === 0;
+    case 2:
+      return col % 3 === 0;
+    case 3:
+      return (row + col) % 3 === 0;
+    case 4:
+      return (Math.floor(row / 2) + Math.floor(col / 3)) % 2 === 0;
+    case 5:
+      return ((row * col) % 2) + ((row * col) % 3) === 0;
+    case 6:
+      return (((row * col) % 2) + ((row * col) % 3)) % 2 === 0;
+    default:
+      return (((row + col) % 2) + ((row * col) % 3)) % 2 === 0;
+  }
+}
+
+/** Writes `codewords` into every module the function patterns left `undefined`, in the standard
+ *  boustrophedon (up-down, right-to-left in 2-column strides, skipping the timing column) order,
+ *  masking each written bit with `pattern` as it goes — masking happens INLINE here rather than
+ *  as a second pass, because only the data modules (never a function pattern) are ever masked. */
+function drawData(matrix: Matrix, codewords: readonly number[], pattern: number): void {
+  const size = matrix.size;
+  const bits: boolean[] = [];
+  for (const byte of codewords) for (let i = 7; i >= 0; i--) bits.push(((byte >>> i) & 1) === 1);
+
+  let bitIndex = 0;
+  let upward = true;
+  for (let colPair = size - 1; colPair > 0; colPair -= 2) {
+    for (let count = 0; count < size; count++) {
+      const row = upward ? size - 1 - count : count;
+      for (let colOffset = 0; colOffset < 2; colOffset++) {
+        const col = colPair - colOffset;
+        if (col === 6) continue; // the vertical timing column carries no data
+        if (matrix.isSet(row, col)) continue;
+        const bit = bits[bitIndex] ?? false;
+        bitIndex++;
+        const masked = applyMask(row, col, pattern) ? !bit : bit;
+        matrix.set(row, col, masked);
+      }
+    }
+    upward = !upward;
+  }
+}
+
+/** N1: five or more same-colour modules in a row/column. */
+function runPenalty(line: readonly boolean[]): number {
+  let total = 0;
+  let runLength = 1;
+  for (let i = 1; i <= line.length; i++) {
+    if (i < line.length && line[i] === line[i - 1]) {
+      runLength++;
+      continue;
+    }
+    if (runLength >= 5) total += 3 + (runLength - 5);
+    runLength = 1;
+  }
+  return total;
+}
+
+/** N3: the finder-like dark-light-dark-dark-dark-light-dark run, with 4 light either side. */
+const FINDER_LIKE = [true, false, true, true, true, false, true, false, false, false, false];
+const FINDER_LIKE_REVERSED = [...FINDER_LIKE].reverse();
+
+function finderLikePenalty(line: readonly boolean[]): number {
+  let total = 0;
+  const matches = (start: number, target: readonly boolean[]): boolean =>
+    target.every((v, i) => line[start + i] === v);
+  for (let i = 0; i + FINDER_LIKE.length <= line.length; i++) {
+    if (matches(i, FINDER_LIKE) || matches(i, FINDER_LIKE_REVERSED)) total += 40;
+  }
+  return total;
+}
+
+/** The standard penalty score (ISO 18004 §8.8.2, rules N1-N4) — lower is a better mask, chosen
+ *  by trying all 8 candidates rather than fixing one, so this encoder's output is a symbol a
+ *  real scanner reads reliably rather than merely a structurally valid one. */
+export function maskPenalty(bools: readonly (readonly boolean[])[]): number {
+  const size = bools.length;
+  const column = (c: number): boolean[] => bools.map((row) => row[c] === true);
+  let penalty = 0;
+
+  for (const row of bools) penalty += runPenalty(row) + finderLikePenalty(row);
+  for (let c = 0; c < size; c++) {
+    const col = column(c);
+    penalty += runPenalty(col) + finderLikePenalty(col);
+  }
+
+  // N2: 2x2 blocks of one colour.
+  for (let r = 0; r < size - 1; r++) {
+    for (let c = 0; c < size - 1; c++) {
+      const v = bools[r]?.[c] ?? false;
+      if (bools[r]?.[c + 1] === v && bools[r + 1]?.[c] === v && bools[r + 1]?.[c + 1] === v) {
+        penalty += 3;
+      }
+    }
+  }
+
+  // N4: overall dark-module proportion, penalised the further it strays from 50%.
+  const dark = bools.reduce((sum, row) => sum + row.filter(Boolean).length, 0);
+  const percentDark = (dark * 100) / (size * size);
+  penalty += Math.floor(Math.abs(percentDark - 50) / 5) * 10;
+
+  return penalty;
+}
+
+/** Light modules on every side of the symbol. Four is the standard's minimum; fewer and a
+ *  scanner cannot separate the finder patterns from whatever the page drew next to them. */
+export const DEFAULT_QUIET_ZONE = 4;
+
+/** The quiet zone a caller asked for, screened: a non-integer, a negative or `NaN` would move
+ *  every module by a nonsense offset, so anything but a whole count of modules is the default. */
+export function quietZoneOf(requested: number | undefined): number {
+  if (typeof requested !== 'number' || !Number.isSafeInteger(requested) || requested < 0) {
+    return DEFAULT_QUIET_ZONE;
+  }
+  return requested;
+}
+
+export interface QrMatrix {
+  /** Modules per side — 21, 25 or 29 for versions 1, 2 and 3. */
+  readonly size: number;
+  /** `modules[row][col]` — `true` is a dark (foreground) module. */
+  readonly modules: readonly (readonly boolean[])[];
+  readonly version: number;
+}
+
+interface MaskCandidate {
+  readonly pattern: number;
+  readonly bools: boolean[][];
+  readonly penalty: number;
+}
+
+/**
+ * Encodes `text` as a QR symbol, byte mode, error-correction level M, choosing the smallest of
+ * versions 1-3 that fits. Throws `X_UI_QR_CAPACITY` past version 3's 42-byte ceiling. Pure: the
+ * same text always yields the same modules, so a server render and a hydrated one agree.
+ */
+export function encodeQr(text: string): QrMatrix {
+  const payload = new TextEncoder().encode(text);
+  const version = pickVersion(payload.length);
+  const codewords = buildCodewords(payload, version);
+  const size = sizeForVersion(version);
+
+  let best: MaskCandidate | undefined;
+  for (let pattern = 0; pattern < 8; pattern++) {
+    const matrix = new Matrix(size);
+    drawFunctionPatterns(matrix, version);
+    drawData(matrix, codewords, pattern);
+    drawFormatInfo(matrix, pattern);
+    const bools = matrix.toBooleans();
+    const penalty = maskPenalty(bools);
+    if (best === undefined || penalty < best.penalty) best = { pattern, bools, penalty };
+  }
+  // `pickVersion` already threw if nothing fits, so by construction all eight masks ran; the
+  // fallback is unreachable and exists so the return type needs no assertion.
+  return { size, modules: best?.bools ?? [], version };
+}

package/src/components/sparkline-view.ts

@@ -0,0 +1,36 @@
+// The path of a Sparkline, apart from its markup. A sparkline has no axes and no scale to read —
+// the shape of the trend is the entire point — so this is one `M`/`L` path through every point,
+// scaled into the box. Pure, so two renders draw one line.
+
+import type { ChartPoint } from './bar-chart-view';
+import { maxOf } from './bar-chart-view';
+
+/** 600 × 72: stretched to a content column, 240 × 48 came out ~220px tall — a chart, not a sparkline. */
+export const SPARKLINE = { width: 600, height: 72, pad: 4 } as const;
+
+export interface SparkPoint {
+  readonly x: number;
+  readonly y: number;
+}
+
+/** Every point's position in the box, oldest first; a single point sits at the start. */
+export function sparkPoints(points: readonly ChartPoint[]): readonly SparkPoint[] {
+  const max = maxOf(points);
+  const innerWidth = SPARKLINE.width - SPARKLINE.pad * 2;
+  const innerHeight = SPARKLINE.height - SPARKLINE.pad * 2;
+  const step = points.length > 1 ? innerWidth / (points.length - 1) : 0;
+  return points.map((point, index) => {
+    const value = Number.isFinite(point.value) ? Math.max(0, point.value) : 0;
+    return {
+      x: SPARKLINE.pad + step * index,
+      y: SPARKLINE.pad + innerHeight - (value / max) * innerHeight,
+    };
+  });
+}
+
+/** The `d` attribute, one decimal per coordinate — stable across renders. Empty for no points. */
+export function sparklinePath(points: readonly ChartPoint[]): string {
+  return sparkPoints(points)
+    .map((p, index) => `${index === 0 ? 'M' : 'L'}${p.x.toFixed(1)},${p.y.toFixed(1)}`)
+    .join(' ');
+}

package/src/components/stat-delta.ts

@@ -0,0 +1,30 @@
+// The trend chip on a StatTile, as a pure rule: a percentage against a baseline, or nothing at
+// all when the baseline is zero — a percentage of nothing is a number that means nothing.
+
+export type StatTrend = 'up' | 'down' | 'flat';
+
+export interface StatDelta {
+  /** Already formatted: "+12%", "−4%", "0%". */
+  readonly text: string;
+  readonly trend: StatTrend;
+}
+
+/**
+ * U+2212, the real minus: it is the width of `+`, so the chip does not jump between states.
+ * Rounded to a whole percent — a tile is a glance, not a ledger.
+ */
+export function deltaOf(current: number, baseline: number): StatDelta | undefined {
+  if (!Number.isFinite(current) || !Number.isFinite(baseline) || baseline <= 0) return undefined;
+  const pct = Math.round(((current - baseline) / baseline) * 100);
+  if (pct === 0) return { text: '0%', trend: 'flat' };
+  return pct > 0
+    ? { text: `+${pct}%`, trend: 'up' }
+    : { text: `−${Math.abs(pct)}%`, trend: 'down' };
+}
+
+/** Drawn, not typed: an arrow character inherits the font's metrics and sits off-centre in a pill. */
+export const DELTA_ARROW_PATH: Readonly<Record<StatTrend, string>> = {
+  up: 'M2 7 L5 3 L8 7',
+  down: 'M2 3 L5 7 L8 3',
+  flat: 'M2 5 L8 5',
+};

package/src/errors.ts

@@ -10,6 +10,7 @@ export const UI_ERROR_CODES = {
   invalidValue: 'X_UI_INVALID_VALUE',
   formPathInvalid: 'X_UI_FORM_PATH_INVALID',
   contrastInsufficient: 'X_UI_CONTRAST_INSUFFICIENT',
+  qrCapacity: 'X_UI_QR_CAPACITY',
 } as const;
 
 export type UiErrorCode = (typeof UI_ERROR_CODES)[keyof typeof UI_ERROR_CODES];
@@ -24,6 +25,7 @@ registerErrorCodes({
   X_UI_INVALID_VALUE: { title: 'a formatting component received an unrenderable value' },
   X_UI_FORM_PATH_INVALID: { title: 'a form control name is not a usable field path' },
   X_UI_CONTRAST_INSUFFICIENT: { title: 'a brand palette pairing does not meet WCAG 2.2 AA' },
+  X_UI_QR_CAPACITY: { title: 'text is too long for a QR code this component can draw' },
 });
 
 export class UiError extends UltimateError {
@@ -205,3 +207,17 @@ export function conflictingFieldNameError(name: string, at: string): UiError {
     fix: `rename one of the two controls — a path segment holds a value or a container, never both`,
   });
 }
+
+/**
+ * `<QrCode>` was handed more bytes than version 3 holds. Its own code rather than
+ * X_UI_INVALID_VALUE: the value is not malformed, it is too long for THIS encoder, and the fix is
+ * a shorter value or a full-range library — neither of which "parse it in the loader" describes.
+ * Refused rather than truncated, because a truncated link scans and then leads nowhere.
+ */
+export function qrCapacityError(byteLength: number, ceiling: number): UiError {
+  return new UiError({
+    code: UI_ERROR_CODES.qrCapacity,
+    cause: `<QrCode> value is ${byteLength} bytes in UTF-8; @ultimat3/ui encodes byte mode up to version 3 at error-correction level M, a ${ceiling}-byte ceiling`,
+    fix: 'shorten the value (a short URL, not a full page URL), or draw it with a full-range QR library outside @ultimat3/ui',
+  });
+}

package/src/i18n-keys.ts

@@ -41,6 +41,10 @@ export const UI_KEYS = {
   loadMore: 'ui.load.more',
   /** InfiniteScroll: announced when the last page has arrived. */
   endOfList: 'ui.load.end',
+  /** CopyButton: the control's name before a copy. */
+  copy: 'ui.copy',
+  /** CopyButton: announced, and the control's name, once the write succeeded. */
+  copied: 'ui.copied',
   errorCode: 'ui.error.code',
   errorCause: 'ui.error.cause',
   errorFix: 'ui.error.fix',