@dowel-ui/react 0.7.0 → 0.8.0

package/src/components/diff-viewer/diff-viewer.tsx

@@ -1,6 +1,15 @@
 "use client";
 
-import { useMemo, type ComponentPropsWithRef, type ReactNode } from "react";
+// Motion from SmoothUI AI Diff (MIT, © 2024 Eduardo Calvo). See THIRD_PARTY_NOTICES.md.
+import {
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentPropsWithRef,
+  type CSSProperties,
+  type ReactNode,
+} from "react";
 
 import { disabledStyles, focusRing } from "@/lib/styles";
 import { cn } from "@/lib/utils";
@@ -44,6 +53,44 @@ export interface DiffViewerProps extends Omit<ComponentPropsWithRef<"div">, "chi
   decisions?: Record<string, HunkDecision>;
   onDecision?: (hunkId: string, decision: HunkDecision) => void;
   children?: ReactNode;
+  /**
+   * Entrance for added lines. `wipe` draws each one in along the reading
+   * direction, a line after the other; context and removed lines were already
+   * there and do not move.
+   */
+  entrance?: "none" | "wipe";
+  /**
+   * Collapse a rejected hunk's lines. Its header and controls stay, so the
+   * decision can still be reversed, and the header says the lines are hidden.
+   */
+  collapseRejected?: boolean;
+}
+
+const PREFIX = "dowel-diff-viewer";
+
+/* The wipe reveals an added line's code (never its line numbers) in reading
+ * order; its stagger is capped so a long diff does not take seconds to appear.
+ * The flash is a one-shot tint when a hunk's decision changes. */
+const STYLES = `
+@keyframes ${PREFIX}-wipe{from{clip-path:inset(0 100% 0 0)}}
+@keyframes ${PREFIX}-wipe-rtl{from{clip-path:inset(0 0 0 100%)}}
+@keyframes ${PREFIX}-flash-accepted{from{background-color:color-mix(in oklab,var(--color-success) 14%,transparent)}}
+@keyframes ${PREFIX}-flash-rejected{from{background-color:color-mix(in oklab,var(--color-destructive) 12%,transparent)}}
+.${PREFIX}-wipe{animation:${PREFIX}-wipe calc(280ms * var(--motion-scale,1)) var(--ease-out-quint) both;animation-delay:calc(var(--dowel-i,0) * 20ms * var(--motion-scale,1))}
+.${PREFIX}-wipe:dir(rtl){animation-name:${PREFIX}-wipe-rtl}
+[data-slot=diff-hunk][data-decision-changed=accepted]{animation:${PREFIX}-flash-accepted calc(350ms * var(--motion-scale,1)) var(--ease-out-quint)}
+[data-slot=diff-hunk][data-decision-changed=rejected]{animation:${PREFIX}-flash-rejected calc(350ms * var(--motion-scale,1)) var(--ease-out-quint)}
+`;
+
+/** Lines after this many in a hunk share the last one's delay. */
+const WIPE_STAGGER_CAP = 20;
+
+/** Props for the content cell of an added line under `entrance="wipe"`. */
+function wipe(index: number): { className: string; style: CSSProperties } {
+  return {
+    className: `${PREFIX}-wipe`,
+    style: { "--dowel-i": Math.min(index, WIPE_STAGGER_CAP) } as CSSProperties,
+  };
 }
 
 export function DiffViewer({
@@ -54,6 +101,8 @@ export function DiffViewer({
   decisions,
   onDecision,
   children,
+  entrance = "none",
+  collapseRejected = false,
   ...props
 }: DiffViewerProps) {
   const counts = useMemo(() => countChanges(hunks), [hunks]);
@@ -65,6 +114,9 @@ export function DiffViewer({
       className={cn("flex flex-col gap-2", className)}
       {...props}
     >
+      <style href={PREFIX} precedence="dowel">
+        {STYLES}
+      </style>
       <div className="flex flex-wrap items-baseline justify-between gap-2">
         <span className="font-mono text-sm font-medium">{label}</span>
         {/* Said in words as well as coloured, and before the diff rather than
@@ -95,6 +147,8 @@ export function DiffViewer({
               view={view}
               decision={decisions?.[hunk.id]}
               onDecision={onDecision}
+              entrance={entrance}
+              collapseRejected={collapseRejected}
             />
           ))}
         </div>
@@ -109,22 +163,81 @@ function DiffHunkView({
   view,
   decision,
   onDecision,
+  entrance,
+  collapseRejected,
 }: {
   hunk: DiffHunk;
   label: string;
   view: "unified" | "split";
   decision?: HunkDecision;
   onDecision?: (hunkId: string, decision: HunkDecision) => void;
+  entrance: "none" | "wipe";
+  collapseRejected: boolean;
 }) {
   const splitRows = useMemo(
     () => (view === "split" ? toSplitRows(hunk.rows) : []),
     [view, hunk.rows],
   );
 
+  // A decision that changes after mount flashes once. Tracked during render,
+  // so a decision present on first render (a replay) does not flash.
+  const [previous, setPrevious] = useState(decision);
+  const [flash, setFlash] = useState<HunkDecision | undefined>(undefined);
+  if (decision !== previous) {
+    setPrevious(decision);
+    setFlash(decision);
+  }
+
+  // A native listener rather than onAnimationEnd: React picks a vendor-prefixed
+  // event name wherever AnimationEvent is missing, and would never hear it.
+  const sectionRef = useRef<HTMLElement | null>(null);
+  useEffect(() => {
+    const section = sectionRef.current;
+    if (!section || !flash) return;
+    const clear = (event: Event) => {
+      // Wiped lines end their own animations inside the hunk; only the
+      // hunk's flash clears the flag.
+      if (event.target === section) setFlash(undefined);
+    };
+    section.addEventListener("animationend", clear);
+    return () => {
+      section.removeEventListener("animationend", clear);
+    };
+  }, [flash]);
+
+  const wiping = entrance === "wipe";
+  const collapsed = collapseRejected && decision === "rejected";
+  const hiddenNote = collapsed ? <span className="sr-only"> — lines hidden</span> : null;
+
+  const table = (
+    <div className="overflow-x-auto">
+      <table data-slot="diff-table" className="w-full border-collapse font-mono text-xs">
+        <tbody>
+          {view === "split"
+            ? splitRows.map((pair, index) => (
+                <tr key={index} data-slot="diff-row">
+                  <SplitCell row={pair.left} side="before" />
+                  <SplitCell
+                    row={pair.right}
+                    side="after"
+                    wipeIndex={wiping ? index : undefined}
+                  />
+                </tr>
+              ))
+            : hunk.rows.map((row, index) => (
+                <UnifiedRow key={index} row={row} wipeIndex={wiping ? index : undefined} />
+              ))}
+        </tbody>
+      </table>
+    </div>
+  );
+
   return (
     <section
       data-slot="diff-hunk"
       data-decision={decision}
+      ref={sectionRef}
+      data-decision-changed={flash}
       aria-label={`${label}, hunk ${hunk.id}`}
       className={cn(
         "border-b border-border last:border-b-0",
@@ -148,6 +261,7 @@ function DiffHunkView({
               : decision === "rejected"
                 ? "Rejected"
                 : "Not decided"}
+            {hiddenNote}
           </span>
           <HunkButton
             pressed={decision === "accepted"}
@@ -168,20 +282,26 @@ function DiffHunkView({
         </div>
       ) : null}
 
-      <div className="overflow-x-auto">
-        <table data-slot="diff-table" className="w-full border-collapse font-mono text-xs">
-          <tbody>
-            {view === "split"
-              ? splitRows.map((pair, index) => (
-                  <tr key={index} data-slot="diff-row">
-                    <SplitCell row={pair.left} side="before" />
-                    <SplitCell row={pair.right} side="after" />
-                  </tr>
-                ))
-              : hunk.rows.map((row, index) => <UnifiedRow key={index} row={row} />)}
-          </tbody>
-        </table>
-      </div>
+      {!onDecision ? hiddenNote : null}
+
+      {collapseRejected ? (
+        // Grid rows animate between 1fr and 0fr, which is a height transition
+        // CSS can do. Collapsed lines are inert: hidden, and out of reach.
+        <div
+          data-slot="diff-hunk-lines"
+          data-collapsed={collapsed || undefined}
+          className={cn(
+            "grid transition-[grid-template-rows,opacity] duration-[calc(250ms*var(--motion-scale))] ease-[var(--ease-out-quint)]",
+            collapsed ? "grid-rows-[0fr] opacity-0" : "grid-rows-[1fr]",
+          )}
+        >
+          <div className="min-h-0 overflow-hidden" inert={collapsed || undefined}>
+            {table}
+          </div>
+        </div>
+      ) : (
+        table
+      )}
     </section>
   );
 }
@@ -192,7 +312,8 @@ const ROW_STYLES: Record<DiffRow["kind"], string> = {
   context: "",
 };
 
-function UnifiedRow({ row }: { row: DiffRow }) {
+function UnifiedRow({ row, wipeIndex }: { row: DiffRow; wipeIndex?: number }) {
+  const motion = wipeIndex !== undefined && row.kind === "added" ? wipe(wipeIndex) : undefined;
   return (
     <tr data-slot="diff-row" data-kind={row.kind} className={ROW_STYLES[row.kind]}>
       <LineNumber value={row.before} />
@@ -200,7 +321,10 @@ function UnifiedRow({ row }: { row: DiffRow }) {
       <td className="w-4 pe-1 text-center text-muted-foreground select-none" aria-hidden="true">
         {row.kind === "added" ? "+" : row.kind === "removed" ? "−" : ""}
       </td>
-      <td className="w-full py-0.5 pe-3 break-all whitespace-pre-wrap">
+      <td
+        className={cn("w-full py-0.5 pe-3 break-all whitespace-pre-wrap", motion?.className)}
+        style={motion?.style}
+      >
         {/* The kind, for anyone who cannot see the sign or the tint. Reading a
             diff aloud without it is reading the same file twice. */}
         <span className="sr-only">{KIND_LABEL[row.kind]}: </span>
@@ -210,7 +334,15 @@ function UnifiedRow({ row }: { row: DiffRow }) {
   );
 }
 
-function SplitCell({ row, side }: { row: DiffRow | null; side: "before" | "after" }) {
+function SplitCell({
+  row,
+  side,
+  wipeIndex,
+}: {
+  row: DiffRow | null;
+  side: "before" | "after";
+  wipeIndex?: number;
+}) {
   if (!row) {
     // An empty half of a pair, not a blank line of code. Hidden from assistive
     // technology so a reader is not read padding.
@@ -222,11 +354,18 @@ function SplitCell({ row, side }: { row: DiffRow | null; side: "before" | "after
     );
   }
 
+  const motion = wipeIndex !== undefined && row.kind === "added" ? wipe(wipeIndex) : undefined;
+
   return (
     <>
       <LineNumber value={side === "before" ? row.before : row.after} />
       <td
-        className={cn("w-1/2 py-0.5 pe-3 break-all whitespace-pre-wrap", ROW_STYLES[row.kind])}
+        className={cn(
+          "w-1/2 py-0.5 pe-3 break-all whitespace-pre-wrap",
+          ROW_STYLES[row.kind],
+          motion?.className,
+        )}
+        style={motion?.style}
       >
         <span className="sr-only">{KIND_LABEL[row.kind]}: </span>
         <RowContent row={row} />

package/src/components/diff-viewer/meta.ts

@@ -16,5 +16,8 @@ export const meta = defineMeta({
     "aloud without it is just the same file twice. Line numbers are aria-hidden: they orient a " +
     "sighted reader, and announcing two numbers before every line makes the diff unlistenable. " +
     "Changed words are marked with mark elements so they survive as structure, and the empty half " +
-    "of a split pair is hidden rather than read as a blank line of code.",
+    "of a split pair is hidden rather than read as a blank line of code. The optional wipe entrance " +
+    "is visual only — every row is in the DOM and its kind text is never clipped from assistive " +
+    "technology. With collapseRejected, a rejected hunk's lines are inert and hidden, its header " +
+    "says so in words, and Accept stays available so the decision can be reversed.",
 });

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

@@ -0,0 +1,280 @@
+"use client";
+
+// Ported from amicro "Dither Area Growth" (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,
+  formatDitherValue,
+  hash2,
+  makePath,
+  smoothstep,
+  tracePolyline,
+  useDitherScrubber,
+  valueAt,
+  type DitherDraw,
+} from "@/components/dither-canvas";
+import { cn } from "@/lib/utils";
+
+/*
+ * An area chart filled with dithered cells over a faint cell grid, with a date
+ * scrubber. The cursor follows the pointer as in amicro, cells swell around it,
+ * and it is also an APG slider: Tab to the plot, then arrows step a point, Page
+ * keys jump a tenth, Home/End go to the ends, Escape hides it. The readout is
+ * real text and the slider announces the same thing through aria-valuetext.
+ * Values are springs in the engine, so switching range morphs the curve — a
+ * different point count is resampled rather than dropped to zero.
+ */
+
+export const ditherAreaVariants = cva("flex flex-col gap-2", {
+  variants: {
+    size: {
+      sm: "[--dither-area-height:7.5rem]",
+      md: "[--dither-area-height:11.25rem]",
+      lg: "[--dither-area-height:16rem]",
+    },
+  },
+  defaultVariants: { size: "md" },
+});
+
+export interface DitherAreaDatum {
+  /** The point's name on the axis, e.g. a date. */
+  label: string;
+  value: number;
+}
+
+export interface DitherAreaProps
+  extends
+    Omit<ComponentPropsWithRef<"div">, "children">,
+    VariantProps<typeof ditherAreaVariants> {
+  data: readonly DitherAreaDatum[];
+  /** 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. */
+  max?: number;
+  formatValue?: (value: number) => string;
+  /** Colour token or CSS colour expression for the fill. Default "primary". */
+  color?: string;
+  /** Show value ticks and point labels. */
+  showAxis?: boolean;
+  /** Show the data table. It is always present for assistive technology. */
+  showTable?: boolean;
+  animate?: boolean;
+  cell?: number;
+  /** Cursor point (controlled); null hides it. */
+  index?: number | null;
+  defaultIndex?: number | null;
+  onIndexChange?: (index: number | null) => void;
+  /** Data table headers. */
+  categoryLabel?: string;
+  valueLabel?: string;
+}
+
+/** Space kept above the tallest value, as a fraction of the plot height. */
+export const AREA_HEADROOM = 0.16;
+
+/** Distance from the top of the plot, 0..1, for a value against `max`. */
+export function areaY(value: number, max: number): number {
+  return 1 - (1 - AREA_HEADROOM) * (max > 0 ? Math.max(0, value) / max : 0);
+}
+
+/** Position across the plot, 0..1, of point `index` of `count`. */
+export function pointX(index: number, count: number): number {
+  return count <= 1 ? 0.5 : index / (count - 1);
+}
+
+export function DitherArea({
+  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
+}: DitherAreaProps) {
+  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);
+  const shape = useRef(createSprings(values.map(() => 0)));
+  const cursor = scrubber.index;
+
+  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: pointX(i, current.length) * width,
+      y: areaY(fraction, 1) * height,
+    }));
+    if (points.length === 1 && points[0]) points.unshift({ x: 0, y: points[0].y });
+    if (points.length === 2 && current.length === 1 && points[1]) points[1].x = width;
+
+    // The faint cell grid the area sits on.
+    ditherFill(ctx, {
+      bounds: { x: 0, y: 0, width, height },
+      cell: step,
+      color: frame.color("foreground"),
+      alpha: 0.05,
+      density: () => 0.78,
+    });
+
+    const focus =
+      cursor !== null
+        ? {
+            x: pointX(cursor, current.length) * width,
+            y: areaY(valueAt(current, cursor), 1) * height,
+          }
+        : null;
+    const radius = height * 0.35;
+    ditherFill(ctx, {
+      clip: makePath((sink) => {
+        tracePolyline(sink, points, height);
+      }),
+      bounds: { x: 0, y: 0, width, height },
+      cell: step,
+      color: frame.color(color),
+      alpha: 0.8,
+      density: (cx, cy) => {
+        const glow = focus
+          ? 1 - smoothstep(0, radius, Math.hypot(cx - focus.x, cy - focus.y))
+          : 0;
+        const wave = animated ? Math.sin(cy * 0.1 - time * 3.6) * 0.07 : 0;
+        return 0.62 + wave + glow * 0.34 + (hash2(cx, cy) - 0.5) * 0.08;
+      },
+    });
+    return moving;
+  };
+
+  const format = (i: number) => {
+    const datum = data[i];
+    return datum ? `${datum.label}: ${formatValue(datum.value)}` : "";
+  };
+  const peak = 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 ?? ""}. ` +
+        `Starts at ${formatValue(values[0] ?? 0)}, ends at ${formatValue(values[count - 1] ?? 0)}; ` +
+        `peak ${formatValue(values[peak] ?? 0)} on ${data[peak]?.label ?? ""}.`);
+  const ticks = [top, top * 0.66, top * 0.33, 0];
+  const axisLabels =
+    count > 0
+      ? [0, 0.25, 0.5, 0.75, 1]
+          .map((t) => Math.round(t * (count - 1)))
+          .filter((i, n, all) => all.indexOf(i) === n)
+      : [];
+  const shown = scrubber.valueIndex;
+  const datum = data[shown];
+
+  return (
+    <div
+      data-slot="dither-area"
+      {...props}
+      className={cn(ditherAreaVariants({ size }), className)}
+    >
+      <div className="flex gap-3" style={{ direction: "ltr" }}>
+        {showAxis && (
+          <div
+            aria-hidden
+            data-slot="dither-area-ticks"
+            className="relative h-[var(--dither-area-height)] w-8 shrink-0"
+          >
+            {ticks.map((tick, i) => (
+              <span
+                key={i}
+                className="absolute end-0 -translate-y-1/2 font-mono text-2xs text-muted-foreground tabular-nums"
+                style={{ top: `${String(areaY(tick, top) * 100)}%` }}
+              >
+                {formatValue(Math.round(tick))}
+              </span>
+            ))}
+          </div>
+        )}
+        <div className="flex min-w-0 flex-1 flex-col gap-2">
+          <div data-slot="dither-area-plot" className="relative h-[var(--dither-area-height)]">
+            <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={format(shown)}
+                x={pointX(shown, count)}
+                y={areaY(values[shown] ?? 0, top)}
+                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 && (
+            <div
+              aria-hidden
+              data-slot="dither-area-labels"
+              className="relative h-4 font-mono text-2xs text-muted-foreground"
+            >
+              {axisLabels.map((i) => {
+                const x = pointX(i, count);
+                return (
+                  <span
+                    key={i}
+                    className="absolute top-0 whitespace-nowrap"
+                    style={{
+                      left: `${String(x * 100)}%`,
+                      transform: `translateX(${String(-x * 100)}%)`,
+                    }}
+                  >
+                    {data[i]?.label}
+                  </span>
+                );
+              })}
+            </div>
+          )}
+        </div>
+      </div>
+      <DitherTable
+        caption={label}
+        columns={[categoryLabel, valueLabel]}
+        rows={data.map((entry) => [entry.label, formatValue(entry.value)])}
+        visible={showTable}
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,9 @@
+export {
+  AREA_HEADROOM,
+  areaY,
+  DitherArea,
+  ditherAreaVariants,
+  pointX,
+  type DitherAreaDatum,
+  type DitherAreaProps,
+} from "./dither-area";

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

@@ -0,0 +1,18 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "dither-area",
+  title: "Dither Area",
+  description:
+    "An area chart filled with dithered cells over a cell grid, with a date scrubber that swells the cells around it.",
+  category: "data",
+  status: "beta",
+  dependencies: ["class-variance-authority"],
+  registryDependencies: ["dither-canvas"],
+  files: ["dither-area.tsx"],
+  a11y:
+    'The plot is role="img" with an aria-label giving the range, start, end and peak. The scrubber ' +
+    "over it is a slider: arrow keys step a point, Page keys jump a tenth, Home/End go to the ends, " +
+    "Escape hides the cursor, and aria-valuetext announces the date and value shown in the readout. " +
+    "Axis ticks are aria-hidden; the data is always in a table, visually hidden unless showTable is set.",
+});