@dowel-ui/react 0.7.0 → 0.8.0

package/src/components/dither-canvas/dither-engine.ts

@@ -0,0 +1,354 @@
+// Ported from amicro "Dither Charts" (MIT, © 2026 Syed Subhan Uddin). See THIRD_PARTY_NOTICES.md.
+
+/*
+ * The pure half of the dither engine: no React, no DOM beyond the canvas
+ * context it is handed. Everything a dither chart needs to decide *how big a
+ * cell is* lives here, so it can be unit-tested without a canvas.
+ *
+ * The technique, as amicro draws it: the plot is a grid of fixed cells
+ * (~4.6 CSS px). Each cell is drawn as one small square, centred in the cell,
+ * whose side is `cell × density`. Density is built from three ingredients —
+ * a shape term (distance, fill level) eased with smoothstep, a time-based sum of
+ * sines for shimmer, and a per-cell hash for jitter — and the region is clipped
+ * to the shape's path. amicro's hash was `fract(sin(…) × 43758)` and two charts
+ * used Math.random; this one is an integer hash, so a frame is the same on every
+ * machine and every render (and a test can assert it).
+ */
+
+/** Default cell pitch in CSS pixels, as amicro's donut draws it. */
+export const DITHER_CELL = 4.6;
+
+/** Axis-aligned rectangle in CSS pixels. */
+export interface DitherBounds {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+export function lerp(from: number, to: number, t: number): number {
+  return from + (to - from) * t;
+}
+
+/** Hermite ease between two edges; 0 below `edge0`, 1 above `edge1`. */
+export function smoothstep(edge0: number, edge1: number, value: number): number {
+  if (edge0 === edge1) return value < edge0 ? 0 : 1;
+  const x = clamp((value - edge0) / (edge1 - edge0), 0, 1);
+  return x * x * (3 - 2 * x);
+}
+
+/**
+ * Deterministic per-cell hash in [0, 1).
+ *
+ * Coordinates are quantised to 1/100 px so the float noise in a cell's centre
+ * never changes its jitter. `seed` gives a second, independent field (the
+ * particle layer uses one) from the same cell.
+ */
+export function hash2(x: number, y: number, seed = 0): number {
+  let h =
+    Math.imul(Math.round(x * 100) | 0, 0x27d4eb2d) ^
+    Math.imul(Math.round(y * 100) | 0, 0x165667b1);
+  h = Math.imul(h ^ Math.imul(seed | 0, 0x9e3779b1), 0x85ebca6b);
+  h ^= h >>> 13;
+  h = Math.imul(h, 0xc2b2ae35);
+  h ^= h >>> 16;
+  return (h >>> 0) / 4294967296;
+}
+
+/**
+ * amicro's shimmer: a sum of sines eased into 0..1. Pass the raw terms (each
+ * in −1..1) so each chart keeps its own wave; with no terms — the reduced-motion
+ * case — it is the neutral 0.5.
+ */
+export function shimmer(...waves: number[]): number {
+  let sum = 0;
+  for (const wave of waves) sum += wave;
+  return smoothstep(-1.5, 1.5, sum);
+}
+
+/** The two-sine drift amicro's device donut and revenue fill share. */
+export function drift(x: number, y: number, time: number): number {
+  return shimmer(Math.sin(x * 0.05 + time), Math.sin(y * 0.05 + time * 0.7));
+}
+
+/**
+ * The drawn square for one cell: centred, side `cell × density`, never larger
+ * than the cell. Returns null when the density leaves nothing to draw.
+ */
+export function cellSquare(
+  x: number,
+  y: number,
+  cell: number,
+  density: number,
+): [x: number, y: number, size: number] | null {
+  const size = cell * clamp(density, 0, 1);
+  if (size <= 0.05) return null;
+  return [x + (cell - size) / 2, y + (cell - size) / 2, size];
+}
+
+/**
+ * Visits every cell overlapping `bounds`, on a grid anchored at the canvas
+ * origin. Anchoring matters: a grid anchored to each shape would swim as the
+ * shape animates, and two shapes would not share cells.
+ */
+export function forEachCell(
+  bounds: DitherBounds,
+  cell: number,
+  visit: (x: number, y: number) => void,
+): void {
+  if (cell <= 0 || bounds.width <= 0 || bounds.height <= 0) return;
+  const x0 = Math.floor(bounds.x / cell) * cell;
+  const y0 = Math.floor(bounds.y / cell) * cell;
+  const x1 = bounds.x + bounds.width;
+  const y1 = bounds.y + bounds.height;
+  for (let x = x0; x < x1; x += cell) {
+    for (let y = y0; y < y1; y += cell) visit(x, y);
+  }
+}
+
+/**
+ * Density function for one cell. `cx`/`cy` are the cell's centre and `x`/`y`
+ * its top-left corner, both in CSS pixels. Return 0..1 — the fraction of the
+ * cell the square covers; 0 or less skips the cell.
+ */
+export type DitherDensity = (cx: number, cy: number, x: number, y: number) => number;
+
+export interface DitherFillOptions {
+  /** Region to scan. Keep it tight: every cell in it runs `density`. */
+  bounds: DitherBounds;
+  density: DitherDensity;
+  /** Cell pitch in CSS pixels. Defaults to DITHER_CELL. */
+  cell?: number;
+  /** Clip region — usually a Path2D from `makePath`. Omit to fill the bounds. */
+  clip?: Path2D | null;
+  /** Resolved colour (`frame.color("primary")`). Omit to keep the current fillStyle. */
+  color?: string;
+  /** Multiplies the current globalAlpha for this fill. */
+  alpha?: number;
+}
+
+/**
+ * Fills a region with dithered cells. Saves and restores the context, so the
+ * clip, colour and alpha never leak into the next shape. Returns the number of
+ * squares drawn.
+ */
+export function ditherFill(ctx: CanvasRenderingContext2D, options: DitherFillOptions): number {
+  const cell = options.cell ?? DITHER_CELL;
+  let drawn = 0;
+  ctx.save();
+  if (options.clip) ctx.clip(options.clip);
+  if (options.color !== undefined) ctx.fillStyle = options.color;
+  if (options.alpha !== undefined) ctx.globalAlpha *= clamp(options.alpha, 0, 1);
+  forEachCell(options.bounds, cell, (x, y) => {
+    const square = cellSquare(x, y, cell, options.density(x + cell / 2, y + cell / 2, x, y));
+    if (!square) return;
+    ctx.fillRect(square[0], square[1], square[2], square[2]);
+    drawn += 1;
+  });
+  ctx.restore();
+  return drawn;
+}
+
+/* Colour ------------------------------------------------------------------ */
+
+/**
+ * Turns a colour reference into a CSS value:
+ * `"primary"` and `"--color-primary"` become `var(--color-primary)`; anything
+ * else (`var(…)`, `color-mix(…)`, `currentColor`) is passed through.
+ */
+export function tokenToCss(token: string): string {
+  if (token.startsWith("--")) return `var(${token})`;
+  if (/^[a-z][a-z0-9-]*$/.test(token) && token !== "currentcolor" && token !== "transparent") {
+    return `var(--color-${token})`;
+  }
+  return token;
+}
+
+/**
+ * Resolves a colour token to a concrete value a canvas accepts, as seen from
+ * `element` — so a theme scoped to a subtree applies. A hidden probe element
+ * lets the browser do the resolving, which also settles `color-mix()` and
+ * nested `var()`s that a canvas fillStyle would reject.
+ */
+export function resolveColor(element: Element, token: string): string {
+  const css = tokenToCss(token);
+  const doc = element.ownerDocument;
+  const view = doc.defaultView;
+  if (!view) return css;
+  const host = element.parentElement ?? doc.body;
+  const probe = doc.createElement("span");
+  probe.style.display = "none";
+  probe.style.color = css;
+  host.appendChild(probe);
+  const resolved = view.getComputedStyle(probe).color;
+  probe.remove();
+  if (resolved && !resolved.includes("var(")) return resolved;
+  // No resolution (a detached element, or a DOM without CSS): fall back to the
+  // custom property's own value, then to the expression itself.
+  const name = /^var\((--[\w-]+)\)$/.exec(css)?.[1];
+  const raw = name ? view.getComputedStyle(element).getPropertyValue(name).trim() : "";
+  return raw || css;
+}
+
+/**
+ * Default series colours: one hue — the theme's primary — stepped toward the
+ * card surface, as amicro's monochrome ramp is. Status tokens (success,
+ * warning, destructive) are deliberately absent: they mean state, not series.
+ * Identity never rests on colour alone; every chart also names each series in
+ * a legend, its readout and its data table.
+ */
+export const DITHER_PALETTE: readonly string[] = [
+  "primary",
+  "color-mix(in oklab, var(--color-primary) 72%, var(--color-card))",
+  "color-mix(in oklab, var(--color-primary) 50%, var(--color-card))",
+  "color-mix(in oklab, var(--color-primary) 34%, var(--color-card))",
+  "color-mix(in oklab, var(--color-primary) 22%, var(--color-card))",
+  "muted-foreground",
+];
+
+/** The colour for series `index`: its own if given, else the palette in order. */
+export function seriesColor(index: number, color?: string): string {
+  return color ?? DITHER_PALETTE[index % DITHER_PALETTE.length] ?? "primary";
+}
+
+/* Value animation ---------------------------------------------------------- */
+
+export interface SpringConfig {
+  stiffness?: number;
+  damping?: number;
+  mass?: number;
+  /** Distance and speed below which the spring snaps to rest. */
+  precision?: number;
+}
+
+export interface Spring {
+  readonly value: number;
+  readonly target: number;
+  readonly velocity: number;
+  /** Aims the spring at a new target; it moves on the next `step`. */
+  set(target: number): void;
+  /** Places the spring at rest on `value`. */
+  jump(value: number): void;
+  /** Advances by `dt` seconds. Returns true while still moving. */
+  step(dt: number, reducedMotion?: boolean): boolean;
+}
+
+/** amicro's number spring (motion's useSpring at 190 / 27 / 0.7). */
+export const DEFAULT_SPRING: Required<SpringConfig> = {
+  stiffness: 190,
+  damping: 27,
+  mass: 0.7,
+  precision: 0.001,
+};
+
+/**
+ * A damped spring for canvas values. Integrated in fixed sub-steps, so a long
+ * frame (a tab coming back into view) cannot make it explode. Under reduced
+ * motion `step` jumps straight to the target: the settled value, drawn once.
+ */
+export function createSpring(initial: number, config: SpringConfig = {}): Spring {
+  const { stiffness, damping, mass, precision } = { ...DEFAULT_SPRING, ...config };
+  let value = initial;
+  let target = initial;
+  let velocity = 0;
+  return {
+    get value() {
+      return value;
+    },
+    get target() {
+      return target;
+    },
+    get velocity() {
+      return velocity;
+    },
+    set(next) {
+      target = next;
+    },
+    jump(next) {
+      value = next;
+      target = next;
+      velocity = 0;
+    },
+    step(dt, reducedMotion = false) {
+      if (reducedMotion) {
+        value = target;
+        velocity = 0;
+        return false;
+      }
+      let remaining = clamp(dt, 0, 0.1);
+      while (remaining > 0) {
+        const h = Math.min(remaining, 1 / 240);
+        const force = -stiffness * (value - target) - damping * velocity;
+        velocity += (force / mass) * h;
+        value += velocity * h;
+        remaining -= h;
+      }
+      const scale = Math.max(1, Math.abs(target));
+      if (
+        Math.abs(value - target) < precision * scale &&
+        Math.abs(velocity) < precision * scale
+      ) {
+        value = target;
+        velocity = 0;
+        return false;
+      }
+      return true;
+    },
+  };
+}
+
+export interface SpringList {
+  readonly values: number[];
+  /** Aims at new targets. A different length resamples the current values. */
+  set(targets: readonly number[]): void;
+  jump(targets: readonly number[]): void;
+  step(dt: number, reducedMotion?: boolean): boolean;
+}
+
+/**
+ * Resamples `values` to `length` points by nearest index, so a 7-point series
+ * can morph into a 30-point one without a jump to zero (amicro's range switch).
+ */
+export function resample(values: readonly number[], length: number): number[] {
+  if (length <= 0) return [];
+  if (values.length === 0) return Array.from({ length }, () => 0);
+  if (values.length === length) return [...values];
+  return Array.from({ length }, (_, index) => {
+    const t = length === 1 ? 0 : index / (length - 1);
+    return values[Math.round(t * (values.length - 1))] ?? 0;
+  });
+}
+
+/** A list of springs that animates an array of values together. */
+export function createSprings(
+  initial: readonly number[],
+  config: SpringConfig = {},
+): SpringList {
+  let springs = initial.map((value) => createSpring(value, config));
+  const list: SpringList = {
+    get values() {
+      return springs.map((spring) => spring.value);
+    },
+    set(targets) {
+      if (targets.length !== springs.length) {
+        springs = resample(list.values, targets.length).map((value) =>
+          createSpring(value, config),
+        );
+      }
+      targets.forEach((target, index) => springs[index]?.set(target));
+    },
+    jump(targets) {
+      springs = targets.map((value) => createSpring(value, config));
+    },
+    step(dt, reducedMotion = false) {
+      let moving = false;
+      for (const spring of springs) moving = spring.step(dt, reducedMotion) || moving;
+      return moving;
+    },
+  };
+  return list;
+}

package/src/components/dither-canvas/dither-geometry.ts

@@ -0,0 +1,295 @@
+// Ported from amicro "Dither Charts" (MIT, © 2026 Syed Subhan Uddin). See THIRD_PARTY_NOTICES.md.
+
+/*
+ * Shape geometry for dither charts. Every tracer writes to a `PathSink` — the
+ * subset of the path API that both CanvasRenderingContext2D and Path2D share —
+ * so the same function builds a clip region, strokes an outline, or records
+ * its commands in a test.
+ */
+
+export interface PathSink {
+  moveTo(x: number, y: number): void;
+  lineTo(x: number, y: number): void;
+  arc(x: number, y: number, radius: number, start: number, end: number, ccw?: boolean): void;
+  arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void;
+  bezierCurveTo(c1x: number, c1y: number, c2x: number, c2y: number, x: number, y: number): void;
+  closePath(): void;
+}
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+/**
+ * Builds a Path2D from a tracer. Returns null where Path2D does not exist
+ * (server rendering, some test DOMs), so callers simply skip the clip.
+ */
+export function makePath(trace: (sink: PathSink) => void): Path2D | null {
+  if (typeof Path2D === "undefined") return null;
+  const path = new Path2D();
+  trace(path);
+  return path;
+}
+
+const TAU = Math.PI * 2;
+
+/** Normalises an angle into [0, 2π). */
+export function normalizeAngle(angle: number): number {
+  return ((angle % TAU) + TAU) % TAU;
+}
+
+export interface Wedge {
+  index: number;
+  /** Fraction of the whole, 0..1. */
+  share: number;
+  start: number;
+  end: number;
+  mid: number;
+}
+
+/**
+ * Splits a circle into wedges, clockwise from 12 o'clock by default, leaving
+ * `gap` radians between neighbours (amicro's graph donut uses 0.07).
+ * Negative and non-finite values count as zero.
+ */
+export function pieWedges(
+  values: readonly number[],
+  options: { start?: number; gap?: number } = {},
+): Wedge[] {
+  const start = options.start ?? -Math.PI / 2;
+  const gap = options.gap ?? 0;
+  const clean = values.map((value) => (Number.isFinite(value) && value > 0 ? value : 0));
+  const total = clean.reduce((sum, value) => sum + value, 0);
+  let cursor = start;
+  return clean.map((value, index) => {
+    const share = total > 0 ? value / total : 0;
+    const sweep = share * TAU;
+    const half = sweep > gap ? gap / 2 : sweep / 2;
+    const wedge = {
+      index,
+      share,
+      start: cursor + half,
+      end: cursor + sweep - half,
+      mid: cursor + sweep / 2,
+    };
+    cursor += sweep;
+    return wedge;
+  });
+}
+
+/** True when `angle` lies within the wedge's sweep. */
+export function angleInWedge(angle: number, start: number, end: number): boolean {
+  if (end <= start) return false;
+  return normalizeAngle(angle - start) <= end - start;
+}
+
+/**
+ * The wedge under a point, or null — hit-testing for a donut from pointer
+ * coordinates, so hover never needs to read pixels back.
+ */
+export function wedgeAt(
+  wedges: readonly Wedge[],
+  center: Point,
+  inner: number,
+  outer: number,
+  point: Point,
+): number | null {
+  const dx = point.x - center.x;
+  const dy = point.y - center.y;
+  const distance = Math.hypot(dx, dy);
+  if (distance < inner || distance > outer) return null;
+  const angle = Math.atan2(dy, dx);
+  const hit = wedges.find(
+    (wedge) => wedge.share > 0 && angleInWedge(angle, wedge.start, wedge.end),
+  );
+  return hit ? hit.index : null;
+}
+
+/** A plain annular sector (amicro's device donut). */
+export function traceWedge(
+  sink: PathSink,
+  center: Point,
+  inner: number,
+  outer: number,
+  start: number,
+  end: number,
+): void {
+  if (end - start <= 0.0001) return;
+  sink.moveTo(center.x + outer * Math.cos(start), center.y + outer * Math.sin(start));
+  sink.arc(center.x, center.y, outer, start, end);
+  sink.lineTo(center.x + inner * Math.cos(end), center.y + inner * Math.sin(end));
+  sink.arc(center.x, center.y, inner, end, start, true);
+  sink.closePath();
+}
+
+/** An annular sector with rounded corners (amicro's graph donut). */
+export function traceRoundedWedge(
+  sink: PathSink,
+  center: Point,
+  inner: number,
+  outer: number,
+  start: number,
+  end: number,
+  radius: number,
+): void {
+  const sweep = end - start;
+  if (sweep <= 0.001) return;
+  const r = Math.max(0, Math.min(radius, (outer - inner) / 2, (sweep * inner) / 2));
+  if (r === 0) {
+    traceWedge(sink, center, inner, outer, start, end);
+    return;
+  }
+  const { x: cx, y: cy } = center;
+  const at = (distance: number, angle: number): [number, number] => [
+    cx + distance * Math.cos(angle),
+    cy + distance * Math.sin(angle),
+  ];
+  const [isx, isy] = at(inner, start + r / inner);
+  sink.moveTo(isx, isy);
+  sink.arc(cx, cy, inner, start + r / inner, end - r / inner);
+  sink.arcTo(...at(inner, end), ...at(outer, end), r);
+  sink.arcTo(...at(outer, end), ...at(outer, end - r / outer), r);
+  sink.arc(cx, cy, outer, end - r / outer, start + r / outer, true);
+  sink.arcTo(...at(outer, start), ...at(inner, start), r);
+  sink.arcTo(...at(inner, start), isx, isy, r);
+  sink.closePath();
+}
+
+/** A rectangle with separate top and bottom corner radii (a stacked segment). */
+export function traceRoundedRect(
+  sink: PathSink,
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  radiusTop: number,
+  radiusBottom = radiusTop,
+): void {
+  if (width <= 0 || height <= 0) return;
+  const top = Math.max(0, Math.min(radiusTop, width / 2, height / 2));
+  const bottom = Math.max(0, Math.min(radiusBottom, width / 2, height / 2));
+  sink.moveTo(x + top, y);
+  sink.lineTo(x + width - top, y);
+  sink.arcTo(x + width, y, x + width, y + top, top);
+  sink.lineTo(x + width, y + height - bottom);
+  sink.arcTo(x + width, y + height, x + width - bottom, y + height, bottom);
+  sink.lineTo(x + bottom, y + height);
+  sink.arcTo(x, y + height, x, y + height - bottom, bottom);
+  sink.lineTo(x, y + top);
+  sink.arcTo(x, y, x + top, y, top);
+  sink.closePath();
+}
+
+/**
+ * Tangents for a monotone cubic spline (Fritsch–Carlson). Monotone means the
+ * curve never overshoots its data: a smooth line that invents a dip below zero
+ * between two positive days is lying.
+ */
+export function monotoneTangents(points: readonly Point[]): number[] {
+  const n = points.length;
+  if (n < 2) return points.map(() => 0);
+  const slopes: number[] = [];
+  for (let i = 0; i < n - 1; i++) {
+    const a = points[i] as Point;
+    const b = points[i + 1] as Point;
+    const dx = b.x - a.x;
+    slopes.push(dx === 0 ? 0 : (b.y - a.y) / dx);
+  }
+  const tangents = points.map((_, i) => {
+    if (i === 0) return slopes[0] ?? 0;
+    if (i === n - 1) return slopes[n - 2] ?? 0;
+    const left = slopes[i - 1] ?? 0;
+    const right = slopes[i] ?? 0;
+    return left * right <= 0 ? 0 : (left + right) / 2;
+  });
+  for (let i = 0; i < n - 1; i++) {
+    const slope = slopes[i] ?? 0;
+    if (slope === 0) {
+      tangents[i] = 0;
+      tangents[i + 1] = 0;
+      continue;
+    }
+    const a = (tangents[i] ?? 0) / slope;
+    const b = (tangents[i + 1] ?? 0) / slope;
+    const s = a * a + b * b;
+    if (s > 9) {
+      const t = 3 / Math.sqrt(s);
+      tangents[i] = t * a * slope;
+      tangents[i + 1] = t * b * slope;
+    }
+  }
+  return tangents;
+}
+
+/**
+ * Traces a monotone spline through `points`. With `baseline`, it closes the
+ * shape down to that y — the region under the line, ready to clip a fill.
+ */
+export function traceSpline(sink: PathSink, points: readonly Point[], baseline?: number): void {
+  const first = points[0];
+  const last = points[points.length - 1];
+  if (!first || !last) return;
+  const tangents = monotoneTangents(points);
+  sink.moveTo(first.x, first.y);
+  for (let i = 0; i < points.length - 1; i++) {
+    const a = points[i] as Point;
+    const b = points[i + 1] as Point;
+    const third = (b.x - a.x) / 3;
+    sink.bezierCurveTo(
+      a.x + third,
+      a.y + third * (tangents[i] ?? 0),
+      b.x - third,
+      b.y - third * (tangents[i + 1] ?? 0),
+      b.x,
+      b.y,
+    );
+  }
+  if (baseline !== undefined) {
+    sink.lineTo(last.x, baseline);
+    sink.lineTo(first.x, baseline);
+    sink.closePath();
+  }
+}
+
+/** Traces straight segments through `points`, optionally closed to a baseline. */
+export function tracePolyline(
+  sink: PathSink,
+  points: readonly Point[],
+  baseline?: number,
+): void {
+  const first = points[0];
+  const last = points[points.length - 1];
+  if (!first || !last) return;
+  sink.moveTo(first.x, first.y);
+  for (const point of points.slice(1)) sink.lineTo(point.x, point.y);
+  if (baseline !== undefined) {
+    sink.lineTo(last.x, baseline);
+    sink.lineTo(first.x, baseline);
+    sink.closePath();
+  }
+}
+
+/** Linear interpolation of a series at fractional index `at` (0..length−1). */
+export function valueAt(values: readonly number[], at: number): number {
+  if (values.length === 0) return 0;
+  const clamped = Math.min(values.length - 1, Math.max(0, at));
+  const i0 = Math.floor(clamped);
+  const i1 = Math.min(i0 + 1, values.length - 1);
+  const a = values[i0] ?? 0;
+  const b = values[i1] ?? 0;
+  return a + (b - a) * (clamped - i0);
+}
+
+/**
+ * A round axis maximum just above `value`: 1, 2 or 5 × 10ⁿ, with 5% headroom
+ * (amicro's getAxisMax). Zero and negatives give 1.
+ */
+export function niceMax(value: number): number {
+  if (!(value > 0)) return 1;
+  const target = value * 1.05;
+  const power = 10 ** Math.floor(Math.log10(target));
+  const normalized = target / power;
+  const step = normalized <= 1 ? 1 : normalized <= 2 ? 2 : normalized <= 5 ? 5 : 10;
+  return step * power;
+}