@dowel-ui/react 0.5.0 → 0.8.0

package/src/components/dither-canvas/dither-scrubber.tsx

@@ -0,0 +1,244 @@
+"use client";
+
+// Original design (pattern inspired by amicro "Dither Area Growth").
+import {
+  useCallback,
+  useState,
+  type ComponentPropsWithRef,
+  type FocusEvent,
+  type KeyboardEvent,
+  type PointerEvent,
+  type ReactNode,
+} from "react";
+
+import { focusRing } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+/*
+ * A scrubber over a series: the cursor amicro's growth chart drags with the
+ * pointer, made operable without one. The plot overlay is an APG slider whose
+ * value is a point index — arrow keys step, Page keys jump a tenth, Home/End go
+ * to the ends — so the readout a pointer reveals is also reachable by keyboard
+ * and announced through aria-valuetext.
+ */
+
+/** The index under a pointer: `clientX` across `rect`, rounded to a point. */
+export function indexFromPointer(
+  clientX: number,
+  rect: { left: number; width: number },
+  count: number,
+): number {
+  if (count <= 1 || rect.width <= 0) return 0;
+  const t = Math.min(1, Math.max(0, (clientX - rect.left) / rect.width));
+  return Math.round(t * (count - 1));
+}
+
+/** The index a key moves to, or null when the key is not a slider key. */
+export function indexFromKey(key: string, current: number, count: number): number | null {
+  const lastIndex = Math.max(0, count - 1);
+  const page = Math.max(1, Math.round(count / 10));
+  const clampTo = (value: number) => Math.min(lastIndex, Math.max(0, value));
+  switch (key) {
+    case "ArrowRight":
+    case "ArrowUp":
+      return clampTo(current + 1);
+    case "ArrowLeft":
+    case "ArrowDown":
+      return clampTo(current - 1);
+    case "PageUp":
+      return clampTo(current + page);
+    case "PageDown":
+      return clampTo(current - page);
+    case "Home":
+      return 0;
+    case "End":
+      return lastIndex;
+    default:
+      return null;
+  }
+}
+
+export interface DitherScrubberOptions {
+  /** Number of points. */
+  count: number;
+  /** Controlled cursor index; null hides the cursor. */
+  index?: number | null;
+  defaultIndex?: number | null;
+  onIndexChange?: (index: number | null) => void;
+}
+
+export interface DitherScrubberProps {
+  role: "slider";
+  tabIndex: number;
+  "aria-valuemin": number;
+  "aria-valuemax": number;
+  "aria-valuenow": number;
+  "aria-orientation": "horizontal";
+  onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+  onPointerMove: (event: PointerEvent<HTMLElement>) => void;
+  onPointerLeave: (event: PointerEvent<HTMLElement>) => void;
+  onFocus: (event: FocusEvent<HTMLElement>) => void;
+  onBlur: (event: FocusEvent<HTMLElement>) => void;
+}
+
+export interface DitherScrubber {
+  /** The cursor's point, or null when neither pointer nor focus is on the plot. */
+  index: number | null;
+  /** The point the slider reports: the cursor, or the latest point at rest. */
+  valueIndex: number;
+  setIndex: (index: number | null) => void;
+  /** Spread onto the plot overlay. Add aria-label and aria-valuetext yourself. */
+  sliderProps: DitherScrubberProps;
+}
+
+/** State and slider props for a keyboard-operable chart cursor. */
+export function useDitherScrubber({
+  count,
+  index: controlled,
+  defaultIndex = null,
+  onIndexChange,
+}: DitherScrubberOptions): DitherScrubber {
+  const [uncontrolled, setUncontrolled] = useState<number | null>(defaultIndex);
+  const isControlled = controlled !== undefined;
+  const raw = isControlled ? controlled : uncontrolled;
+  const lastIndex = Math.max(0, count - 1);
+  const index = raw === null ? null : Math.min(lastIndex, Math.max(0, raw));
+
+  const setIndex = useCallback(
+    (next: number | null) => {
+      if (!isControlled) setUncontrolled(next);
+      onIndexChange?.(next);
+    },
+    [isControlled, onIndexChange],
+  );
+
+  const valueIndex = index ?? lastIndex;
+
+  return {
+    index,
+    valueIndex,
+    setIndex,
+    sliderProps: {
+      role: "slider",
+      tabIndex: 0,
+      "aria-valuemin": 0,
+      "aria-valuemax": lastIndex,
+      "aria-valuenow": valueIndex,
+      "aria-orientation": "horizontal",
+      onKeyDown: (event) => {
+        if (event.key === "Escape" && index !== null) {
+          event.preventDefault();
+          setIndex(null);
+          return;
+        }
+        const next = indexFromKey(event.key, valueIndex, count);
+        if (next === null) return;
+        event.preventDefault();
+        if (next !== index) setIndex(next);
+      },
+      onPointerMove: (event) => {
+        const next = indexFromPointer(
+          event.clientX,
+          event.currentTarget.getBoundingClientRect(),
+          count,
+        );
+        if (next !== index) setIndex(next);
+      },
+      onPointerLeave: (event) => {
+        if (event.currentTarget.ownerDocument.activeElement !== event.currentTarget)
+          setIndex(null);
+      },
+      onFocus: () => {
+        if (index === null) setIndex(lastIndex);
+      },
+      onBlur: () => {
+        setIndex(null);
+      },
+    },
+  };
+}
+
+export interface DitherCursorProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
+  scrubber: DitherScrubber;
+  /** Names the slider, e.g. "Members by day". */
+  label: string;
+  /** What the slider announces for the current point, e.g. "Jul 3: 24". */
+  valueText: string;
+  /** Cursor position across the plot, 0..1. */
+  x: number;
+  /** Point position down the plot, 0..1 from the top; null draws no dot. */
+  y?: number | null;
+  /** Readout content, shown beside the cursor. */
+  readout?: ReactNode;
+}
+
+/**
+ * The scrubber's overlay: an invisible slider covering its positioned parent,
+ * plus the cursor line, point and readout while a point is active. All real
+ * DOM — the readout is text, not pixels. Place it after the chart's role="img"
+ * element, not inside it: a slider inside an image would be hidden.
+ */
+export function DitherCursor({
+  scrubber,
+  label,
+  valueText,
+  x,
+  y = null,
+  readout,
+  className,
+  ...props
+}: DitherCursorProps) {
+  const active = scrubber.index !== null;
+  const left = `${String(Math.min(1, Math.max(0, x)) * 100)}%`;
+  // Keep the readout inside the plot near either edge.
+  const shift = x < 0.15 ? "0%" : x > 0.85 ? "-100%" : "-50%";
+  const move =
+    "transition-[left,top,transform] duration-[var(--duration-fast)] ease-[var(--ease-out-quint)]";
+  return (
+    <>
+      <div
+        data-slot="dither-cursor"
+        aria-label={label}
+        aria-valuetext={valueText}
+        {...scrubber.sliderProps}
+        {...props}
+        className={cn(
+          "absolute inset-0 cursor-crosshair touch-pan-y rounded-md",
+          focusRing,
+          className,
+        )}
+      />
+      {active && (
+        <div aria-hidden className="pointer-events-none absolute inset-0">
+          <div
+            data-slot="dither-cursor-line"
+            className={cn("absolute inset-y-0 w-px bg-primary/70", move)}
+            style={{ left }}
+          />
+          {y !== null && (
+            <div
+              data-slot="dither-cursor-point"
+              className={cn(
+                "absolute size-3 -translate-x-1/2 -translate-y-1/2 rounded-full border-2 border-background bg-primary shadow-sm",
+                move,
+              )}
+              style={{ left, top: `${String(y * 100)}%` }}
+            />
+          )}
+          {readout !== undefined && (
+            <div
+              data-slot="dither-cursor-readout"
+              className={cn(
+                "absolute top-0 z-10 rounded-md border border-border bg-popover px-2.5 py-1.5 text-xs whitespace-nowrap text-popover-foreground shadow-md",
+                move,
+              )}
+              style={{ left, transform: `translate(${shift}, calc(-100% - 0.375rem))` }}
+            >
+              {readout}
+            </div>
+          )}
+        </div>
+      )}
+    </>
+  );
+}

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

@@ -0,0 +1,68 @@
+export {
+  DitherCanvas,
+  DitherTable,
+  formatDitherValue,
+  prefersReducedMotion,
+  useDitherCanvas,
+  useReducedMotionPreference,
+  type DitherCanvasHandle,
+  type DitherCanvasOptions,
+  type DitherCanvasProps,
+  type DitherDraw,
+  type DitherFrame,
+  type DitherTableProps,
+} from "./dither-canvas";
+export {
+  cellSquare,
+  clamp,
+  createSpring,
+  createSprings,
+  DEFAULT_SPRING,
+  DITHER_CELL,
+  DITHER_PALETTE,
+  ditherFill,
+  drift,
+  forEachCell,
+  hash2,
+  lerp,
+  resample,
+  resolveColor,
+  seriesColor,
+  shimmer,
+  smoothstep,
+  tokenToCss,
+  type DitherBounds,
+  type DitherDensity,
+  type DitherFillOptions,
+  type Spring,
+  type SpringConfig,
+  type SpringList,
+} from "./dither-engine";
+export {
+  angleInWedge,
+  makePath,
+  monotoneTangents,
+  niceMax,
+  normalizeAngle,
+  pieWedges,
+  traceRoundedRect,
+  traceRoundedWedge,
+  tracePolyline,
+  traceSpline,
+  traceWedge,
+  valueAt,
+  wedgeAt,
+  type PathSink,
+  type Point,
+  type Wedge,
+} from "./dither-geometry";
+export {
+  DitherCursor,
+  indexFromKey,
+  indexFromPointer,
+  useDitherScrubber,
+  type DitherCursorProps,
+  type DitherScrubber,
+  type DitherScrubberOptions,
+  type DitherScrubberProps,
+} from "./dither-scrubber";

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

@@ -0,0 +1,19 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "dither-canvas",
+  title: "Dither Canvas",
+  description:
+    "The engine behind the dither charts: a DPR-capped, self-pausing canvas loop, token colours, a deterministic cell hash, springs, geometry and a keyboard scrubber.",
+  category: "data",
+  status: "beta",
+  dependencies: [],
+  registryDependencies: [],
+  files: ["dither-canvas.tsx", "dither-engine.ts", "dither-geometry.ts", "dither-scrubber.tsx"],
+  a11y:
+    'The canvas is aria-hidden by default: a chart built on it names itself with role="img" and an ' +
+    "aria-label summary, and renders its values in DitherTable, which stays in the accessibility tree " +
+    "when visually hidden. useDitherScrubber gives a chart cursor APG slider semantics (arrows, Page " +
+    "keys, Home/End). The loop pauses off-screen and in hidden tabs, and under reduced motion (or " +
+    "--motion-scale near zero) draws a single static frame with springs settled.",
+});

package/src/components/dither-donut/dither-donut.tsx

@@ -0,0 +1,377 @@
+"use client";
+
+// Ported from amicro "Dither Donut Graph" and "Device Usage Donut" (MIT, © 2026 Syed Subhan Uddin). See THIRD_PARTY_NOTICES.md.
+import { cva, type VariantProps } from "class-variance-authority";
+import {
+  useRef,
+  useState,
+  type ComponentPropsWithRef,
+  type PointerEvent,
+  type ReactNode,
+} from "react";
+
+import {
+  angleInWedge,
+  createSprings,
+  DitherCanvas,
+  ditherFill,
+  DitherTable,
+  drift,
+  formatDitherValue,
+  hash2,
+  makePath,
+  pieWedges,
+  seriesColor,
+  shimmer,
+  smoothstep,
+  tokenToCss,
+  traceRoundedWedge,
+  traceWedge,
+  wedgeAt,
+  type DitherDraw,
+} from "@/components/dither-canvas";
+import { focusRing } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+/*
+ * A donut drawn in dithered cells. Two looks from amicro:
+ *
+ * - `graph` (Dither Donut Graph): rounded wedges with gaps, cells that grow
+ *   toward the outer edge, a three-sine shimmer, and the active wedge popping
+ *   outward with a scatter of highlight particles.
+ * - `flat` (Device Usage Donut): plain sectors, even cells, a two-sine drift.
+ *
+ * Shares and pop-outs are springs in the engine, so a data change morphs.
+ * Hovering a wedge or a legend entry previews it; clicking a legend entry pins
+ * it (aria-pressed). The period selector in amicro's demo is consumer UI and
+ * lives in the stories.
+ */
+
+export const ditherDonutVariants = cva("flex flex-wrap items-center gap-x-6 gap-y-4", {
+  variants: {
+    size: {
+      sm: "[--dither-donut-size:8rem]",
+      md: "[--dither-donut-size:11rem]",
+      lg: "[--dither-donut-size:14rem]",
+    },
+  },
+  defaultVariants: { size: "md" },
+});
+
+export interface DitherDonutDatum {
+  label: string;
+  value: number;
+  /** Colour token (`"primary"`) or CSS colour expression. Defaults to the palette. */
+  color?: string;
+}
+
+export interface DitherDonutLabels {
+  category?: string;
+  value?: string;
+  share?: string;
+  total?: string;
+}
+
+export interface DitherDonutProps
+  extends
+    Omit<ComponentPropsWithRef<"div">, "children">,
+    VariantProps<typeof ditherDonutVariants> {
+  data: readonly DitherDonutDatum[];
+  /** What the chart shows. Names the image, the legend and the data table. */
+  label: string;
+  /** Replaces the generated summary in the image's accessible name. */
+  description?: string;
+  variant?: "graph" | "flat";
+  /** Ring thickness as a fraction of the radius. Default 0.36. */
+  thickness?: number;
+  formatValue?: (value: number) => string;
+  /** Centre content. Defaults to the active entry, or the total; null hides it. */
+  center?: ReactNode;
+  showLegend?: boolean;
+  /** Show the data table. It is always present for assistive technology. */
+  showTable?: boolean;
+  /** Run the shimmer. Reduced motion stops it regardless. */
+  animate?: boolean;
+  cell?: number;
+  /** The pinned entry (controlled). */
+  activeIndex?: number | null;
+  defaultActiveIndex?: number | null;
+  onActiveIndexChange?: (index: number | null) => void;
+  labels?: DitherDonutLabels;
+}
+
+const PERCENT = new Intl.NumberFormat(undefined, {
+  style: "percent",
+  maximumFractionDigits: 0,
+});
+
+function donutLayout(width: number, height: number, thickness: number, graph: boolean) {
+  const size = Math.min(width, height);
+  const pop = graph ? size * 0.03 : 0;
+  const outer = Math.max(0, size / 2 - pop - 1);
+  return {
+    center: { x: width / 2, y: height / 2 },
+    outer,
+    inner: outer * (1 - Math.min(0.9, Math.max(0.1, thickness))),
+    pop,
+  };
+}
+
+export function DitherDonut({
+  data,
+  label,
+  description,
+  variant = "graph",
+  size,
+  thickness = 0.36,
+  formatValue = formatDitherValue,
+  center,
+  showLegend = true,
+  showTable = false,
+  animate = true,
+  cell,
+  activeIndex,
+  defaultActiveIndex = null,
+  onActiveIndexChange,
+  labels,
+  className,
+  ...props
+}: DitherDonutProps) {
+  const [uncontrolled, setUncontrolled] = useState<number | null>(defaultActiveIndex);
+  const [preview, setPreview] = useState<number | null>(null);
+  const pinned = activeIndex !== undefined ? activeIndex : uncontrolled;
+  const active = preview ?? pinned;
+
+  const graph = variant === "graph";
+  const values = data.map((datum) => (datum.value > 0 ? datum.value : 0));
+  const total = values.reduce((sum, value) => sum + value, 0);
+  const targets = values.map((value) => (total > 0 ? value / total : 0));
+
+  const shares = useRef(createSprings(targets));
+  const pops = useRef(
+    createSprings(
+      targets.map(() => 0),
+      { stiffness: 320, damping: 24 },
+    ),
+  );
+
+  const pin = (index: number) => {
+    const next = pinned === index ? null : index;
+    if (activeIndex === undefined) setUncontrolled(next);
+    onActiveIndexChange?.(next);
+  };
+
+  const draw: DitherDraw = (ctx, frame) => {
+    const { width, height, time, animated } = frame;
+    const step = frame.cell;
+    const { center: c, outer, inner, pop } = donutLayout(width, height, thickness, graph);
+    shares.current.set(targets);
+    pops.current.set(targets.map((_, index) => (index === active ? 1 : 0)));
+    const sharesMoving = shares.current.step(frame.delta, frame.reducedMotion);
+    const moving = pops.current.step(frame.delta, frame.reducedMotion) || sharesMoving;
+    const popped = pops.current.values;
+    const t = time * 1.2;
+    const bounds = {
+      x: c.x - outer - step,
+      y: c.y - outer - step,
+      width: 2 * (outer + step),
+      height: 2 * (outer + step),
+    };
+
+    for (const wedge of pieWedges(shares.current.values, { gap: graph ? 0.07 : 0 })) {
+      if (wedge.share <= 0 || wedge.end <= wedge.start) continue;
+      const { index, start, end, mid } = wedge;
+      const isActive = index === active;
+      const lift = pop * (popped[index] ?? 0);
+      ctx.save();
+      ctx.translate(Math.cos(mid) * lift, Math.sin(mid) * lift);
+      const clip = makePath((sink) => {
+        if (graph) traceRoundedWedge(sink, c, inner, outer, start, end, 6);
+        else traceWedge(sink, c, inner, outer, start, end);
+      });
+      const inside = (cx: number, cy: number) => {
+        const distance = Math.hypot(cx - c.x, cy - c.y);
+        return (
+          distance >= inner - step &&
+          distance <= outer + step &&
+          angleInWedge(Math.atan2(cy - c.y, cx - c.x), start, end)
+        );
+      };
+      ditherFill(ctx, {
+        clip,
+        bounds,
+        cell: step,
+        color: frame.color(seriesColor(index, data[index]?.color)),
+        alpha: isActive ? 1 : active !== null ? 0.3 : graph ? 0.78 : 0.85,
+        density: (cx, cy) => {
+          if (!inside(cx, cy)) return 0;
+          const jitter = hash2(cx, cy);
+          if (!graph)
+            return (0.4 + 0.4 * (animated ? drift(cx, cy, t) : 0.5)) * (0.8 + 0.4 * jitter);
+          const dx = cx - c.x;
+          const dy = cy - c.y;
+          const distance = Math.hypot(dx, dy);
+          const fullness = smoothstep(0.62, 1, (distance - inner) / Math.max(1, outer - inner));
+          const wave = animated
+            ? shimmer(
+                Math.sin(distance * 0.1 - t),
+                Math.sin(Math.atan2(dy, dx) * 3 + t * 1.5),
+                Math.sin((dx + dy) * 0.05 + t * 2),
+              )
+            : 0.5;
+          return (
+            ((isActive ? 0.46 : 0.34) + 0.36 * fullness + 0.26 * wave) * (0.78 + 0.42 * jitter)
+          );
+        },
+      });
+      if (isActive) {
+        // Highlight particles: a sparse second layer, re-seeded a few times a
+        // second while animating, still under reduced motion.
+        const seed = animated ? 1 + Math.floor(time * 6) : 1;
+        ditherFill(ctx, {
+          clip,
+          bounds,
+          cell: step,
+          color: frame.color("foreground"),
+          alpha: 0.9,
+          density: (cx, cy) => (inside(cx, cy) && hash2(cx, cy, seed) > 0.92 ? 0.8 : 0),
+        });
+      }
+      ctx.restore();
+    }
+    return moving;
+  };
+
+  const onPointerMove = (event: PointerEvent<HTMLDivElement>) => {
+    const rect = event.currentTarget.getBoundingClientRect();
+    const layout = donutLayout(rect.width, rect.height, thickness, graph);
+    const hit = wedgeAt(
+      pieWedges(targets, { gap: graph ? 0.07 : 0 }),
+      layout.center,
+      layout.inner,
+      layout.outer + layout.pop,
+      { x: event.clientX - rect.left, y: event.clientY - rect.top },
+    );
+    if (hit !== preview) setPreview(hit);
+  };
+
+  const share = (index: number) => PERCENT.format(targets[index] ?? 0);
+  const summary =
+    description ??
+    `${data.map((datum, index) => `${datum.label} ${formatValue(datum.value)} (${share(index)})`).join(", ")}. ${labels?.total ?? "Total"} ${formatValue(total)}.`;
+  const activeDatum = active !== null ? data[active] : undefined;
+
+  const readout =
+    center !== undefined ? (
+      center
+    ) : (
+      <>
+        <span className="text-xs text-muted-foreground">
+          {activeDatum?.label ?? labels?.total ?? "Total"}
+        </span>
+        <span className="text-lg font-semibold text-foreground tabular-nums">
+          {formatValue(activeDatum ? activeDatum.value : total)}
+        </span>
+        {activeDatum && (
+          <span className="text-xs text-muted-foreground tabular-nums">
+            {share(active ?? 0)}
+          </span>
+        )}
+      </>
+    );
+
+  return (
+    <div
+      data-slot="dither-donut"
+      data-variant={variant}
+      {...props}
+      className={cn(ditherDonutVariants({ size }), className)}
+    >
+      <div
+        data-slot="dither-donut-plot"
+        className="relative size-[var(--dither-donut-size)] shrink-0"
+      >
+        <div
+          role="img"
+          aria-label={`${label}: ${summary}`}
+          className="size-full"
+          onPointerMove={onPointerMove}
+          onPointerLeave={() => {
+            setPreview(null);
+          }}
+        >
+          <DitherCanvas draw={draw} animate={animate} cell={cell} />
+        </div>
+        {readout !== null && (
+          <div
+            data-slot="dither-donut-readout"
+            className="pointer-events-none absolute inset-0 flex flex-col items-center justify-center text-center leading-tight"
+          >
+            {readout}
+          </div>
+        )}
+      </div>
+      {showLegend && (
+        <ul
+          data-slot="dither-donut-legend"
+          aria-label={label}
+          className="flex min-w-0 flex-1 flex-col gap-1"
+        >
+          {data.map((datum, index) => (
+            <li key={`${datum.label}-${String(index)}`}>
+              <button
+                type="button"
+                aria-pressed={pinned === index}
+                aria-label={`${datum.label}: ${formatValue(datum.value)} (${share(index)})`}
+                data-active={active === index || undefined}
+                className={cn(
+                  "flex w-full items-center gap-2.5 rounded-md px-2 py-1.5 text-xs transition-colors duration-[var(--duration-fast)] ease-[var(--ease-out-quint)] hover:bg-muted aria-pressed:bg-accent aria-pressed:text-accent-foreground data-active:bg-muted",
+                  focusRing,
+                )}
+                onPointerEnter={() => {
+                  setPreview(index);
+                }}
+                onPointerLeave={() => {
+                  setPreview(null);
+                }}
+                onFocus={() => {
+                  setPreview(index);
+                }}
+                onBlur={() => {
+                  setPreview(null);
+                }}
+                onClick={() => {
+                  pin(index);
+                }}
+              >
+                <span
+                  aria-hidden
+                  className="size-2.5 shrink-0 rounded-full"
+                  style={{ background: tokenToCss(seriesColor(index, datum.color)) }}
+                />
+                <span className="min-w-0 flex-1 truncate text-start font-medium text-foreground">
+                  {datum.label}
+                </span>
+                <span className="text-foreground tabular-nums">{formatValue(datum.value)}</span>
+                <span className="w-9 text-end font-mono text-2xs text-muted-foreground">
+                  {share(index)}
+                </span>
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+      <DitherTable
+        caption={label}
+        columns={[
+          labels?.category ?? "Category",
+          labels?.value ?? "Value",
+          labels?.share ?? "Share",
+        ]}
+        rows={data.map((datum, index) => [datum.label, formatValue(datum.value), share(index)])}
+        visible={showTable}
+        className={showTable ? "basis-full" : undefined}
+      />
+    </div>
+  );
+}