@dowel-ui/react 0.5.0 → 0.8.0

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

@@ -0,0 +1,7 @@
+export {
+  DitherDonut,
+  ditherDonutVariants,
+  type DitherDonutDatum,
+  type DitherDonutLabels,
+  type DitherDonutProps,
+} from "./dither-donut";

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

@@ -0,0 +1,19 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "dither-donut",
+  title: "Dither Donut",
+  description:
+    "A donut chart drawn in shimmering dithered cells, with wedges that pop out and sparkle on hover, focus or pin.",
+  category: "data",
+  status: "beta",
+  dependencies: ["class-variance-authority"],
+  registryDependencies: ["dither-canvas"],
+  files: ["dither-donut.tsx"],
+  a11y:
+    'The plot is role="img" with an aria-label summarising every entry, its share and the total. ' +
+    "Legend entries are buttons named with their value and share: focus or hover previews a wedge, " +
+    "and pressing pins it (aria-pressed). The data is always in a table, visually hidden unless " +
+    "showTable is set. The readout is real text. Under reduced motion the shimmer stops and data " +
+    "changes settle in one frame.",
+});

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

@@ -0,0 +1,273 @@
+"use client";
+
+// Ported from amicro "Conversion Funnel" (MIT, © 2026 Syed Subhan Uddin). See THIRD_PARTY_NOTICES.md.
+import { cva, type VariantProps } from "class-variance-authority";
+import { useRef, useState, type ComponentPropsWithRef } from "react";
+
+import {
+  createSprings,
+  DitherCanvas,
+  ditherFill,
+  DitherTable,
+  drift,
+  formatDitherValue,
+  hash2,
+  makePath,
+  seriesColor,
+  traceRoundedRect,
+  type DitherDraw,
+} from "@/components/dither-canvas";
+import { focusRing } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+/*
+ * A conversion funnel drawn in dithered cells: one bar per stage, its length
+ * the stage's value against the first (or `max`), stepping down amicro's
+ * monochrome ramp. Lengths are springs in the engine, so a new period morphs.
+ *
+ * Every stage is a button laid over its bar, showing the stage name and its
+ * conversion, named with the full breakdown — value, share of the first stage,
+ * step conversion from the previous and how many dropped. Hover or focus
+ * lights the stage and fills the readout; pressing pins it. Bars grow from the
+ * start edge in LTR in every direction: the canvas does not mirror.
+ */
+
+export const ditherFunnelVariants = cva("flex flex-col gap-2", {
+  variants: {
+    size: {
+      sm: "[--dither-funnel-height:7rem]",
+      md: "[--dither-funnel-height:10rem]",
+      lg: "[--dither-funnel-height:14rem]",
+    },
+  },
+  defaultVariants: { size: "md" },
+});
+
+export interface DitherFunnelStage {
+  label: string;
+  value: number;
+  /** Colour token or CSS colour expression. Defaults to the palette. */
+  color?: string;
+}
+
+export interface DitherFunnelProps
+  extends
+    Omit<ComponentPropsWithRef<"div">, "children">,
+    VariantProps<typeof ditherFunnelVariants> {
+  stages: readonly DitherFunnelStage[];
+  /** What the funnel shows. Names the image, the stages and the data table. */
+  label: string;
+  /** Replaces the generated summary in the image's accessible name. */
+  description?: string;
+  /** Value of a full-length bar. Defaults to the largest stage. */
+  max?: number;
+  formatValue?: (value: number) => string;
+  /** Formats a 0..1 share. Defaults to a whole percentage. */
+  formatPercent?: (share: number) => string;
+  /** Show the data table. It is always present for assistive technology. */
+  showTable?: boolean;
+  animate?: boolean;
+  cell?: number;
+  /** The pinned stage (controlled); null pins none. */
+  activeStage?: number | null;
+  defaultActiveStage?: number | null;
+  onActiveStageChange?: (index: number | null) => void;
+  /** Data table headers. */
+  categoryLabel?: string;
+  valueLabel?: string;
+  conversionLabel?: string;
+  stepLabel?: string;
+}
+
+/** Gap between stage bars in CSS pixels, shared by the canvas and the buttons. */
+export const FUNNEL_GAP = 6;
+
+export interface FunnelConversion {
+  /** Share of the first stage, 0..1. */
+  overall: number;
+  /** Share of the previous stage, 0..1 (1 for the first). */
+  step: number;
+  /** How many the previous stage lost on the way here (0 for the first). */
+  dropped: number;
+}
+
+const clean = (value: number) => (Number.isFinite(value) && value > 0 ? value : 0);
+
+/** Overall and step conversion for each stage. */
+export function funnelConversions(stages: readonly DitherFunnelStage[]): FunnelConversion[] {
+  const first = clean(stages[0]?.value ?? 0);
+  return stages.map((stage, i) => {
+    const value = clean(stage.value);
+    const previous = i === 0 ? value : clean(stages[i - 1]?.value ?? 0);
+    return {
+      overall: first > 0 ? value / first : 0,
+      step: previous > 0 ? value / previous : 0,
+      dropped: i === 0 ? 0 : Math.max(0, previous - value),
+    };
+  });
+}
+
+const wholePercent = (share: number) => `${String(Math.round(share * 100))}%`;
+
+export function DitherFunnel({
+  stages,
+  label,
+  description,
+  max,
+  size,
+  formatValue = formatDitherValue,
+  formatPercent = wholePercent,
+  showTable = false,
+  animate = true,
+  cell = 3,
+  activeStage,
+  defaultActiveStage = null,
+  onActiveStageChange,
+  categoryLabel = "Stage",
+  valueLabel = "Value",
+  conversionLabel = "Conversion",
+  stepLabel = "Step conversion",
+  className,
+  ...props
+}: DitherFunnelProps) {
+  const [uncontrolled, setUncontrolled] = useState<number | null>(defaultActiveStage);
+  const [preview, setPreview] = useState<number | null>(null);
+  const pinned = activeStage !== undefined ? activeStage : uncontrolled;
+  const lit = preview ?? pinned;
+  const values = stages.map((stage) => clean(stage.value));
+  const top = max ?? Math.max(0, ...values);
+  const fractions = values.map((value) => (top > 0 ? Math.min(1, value / top) : 0));
+  const conversions = funnelConversions(stages);
+  const bars = useRef(createSprings(fractions.map(() => 0)));
+
+  const draw: DitherDraw = (ctx, frame) => {
+    const { width, height, time } = frame;
+    bars.current.set(fractions);
+    const moving = bars.current.step(frame.delta, frame.reducedMotion);
+    const current = bars.current.values;
+    const count = current.length;
+    if (count === 0) return moving;
+    const rowHeight = (height - FUNNEL_GAP * (count - 1)) / count;
+    if (rowHeight <= 0) return moving;
+    current.forEach((fraction, i) => {
+      const barWidth = Math.max(0, Math.min(1, fraction)) * width;
+      if (barWidth < 1) return;
+      const y = i * (rowHeight + FUNNEL_GAP);
+      ditherFill(ctx, {
+        clip: makePath((sink) => {
+          traceRoundedRect(sink, 0, y, barWidth, rowHeight, 4);
+        }),
+        bounds: { x: 0, y, width: barWidth, height: rowHeight },
+        cell: frame.cell,
+        color: frame.color(seriesColor(i, stages[i]?.color)),
+        alpha: lit !== null && lit !== i ? 0.3 : 0.85,
+        density: (cx, cy) =>
+          (0.35 + 0.35 * drift(cx, cy, time * 1.2)) * (0.8 + 0.4 * hash2(cx, cy)) +
+          (lit === i ? 0.15 : 0),
+      });
+    });
+    return moving;
+  };
+
+  const pin = (index: number) => {
+    const next = pinned === index ? null : index;
+    if (activeStage === undefined) setUncontrolled(next);
+    onActiveStageChange?.(next);
+  };
+
+  const first = stages[0];
+  const breakdown = (i: number) => {
+    const stage = stages[i];
+    const conversion = conversions[i];
+    if (!stage || !conversion) return "";
+    const head = `${stage.label}: ${formatValue(values[i] ?? 0)}`;
+    if (i === 0) return head;
+    const previous = stages[i - 1]?.label ?? "";
+    return (
+      `${head}, ${formatPercent(conversion.overall)} of ${first?.label ?? ""}, ` +
+      `${formatPercent(conversion.step)} from ${previous}, ${formatValue(conversion.dropped)} dropped`
+    );
+  };
+  const summary =
+    description ??
+    (stages.length === 0
+      ? "No data."
+      : `${String(stages.length)} stages. ${stages.map((_, i) => breakdown(i)).join("; ")}.`);
+
+  return (
+    <div
+      data-slot="dither-funnel"
+      {...props}
+      className={cn(ditherFunnelVariants({ size }), className)}
+    >
+      <div
+        data-slot="dither-funnel-plot"
+        className="relative h-[var(--dither-funnel-height)]"
+        style={{ direction: "ltr" }}
+      >
+        <div role="img" aria-label={`${label}: ${summary}`} className="size-full">
+          <DitherCanvas draw={draw} animate={animate} cell={cell} />
+        </div>
+        <ul
+          aria-label={label}
+          className="absolute inset-0 flex flex-col"
+          style={{ gap: `${String(FUNNEL_GAP)}px` }}
+        >
+          {stages.map((stage, i) => (
+            <li key={`${stage.label}-${String(i)}`} className="flex min-h-0 flex-1">
+              <button
+                type="button"
+                aria-pressed={pinned === i}
+                aria-label={breakdown(i)}
+                data-active={lit === i || undefined}
+                className={cn(
+                  "flex flex-1 items-center justify-between gap-2 rounded-md px-1.5 text-xs font-medium",
+                  focusRing,
+                )}
+                onPointerEnter={() => {
+                  setPreview(i);
+                }}
+                onPointerLeave={() => {
+                  setPreview(null);
+                }}
+                onFocus={() => {
+                  setPreview(i);
+                }}
+                onBlur={() => {
+                  setPreview(null);
+                }}
+                onClick={() => {
+                  pin(i);
+                }}
+              >
+                <span className="truncate rounded-sm bg-background/80 px-1 text-foreground">
+                  {stage.label}
+                </span>
+                <span className="rounded-sm bg-background/80 px-1 text-muted-foreground tabular-nums">
+                  {formatPercent(conversions[i]?.overall ?? 0)}
+                </span>
+              </button>
+            </li>
+          ))}
+        </ul>
+      </div>
+      <p
+        data-slot="dither-funnel-readout"
+        className="min-h-4 text-xs text-muted-foreground tabular-nums"
+      >
+        {lit !== null && stages[lit] ? breakdown(lit) : null}
+      </p>
+      <DitherTable
+        caption={label}
+        columns={[categoryLabel, valueLabel, conversionLabel, stepLabel]}
+        rows={stages.map((stage, i) => [
+          stage.label,
+          formatValue(values[i] ?? 0),
+          formatPercent(conversions[i]?.overall ?? 0),
+          formatPercent(conversions[i]?.step ?? 0),
+        ])}
+        visible={showTable}
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,9 @@
+export {
+  DitherFunnel,
+  ditherFunnelVariants,
+  FUNNEL_GAP,
+  funnelConversions,
+  type DitherFunnelProps,
+  type DitherFunnelStage,
+  type FunnelConversion,
+} from "./dither-funnel";

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

@@ -0,0 +1,19 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "dither-funnel",
+  title: "Dither Funnel",
+  description:
+    "A conversion funnel of dithered stage bars that morph between periods, with overall and step conversion per stage.",
+  category: "data",
+  status: "beta",
+  dependencies: ["class-variance-authority"],
+  registryDependencies: ["dither-canvas"],
+  files: ["dither-funnel.tsx"],
+  a11y:
+    'The bars are role="img" with an aria-label giving every stage\'s value and conversion. Each ' +
+    "stage is a button over its bar, showing its name and overall conversion and named with the " +
+    "full breakdown (share of the first stage, step conversion, drop-off); hover or focus fills " +
+    "the text readout and pressing pins it (aria-pressed). The data is always in a table, visually " +
+    "hidden unless showTable is set.",
+});

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

@@ -0,0 +1,279 @@
+"use client";
+
+// Ported from amicro "Server CPU Gauge" (MIT, © 2026 Syed Subhan Uddin). See THIRD_PARTY_NOTICES.md.
+import { cva, type VariantProps } from "class-variance-authority";
+import { useRef, useState, type ComponentPropsWithRef } from "react";
+
+import {
+  createSprings,
+  DitherCanvas,
+  ditherFill,
+  DitherTable,
+  drift,
+  hash2,
+  makePath,
+  seriesColor,
+  tokenToCss,
+  traceWedge,
+  type DitherDraw,
+} from "@/components/dither-canvas";
+import { focusRing } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+/*
+ * A half-circle gauge drawn in dithered cells, one ring per metric — amicro's
+ * server gauge with its CPU / memory / network switch. The outer ring is the
+ * first metric. Each fill is a spring in the engine (amicro's 120 / 20), so a
+ * new reading sweeps rather than jumps.
+ *
+ * The reading in the centre is a real role="meter" with aria-valuenow, min and
+ * max. With several metrics, legend buttons preview a ring on hover or focus
+ * (the rest dim) and pick the one the centre reads when pressed. amicro wobbled
+ * the drawn value a few percent with a timer; a gauge that shows a reading it
+ * was not given is lying, so here only the cells shimmer.
+ */
+
+export const ditherGaugeVariants = cva("flex flex-col items-center gap-3", {
+  variants: {
+    size: {
+      sm: "[--dither-gauge-height:6rem]",
+      md: "[--dither-gauge-height:8.5rem]",
+      lg: "[--dither-gauge-height:11rem]",
+    },
+  },
+  defaultVariants: { size: "md" },
+});
+
+export interface DitherGaugeMetric {
+  key: string;
+  label: string;
+  value: number;
+  /** Full-scale value. Default 100. */
+  max?: number;
+  /** Colour token or CSS colour expression. Defaults to the palette. */
+  color?: string;
+}
+
+export interface DitherGaugeProps
+  extends
+    Omit<ComponentPropsWithRef<"div">, "children">,
+    VariantProps<typeof ditherGaugeVariants> {
+  metrics: readonly DitherGaugeMetric[];
+  /** What the gauge shows. Names the image and the data table. */
+  label: string;
+  /** Replaces the generated summary in the image's accessible name. */
+  description?: string;
+  /** Formats a reading. Defaults to the share of `max` as a whole percentage. */
+  formatValue?: (value: number, metric: DitherGaugeMetric) => string;
+  /** Show the metric buttons (only drawn with more than one metric). */
+  showLegend?: boolean;
+  /** Show the data table. It is always present for assistive technology. */
+  showTable?: boolean;
+  animate?: boolean;
+  cell?: number;
+  /** The metric the centre reads (controlled). Defaults to the first. */
+  activeMetric?: string;
+  defaultActiveMetric?: string;
+  onActiveMetricChange?: (key: string) => void;
+  /** Data table headers. */
+  categoryLabel?: string;
+  valueLabel?: string;
+}
+
+/** A reading's share of its scale, clamped to 0..1. */
+export function gaugeFraction(metric: DitherGaugeMetric): number {
+  const max = metric.max ?? 100;
+  if (!(max > 0) || !Number.isFinite(metric.value)) return 0;
+  return Math.min(1, Math.max(0, metric.value / max));
+}
+
+/** Ring radii for `count` concentric rings inside `outer`. */
+export function gaugeRings(outer: number, count: number): { inner: number; outer: number }[] {
+  const band = Math.max(5, outer * (count > 1 ? 0.11 : 0.14));
+  const gap = Math.max(2, band * 0.4);
+  return Array.from({ length: count }, (_, i) => {
+    const ringOuter = outer - i * (band + gap);
+    return { outer: ringOuter, inner: Math.max(0, ringOuter - band) };
+  });
+}
+
+const percent = (value: number, metric: DitherGaugeMetric) =>
+  `${String(Math.round(gaugeFraction({ ...metric, value }) * 100))}%`;
+
+export function DitherGauge({
+  metrics,
+  label,
+  description,
+  size,
+  formatValue = percent,
+  showLegend = true,
+  showTable = false,
+  animate = true,
+  cell = 3,
+  activeMetric,
+  defaultActiveMetric,
+  onActiveMetricChange,
+  categoryLabel = "Metric",
+  valueLabel = "Reading",
+  className,
+  ...props
+}: DitherGaugeProps) {
+  const [uncontrolled, setUncontrolled] = useState(defaultActiveMetric ?? metrics[0]?.key);
+  const [preview, setPreview] = useState<number | null>(null);
+  const chosenKey = activeMetric ?? uncontrolled;
+  const chosen = Math.max(
+    0,
+    metrics.findIndex((metric) => metric.key === chosenKey),
+  );
+  const shown = preview ?? chosen;
+  const fractions = metrics.map(gaugeFraction);
+  const fills = useRef(
+    createSprings(
+      fractions.map(() => 0),
+      { stiffness: 120, damping: 20, mass: 1 },
+    ),
+  );
+
+  const draw: DitherDraw = (ctx, frame) => {
+    const { width, height, time } = frame;
+    fills.current.set(fractions);
+    const moving = fills.current.step(frame.delta, frame.reducedMotion);
+    const current = fills.current.values;
+    const center = { x: width / 2, y: height * 0.94 };
+    const outer = Math.min(width * 0.47, height * 0.88);
+    const rings = gaugeRings(outer, metrics.length);
+    rings.forEach((ring, i) => {
+      if (ring.inner <= 0) return;
+      // The track: a solid, faint half ring.
+      ctx.save();
+      ctx.beginPath();
+      traceWedge(ctx, center, ring.inner, ring.outer, Math.PI, Math.PI * 2);
+      ctx.fillStyle = frame.color("foreground");
+      ctx.globalAlpha = 0.1;
+      ctx.fill();
+      ctx.restore();
+
+      const fraction = Math.min(1, Math.max(0, current[i] ?? 0));
+      if (fraction <= 0.001) return;
+      const end = Math.PI + fraction * Math.PI;
+      const dim = preview !== null && preview !== i;
+      ditherFill(ctx, {
+        clip: makePath((sink) => {
+          traceWedge(sink, center, ring.inner, ring.outer, Math.PI, end);
+        }),
+        bounds: {
+          x: center.x - ring.outer,
+          y: center.y - ring.outer,
+          width: ring.outer * 2,
+          height: ring.outer,
+        },
+        cell: frame.cell,
+        color: frame.color(seriesColor(i, metrics[i]?.color)),
+        alpha: dim ? 0.3 : 0.9,
+        density: (cx, cy) =>
+          (0.4 + 0.4 * drift(cx, cy, time * 3)) * (0.8 + 0.4 * hash2(cx, cy)) +
+          (preview === i ? 0.15 : 0),
+      });
+    });
+    return moving;
+  };
+
+  const choose = (index: number) => {
+    const key = metrics[index]?.key;
+    if (key === undefined) return;
+    if (activeMetric === undefined) setUncontrolled(key);
+    onActiveMetricChange?.(key);
+  };
+
+  const reading = (metric: DitherGaugeMetric) => formatValue(metric.value, metric);
+  const summary =
+    description ??
+    (metrics.length === 0
+      ? "No data."
+      : `${metrics.map((metric) => `${metric.label} ${reading(metric)}`).join(", ")}.`);
+  const metric = metrics[shown];
+
+  return (
+    <div
+      data-slot="dither-gauge"
+      {...props}
+      className={cn(ditherGaugeVariants({ size }), className)}
+    >
+      <div
+        data-slot="dither-gauge-plot"
+        className="relative h-[var(--dither-gauge-height)] w-full"
+        style={{ direction: "ltr" }}
+      >
+        <div role="img" aria-label={`${label}: ${summary}`} className="size-full">
+          <DitherCanvas draw={draw} animate={animate} cell={cell} />
+        </div>
+        {metric && (
+          <div
+            role="meter"
+            data-slot="dither-gauge-reading"
+            aria-label={metric.label}
+            aria-valuemin={0}
+            aria-valuemax={metric.max ?? 100}
+            aria-valuenow={Math.min(metric.max ?? 100, Math.max(0, metric.value))}
+            aria-valuetext={reading(metric)}
+            className="absolute inset-x-0 bottom-0 flex flex-col items-center"
+          >
+            <span className="text-2xl leading-none font-semibold tabular-nums">
+              {reading(metric)}
+            </span>
+            <span className="mt-1 text-2xs text-muted-foreground">{metric.label}</span>
+          </div>
+        )}
+      </div>
+      {showLegend && metrics.length > 1 && (
+        <ul
+          data-slot="dither-gauge-legend"
+          aria-label={`${label} metrics`}
+          className="flex flex-wrap justify-center gap-1"
+        >
+          {metrics.map((entry, index) => (
+            <li key={entry.key}>
+              <button
+                type="button"
+                aria-pressed={chosen === index}
+                data-active={preview === index || undefined}
+                className={cn(
+                  "flex items-center gap-1.5 rounded-md px-2 py-1 text-xs font-medium text-muted-foreground transition-colors duration-[var(--duration-fast)] ease-[var(--ease-out-quint)] hover:text-foreground aria-pressed:bg-accent aria-pressed:text-accent-foreground data-active:text-foreground",
+                  focusRing,
+                )}
+                onPointerEnter={() => {
+                  setPreview(index);
+                }}
+                onPointerLeave={() => {
+                  setPreview(null);
+                }}
+                onFocus={() => {
+                  setPreview(index);
+                }}
+                onBlur={() => {
+                  setPreview(null);
+                }}
+                onClick={() => {
+                  choose(index);
+                }}
+              >
+                <span
+                  aria-hidden
+                  className="size-2.5 rounded-full"
+                  style={{ background: tokenToCss(seriesColor(index, entry.color)) }}
+                />
+                {entry.label} <span className="tabular-nums">{reading(entry)}</span>
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+      <DitherTable
+        caption={label}
+        columns={[categoryLabel, valueLabel]}
+        rows={metrics.map((entry) => [entry.label, reading(entry)])}
+        visible={showTable}
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,8 @@
+export {
+  DitherGauge,
+  ditherGaugeVariants,
+  gaugeFraction,
+  gaugeRings,
+  type DitherGaugeMetric,
+  type DitherGaugeProps,
+} from "./dither-gauge";

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

@@ -0,0 +1,19 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "dither-gauge",
+  title: "Dither Gauge",
+  description:
+    "A half-circle gauge drawn in dithered cells, one sweeping ring per metric, with a centre reading and metric switch.",
+  category: "data",
+  status: "beta",
+  dependencies: ["class-variance-authority"],
+  registryDependencies: ["dither-canvas"],
+  files: ["dither-gauge.tsx"],
+  a11y:
+    'The rings are role="img" with an aria-label listing every metric\'s reading. The centre ' +
+    'reading is a role="meter" with aria-valuemin, aria-valuemax, aria-valuenow and a formatted ' +
+    "aria-valuetext. With several metrics, legend buttons (named with label and reading) preview a " +
+    "ring on hover or focus and choose the centre's metric when pressed (aria-pressed). The data is " +
+    "always in a table, visually hidden unless showTable is set.",
+});