@dowel-ui/react 0.7.0 → 0.8.0

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

@@ -0,0 +1,244 @@
+"use client";
+
+// Ported from amicro "Revenue Spline Line" (MIT, © 2026 Syed Subhan Uddin). See THIRD_PARTY_NOTICES.md.
+import { cva, type VariantProps } from "class-variance-authority";
+import { useRef, type ComponentPropsWithRef } from "react";
+
+import {
+  createSprings,
+  DitherCanvas,
+  DitherCursor,
+  ditherFill,
+  DitherTable,
+  drift,
+  formatDitherValue,
+  hash2,
+  makePath,
+  traceSpline,
+  useDitherScrubber,
+  type DitherDraw,
+} from "@/components/dither-canvas";
+import { cn } from "@/lib/utils";
+
+/*
+ * A smooth line over a dithered gradient fill: cells are largest just under
+ * the top of the plot and thin out toward the baseline, drifting on a two-sine
+ * wave. amicro drew straight segments; this one is the spline its name
+ * promised — monotone, so it never overshoots between two points and invents a
+ * dip the data does not have. The same keyboard scrubber as DitherArea reads
+ * out each point.
+ */
+
+export const ditherLineVariants = cva("flex flex-col gap-2", {
+  variants: {
+    size: {
+      sm: "[--dither-line-height:7.5rem]",
+      md: "[--dither-line-height:11.25rem]",
+      lg: "[--dither-line-height:16rem]",
+    },
+  },
+  defaultVariants: { size: "md" },
+});
+
+export interface DitherLineDatum {
+  label: string;
+  value: number;
+}
+
+export interface DitherLineProps
+  extends
+    Omit<ComponentPropsWithRef<"div">, "children">,
+    VariantProps<typeof ditherLineVariants> {
+  data: readonly DitherLineDatum[];
+  /** What the chart shows. Names the image, the scrubber and the data table. */
+  label: string;
+  /** Replaces the generated summary in the image's accessible name. */
+  description?: string;
+  /** Axis maximum. Defaults to the largest value plus 20% headroom. */
+  max?: number;
+  formatValue?: (value: number) => string;
+  /** Colour token or CSS colour expression for the line and fill. Default "primary". */
+  color?: string;
+  /** Show point labels under the plot. */
+  showAxis?: boolean;
+  /** Show the data table. It is always present for assistive technology. */
+  showTable?: boolean;
+  animate?: boolean;
+  cell?: number;
+  index?: number | null;
+  defaultIndex?: number | null;
+  onIndexChange?: (index: number | null) => void;
+  categoryLabel?: string;
+  valueLabel?: string;
+}
+
+/** Distance from the top, 0..1, keeping half a stroke clear of each edge. */
+export function lineY(value: number, max: number, height: number, stroke = 2): number {
+  const inset = height > 0 ? stroke / height : 0;
+  const fraction = max > 0 ? Math.min(1, Math.max(0, value) / max) : 0;
+  return inset + (1 - 2 * inset) * (1 - fraction);
+}
+
+function lineX(index: number, count: number): number {
+  return count <= 1 ? 0.5 : index / (count - 1);
+}
+
+/** Which points get an axis label: every one up to 8, else about 5 spread evenly. */
+export function axisIndices(count: number): number[] {
+  if (count <= 8) return Array.from({ length: count }, (_, i) => i);
+  return [0, 0.25, 0.5, 0.75, 1].map((t) => Math.round(t * (count - 1)));
+}
+
+export function DitherLine({
+  data,
+  label,
+  description,
+  max,
+  size,
+  formatValue = formatDitherValue,
+  color = "primary",
+  showAxis = true,
+  showTable = false,
+  animate = true,
+  cell,
+  index,
+  defaultIndex,
+  onIndexChange,
+  categoryLabel = "Point",
+  valueLabel = "Value",
+  className,
+  ...props
+}: DitherLineProps) {
+  const count = data.length;
+  const scrubber = useDitherScrubber({ count, index, defaultIndex, onIndexChange });
+  const values = data.map((datum) =>
+    Number.isFinite(datum.value) ? Math.max(0, datum.value) : 0,
+  );
+  const top = max ?? Math.max(1, ...values) * 1.2;
+  const shape = useRef(createSprings(values.map(() => 0)));
+
+  const draw: DitherDraw = (ctx, frame) => {
+    const { width, height, time, animated } = frame;
+    const step = frame.cell;
+    shape.current.set(values.map((value) => value / top));
+    const moving = shape.current.step(frame.delta, frame.reducedMotion);
+    const current = shape.current.values;
+    const points = current.map((fraction, i) => ({
+      x: lineX(i, current.length) * width,
+      y: lineY(fraction, 1, height) * height,
+    }));
+    if (points.length === 1 && points[0])
+      points.splice(0, 1, { x: 0, y: points[0].y }, { x: width, y: points[0].y });
+    if (points.length === 0) return moving;
+    const resolved = frame.color(color);
+
+    ditherFill(ctx, {
+      clip: makePath((sink) => {
+        traceSpline(sink, points, height);
+      }),
+      bounds: { x: 0, y: 0, width, height },
+      cell: step,
+      color: resolved,
+      density: (cx, cy) => {
+        const falloff = Math.max(0, 1 - cy / height);
+        const mod = animated ? drift(cx, cy, time * 1.2) : 0.5;
+        return (0.55 * falloff + 0.35 * mod) * (0.8 + 0.4 * hash2(cx, cy));
+      },
+    });
+
+    ctx.beginPath();
+    traceSpline(ctx, points);
+    ctx.lineWidth = 2;
+    ctx.lineJoin = "round";
+    ctx.lineCap = "round";
+    ctx.strokeStyle = resolved;
+    ctx.stroke();
+    return moving;
+  };
+
+  const shown = scrubber.valueIndex;
+  const datum = data[shown];
+  const low = values.reduce(
+    (best, value, i) => (value < (values[best] ?? Infinity) ? i : best),
+    0,
+  );
+  const high = values.reduce(
+    (best, value, i) => (value > (values[best] ?? -Infinity) ? i : best),
+    0,
+  );
+  const summary =
+    description ??
+    (count === 0
+      ? "No data."
+      : `${String(count)} points from ${data[0]?.label ?? ""} to ${data[count - 1]?.label ?? ""}. ` +
+        `High ${formatValue(values[high] ?? 0)} on ${data[high]?.label ?? ""}, ` +
+        `low ${formatValue(values[low] ?? 0)} on ${data[low]?.label ?? ""}.`);
+
+  return (
+    <div
+      data-slot="dither-line"
+      {...props}
+      className={cn(ditherLineVariants({ size }), className)}
+    >
+      <div
+        data-slot="dither-line-plot"
+        className="relative h-[var(--dither-line-height)]"
+        style={{ direction: "ltr" }}
+      >
+        <div role="img" aria-label={`${label}: ${summary}`} className="size-full">
+          <DitherCanvas draw={draw} animate={animate} cell={cell} />
+        </div>
+        {count > 0 && (
+          <DitherCursor
+            scrubber={scrubber}
+            label={label}
+            valueText={datum ? `${datum.label}: ${formatValue(datum.value)}` : ""}
+            x={lineX(shown, count)}
+            y={lineY(values[shown] ?? 0, top, 0)}
+            readout={
+              datum && (
+                <>
+                  <span className="block text-2xs text-muted-foreground uppercase">
+                    {datum.label}
+                  </span>
+                  <span className="font-medium tabular-nums">{formatValue(datum.value)}</span>
+                </>
+              )
+            }
+          />
+        )}
+      </div>
+      {showAxis && count > 0 && (
+        <div
+          aria-hidden
+          data-slot="dither-line-labels"
+          className="relative h-4 font-mono text-2xs text-muted-foreground"
+          style={{ direction: "ltr" }}
+        >
+          {axisIndices(count).map((i) => {
+            const x = lineX(i, count);
+            return (
+              <span
+                key={i}
+                data-active={scrubber.index === i || undefined}
+                className="absolute top-0 whitespace-nowrap data-active:text-foreground"
+                style={{
+                  left: `${String(x * 100)}%`,
+                  transform: `translateX(${String(-x * 100)}%)`,
+                }}
+              >
+                {data[i]?.label}
+              </span>
+            );
+          })}
+        </div>
+      )}
+      <DitherTable
+        caption={label}
+        columns={[categoryLabel, valueLabel]}
+        rows={data.map((entry) => [entry.label, formatValue(entry.value)])}
+        visible={showTable}
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,8 @@
+export {
+  axisIndices,
+  DitherLine,
+  ditherLineVariants,
+  lineY,
+  type DitherLineDatum,
+  type DitherLineProps,
+} from "./dither-line";

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

@@ -0,0 +1,18 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "dither-line",
+  title: "Dither Line",
+  description:
+    "A smooth monotone line over a drifting dithered gradient fill, with a keyboard-operable point scrubber.",
+  category: "data",
+  status: "beta",
+  dependencies: ["class-variance-authority"],
+  registryDependencies: ["dither-canvas"],
+  files: ["dither-line.tsx"],
+  a11y:
+    'The plot is role="img" with an aria-label giving the range, high and low. The scrubber over ' +
+    "it is a slider: arrow keys step a point, Page keys jump, Home/End go to the ends, Escape hides " +
+    "the cursor, and aria-valuetext announces the point and value shown in the readout. The data is " +
+    "always in a table, visually hidden unless showTable is set.",
+});

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

@@ -0,0 +1,299 @@
+"use client";
+
+// Ported from amicro "Storage Capacity Bar" (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,
+  tokenToCss,
+  traceRoundedRect,
+  type DitherDraw,
+} from "@/components/dither-canvas";
+import { focusRing } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+/*
+ * A capacity bar drawn in dithered cells over a faint track — amicro's storage
+ * bar — split into one segment per category. Segment lengths are springs in
+ * the engine (amicro's 150 / 20), so a new reading fills rather than cuts.
+ *
+ * The bar is a role="meter" rather than an image: used over capacity is its
+ * value (aria-valuenow / min / max) and aria-valuetext reads the breakdown. A
+ * meter's children are presentational, so the canvas inside it is too. Legend
+ * buttons preview a category on hover or focus and pin it when pressed. The
+ * bar fills from the start edge in LTR in every direction, as a canvas draws.
+ */
+
+export const ditherMeterVariants = cva("flex flex-col gap-2", {
+  variants: {
+    size: {
+      sm: "[--dither-meter-height:0.75rem]",
+      md: "[--dither-meter-height:1.5rem]",
+      lg: "[--dither-meter-height:2.25rem]",
+    },
+  },
+  defaultVariants: { size: "md" },
+});
+
+export interface DitherMeterSegment {
+  key: string;
+  label: string;
+  value: number;
+  /** Colour token or CSS colour expression. Defaults to the palette. */
+  color?: string;
+}
+
+export interface DitherMeterProps
+  extends
+    Omit<ComponentPropsWithRef<"div">, "children">,
+    VariantProps<typeof ditherMeterVariants> {
+  segments: readonly DitherMeterSegment[];
+  /** What the bar measures. Names the meter and the data table. */
+  label: string;
+  /** Replaces the generated breakdown in the meter's aria-valuetext. */
+  description?: string;
+  /** Capacity. Defaults to the sum of the segments (a full bar). */
+  max?: number;
+  formatValue?: (value: number) => string;
+  /** Formats a 0..1 share. Defaults to a whole percentage. */
+  formatPercent?: (share: number) => string;
+  /** Show the category buttons. */
+  showLegend?: boolean;
+  /** Show the "used of capacity" line. */
+  showValue?: boolean;
+  /** Name of the unused remainder. */
+  freeLabel?: string;
+  /** Show the data table. It is always present for assistive technology. */
+  showTable?: boolean;
+  animate?: boolean;
+  cell?: number;
+  /** The pinned category key (controlled). */
+  activeSegment?: string | null;
+  defaultActiveSegment?: string | null;
+  onActiveSegmentChange?: (key: string | null) => void;
+  /** Data table headers. */
+  categoryLabel?: string;
+  valueLabel?: string;
+  shareLabel?: string;
+}
+
+/** Gap between segments in CSS pixels. */
+export const METER_GAP = 2;
+
+const clean = (value: number) => (Number.isFinite(value) && value > 0 ? value : 0);
+
+/** Each segment's [start, end] along the bar, 0..1, stacked from the start. */
+export function meterSpans(values: readonly number[], capacity: number): [number, number][] {
+  let cursor = 0;
+  return values.map((value) => {
+    const share = capacity > 0 ? clean(value) / capacity : 0;
+    const start = Math.min(1, cursor);
+    cursor += share;
+    return [start, Math.min(1, cursor)];
+  });
+}
+
+const wholePercent = (share: number) => `${String(Math.round(share * 100))}%`;
+
+export function DitherMeter({
+  segments,
+  label,
+  description,
+  max,
+  size,
+  formatValue = formatDitherValue,
+  formatPercent = wholePercent,
+  showLegend = true,
+  showValue = true,
+  freeLabel = "Free",
+  showTable = false,
+  animate = true,
+  cell = 3,
+  activeSegment,
+  defaultActiveSegment = null,
+  onActiveSegmentChange,
+  categoryLabel = "Category",
+  valueLabel = "Value",
+  shareLabel = "Share",
+  className,
+  ...props
+}: DitherMeterProps) {
+  const [uncontrolled, setUncontrolled] = useState<string | null>(defaultActiveSegment);
+  const [preview, setPreview] = useState<number | null>(null);
+  const pinnedKey = activeSegment !== undefined ? activeSegment : uncontrolled;
+  const pinned = pinnedKey === null ? -1 : segments.findIndex((s) => s.key === pinnedKey);
+  const lit = preview ?? (pinned >= 0 ? pinned : null);
+
+  const values = segments.map((segment) => clean(segment.value));
+  const used = values.reduce((sum, value) => sum + value, 0);
+  const capacity = max !== undefined && max > 0 ? max : used;
+  const free = Math.max(0, capacity - used);
+  const shares = values.map((value) => (capacity > 0 ? value / capacity : 0));
+  const spans = meterSpans(values, capacity);
+  const ends = useRef(
+    createSprings(
+      spans.map(() => 0),
+      { stiffness: 150, damping: 20, mass: 1 },
+    ),
+  );
+
+  const draw: DitherDraw = (ctx, frame) => {
+    const { width, height, time } = frame;
+    ends.current.set(spans.map((span) => span[1]));
+    const moving = ends.current.step(frame.delta, frame.reducedMotion);
+    const current = ends.current.values;
+    const radius = Math.min(height / 2, 6);
+    const bar = makePath((sink) => {
+      traceRoundedRect(sink, 0, 0, width, height, radius);
+    });
+    ctx.save();
+    if (bar) ctx.clip(bar);
+    // The track: amicro's faint full-width bar.
+    ctx.globalAlpha = 0.1;
+    ctx.fillStyle = frame.color("foreground");
+    ctx.fillRect(0, 0, width, height);
+    ctx.globalAlpha = 1;
+    let start = 0;
+    current.forEach((end, i) => {
+      const x0 = start * width + (i > 0 ? METER_GAP / 2 : 0);
+      const x1 = Math.min(1, end) * width - METER_GAP / 2;
+      start = Math.max(start, Math.min(1, end));
+      if (x1 - x0 < 1) return;
+      ditherFill(ctx, {
+        clip: makePath((sink) => {
+          traceRoundedRect(sink, x0, 0, x1 - x0, height, 1);
+        }),
+        bounds: { x: x0, y: 0, width: x1 - x0, height },
+        cell: frame.cell,
+        color: frame.color(seriesColor(i, segments[i]?.color)),
+        alpha: lit !== null && lit !== i ? 0.3 : 0.85,
+        density: (cx, cy) =>
+          (0.3 + 0.4 * drift(cx, cy, time * 1.2)) * (0.8 + 0.4 * hash2(cx, cy)) +
+          (lit === i ? 0.2 : 0),
+      });
+    });
+    ctx.restore();
+    return moving;
+  };
+
+  const pin = (index: number) => {
+    const key = segments[index]?.key ?? null;
+    const next = pinnedKey === key ? null : key;
+    if (activeSegment === undefined) setUncontrolled(next);
+    onActiveSegmentChange?.(next);
+  };
+
+  const part = (i: number) =>
+    `${segments[i]?.label ?? ""} ${formatValue(values[i] ?? 0)} (${formatPercent(shares[i] ?? 0)})`;
+  const total = `${formatValue(used)} of ${formatValue(capacity)} used`;
+  const breakdown =
+    segments.length === 0
+      ? "No data."
+      : `${total} (${formatPercent(capacity > 0 ? used / capacity : 0)}). ` +
+        `${segments.map((_, i) => part(i)).join(", ")}; ${freeLabel.toLowerCase()} ${formatValue(free)}.`;
+
+  return (
+    <div
+      data-slot="dither-meter"
+      {...props}
+      className={cn(ditherMeterVariants({ size }), className)}
+    >
+      {showValue && (
+        <p
+          aria-hidden
+          data-slot="dither-meter-value"
+          className="flex items-baseline justify-between gap-3 text-xs text-muted-foreground tabular-nums"
+        >
+          <span>
+            <span className="text-sm font-semibold text-foreground">{formatValue(used)}</span>{" "}
+            of {formatValue(capacity)}
+          </span>
+          <span>{formatPercent(capacity > 0 ? used / capacity : 0)}</span>
+        </p>
+      )}
+      <div
+        role="meter"
+        data-slot="dither-meter-bar"
+        aria-label={label}
+        aria-valuemin={0}
+        aria-valuemax={capacity}
+        aria-valuenow={Math.min(used, capacity)}
+        aria-valuetext={description ?? breakdown}
+        className="h-[var(--dither-meter-height)]"
+        style={{ direction: "ltr" }}
+      >
+        <DitherCanvas draw={draw} animate={animate} cell={cell} />
+      </div>
+      {showLegend && segments.length > 0 && (
+        <ul
+          data-slot="dither-meter-legend"
+          aria-label={`${label} categories`}
+          className="flex flex-wrap gap-1"
+        >
+          {segments.map((segment, i) => (
+            <li key={segment.key}>
+              <button
+                type="button"
+                aria-pressed={pinned === i}
+                data-active={lit === i || 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(i);
+                }}
+                onPointerLeave={() => {
+                  setPreview(null);
+                }}
+                onFocus={() => {
+                  setPreview(i);
+                }}
+                onBlur={() => {
+                  setPreview(null);
+                }}
+                onClick={() => {
+                  pin(i);
+                }}
+              >
+                <span
+                  aria-hidden
+                  className="size-2.5 rounded-full"
+                  style={{ background: tokenToCss(seriesColor(i, segment.color)) }}
+                />
+                {segment.label}{" "}
+                <span className="tabular-nums">{formatValue(values[i] ?? 0)}</span>
+              </button>
+            </li>
+          ))}
+          <li className="flex items-center gap-1.5 px-2 py-1 text-xs text-muted-foreground">
+            <span aria-hidden className="size-2.5 rounded-full bg-foreground/10" />
+            {freeLabel} <span className="tabular-nums">{formatValue(free)}</span>
+          </li>
+        </ul>
+      )}
+      <DitherTable
+        caption={label}
+        columns={[categoryLabel, valueLabel, shareLabel]}
+        rows={[
+          ...segments.map((segment, i) => [
+            segment.label,
+            formatValue(values[i] ?? 0),
+            formatPercent(shares[i] ?? 0),
+          ]),
+          [freeLabel, formatValue(free), formatPercent(capacity > 0 ? free / capacity : 0)],
+        ]}
+        visible={showTable}
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,8 @@
+export {
+  DitherMeter,
+  ditherMeterVariants,
+  METER_GAP,
+  meterSpans,
+  type DitherMeterProps,
+  type DitherMeterSegment,
+} from "./dither-meter";

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

@@ -0,0 +1,19 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "dither-meter",
+  title: "Dither Meter",
+  description:
+    "A capacity bar drawn in dithered cells, split into categories that fill with a spring, with a category legend.",
+  category: "data",
+  status: "beta",
+  dependencies: ["class-variance-authority"],
+  registryDependencies: ["dither-canvas"],
+  files: ["dither-meter.tsx"],
+  a11y:
+    'The bar is a role="meter" named by label, with used over capacity as aria-valuenow / ' +
+    "aria-valuemax and the per-category breakdown as aria-valuetext (or `description`). Legend " +
+    "entries are buttons, named with category and value, that preview a segment on hover or focus " +
+    "and pin it when pressed (aria-pressed). The visible used-of-capacity line is aria-hidden as it " +
+    "repeats the meter. The data is always in a table, visually hidden unless showTable is set.",
+});