@dowel-ui/react 0.5.0 → 0.8.0

package/src/components/dialog/dialog.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+// Motion from SmoothUI Dialog and BasicModal (MIT, © 2024 Eduardo Calvo). See THIRD_PARTY_NOTICES.md.
 import { Dialog as DialogPrimitive } from "radix-ui";
 import type { ComponentPropsWithRef } from "react";
 
@@ -34,56 +35,98 @@ export function DialogOverlay({ className, ...props }: DialogOverlayProps) {
   );
 }
 
+const PREFIX = "dowel-dialog";
+
+/** Each section of a spring dialog arrives 60ms after the one above it. */
+const STAGGER_STEP_MS = 60;
+const STAGGERED = 6;
+
+const SPRING_CHILD = `[data-slot=dialog-content][data-animation=spring][data-state=open]>:not([data-slot=dialog-close])`;
+
+const STYLES = `
+@keyframes ${PREFIX}-spring-in{from{opacity:0;transform:translateY(.5rem) scale(.95)}}
+@keyframes ${PREFIX}-section-in{from{opacity:0;transform:translateY(8px)}}
+${SPRING_CHILD}{animation:${PREFIX}-section-in calc(250ms * var(--motion-scale)) var(--ease-out-quint) both}
+${Array.from(
+  { length: STAGGERED - 1 },
+  (_, i) =>
+    `${SPRING_CHILD}:nth-child(${String(i + 2)}){animation-delay:calc(${String((i + 1) * STAGGER_STEP_MS)}ms * var(--motion-scale))}`,
+).join("\n")}
+${SPRING_CHILD}:nth-child(n+${String(STAGGERED + 1)}){animation-delay:calc(${String(STAGGERED * STAGGER_STEP_MS)}ms * var(--motion-scale))}
+`;
+
 export interface DialogContentProps extends ComponentPropsWithRef<
   typeof DialogPrimitive.Content
 > {
   /** Renders the built-in close button. Turn off to supply your own. */
   showCloseButton?: boolean;
+  /**
+   * How the dialog enters. `default` fades and rises into place. `spring` pops
+   * in with a slight overshoot and then brings its sections — header, body,
+   * footer — in one after another. Both stop under reduced motion, and both
+   * leave the same way.
+   */
+  animation?: "default" | "spring";
 }
 
 export function DialogContent({
   className,
   children,
   showCloseButton = true,
+  animation = "default",
   ...props
 }: DialogContentProps) {
+  const spring = animation === "spring";
+
   return (
-    <DialogPortal>
-      <DialogOverlay />
-      <DialogPrimitive.Content
-        data-slot="dialog-content"
-        className={cn(
-          "fixed top-1/2 left-1/2 z-[var(--z-modal)] w-[calc(100%-2rem)] max-w-lg -translate-x-1/2 -translate-y-1/2",
-          "grid gap-4 rounded-xl border border-border bg-card p-6 text-card-foreground shadow-xl",
-          "data-[state=closed]:animate-dialog-out data-[state=open]:animate-dialog-in",
-          className,
-        )}
-        {...props}
-      >
-        {children}
-        {showCloseButton ? (
-          <DialogPrimitive.Close
-            data-slot="dialog-close"
-            aria-label="Close"
-            className={cn(
-              "absolute top-4 right-4 grid size-7 place-items-center rounded-md text-muted-foreground",
-              "transition-colors duration-[var(--duration-fast)] hover:bg-accent hover:text-foreground",
-              "[&_svg]:size-4",
-              focusRing,
-            )}
-          >
-            <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
-              <path
-                d="m6 6 12 12M18 6 6 18"
-                stroke="currentColor"
-                strokeWidth="2"
-                strokeLinecap="round"
-              />
-            </svg>
-          </DialogPrimitive.Close>
-        ) : null}
-      </DialogPrimitive.Content>
-    </DialogPortal>
+    <>
+      {spring ? (
+        <style href={PREFIX} precedence="dowel">
+          {STYLES}
+        </style>
+      ) : null}
+      <DialogPortal>
+        <DialogOverlay />
+        <DialogPrimitive.Content
+          data-slot="dialog-content"
+          data-animation={spring ? "spring" : undefined}
+          className={cn(
+            "fixed top-1/2 left-1/2 z-[var(--z-modal)] w-[calc(100%-2rem)] max-w-lg -translate-x-1/2 -translate-y-1/2",
+            "grid gap-4 rounded-xl border border-border bg-card p-6 text-card-foreground shadow-xl",
+            "data-[state=closed]:animate-dialog-out",
+            // Spelled out because Tailwind reads class names from the source.
+            spring
+              ? "data-[state=open]:animate-[dowel-dialog-spring-in_calc(250ms*var(--motion-scale))_var(--ease-overshoot)]"
+              : "data-[state=open]:animate-dialog-in",
+            className,
+          )}
+          {...props}
+        >
+          {children}
+          {showCloseButton ? (
+            <DialogPrimitive.Close
+              data-slot="dialog-close"
+              aria-label="Close"
+              className={cn(
+                "absolute end-4 top-4 grid size-7 place-items-center rounded-md text-muted-foreground",
+                "transition-colors duration-[var(--duration-fast)] hover:bg-accent hover:text-foreground",
+                "[&_svg]:size-4",
+                focusRing,
+              )}
+            >
+              <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
+                <path
+                  d="m6 6 12 12M18 6 6 18"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                  strokeLinecap="round"
+                />
+              </svg>
+            </DialogPrimitive.Close>
+          ) : null}
+        </DialogPrimitive.Content>
+      </DialogPortal>
+    </>
   );
 }
 
@@ -91,7 +134,7 @@ export function DialogHeader({ className, ...props }: ComponentPropsWithRef<"div
   return (
     <div
       data-slot="dialog-header"
-      className={cn("flex flex-col gap-1.5 pr-8 text-left", className)}
+      className={cn("flex flex-col gap-1.5 pe-8 text-start", className)}
       {...props}
     />
   );

package/src/components/dialog/meta.ts

@@ -12,5 +12,6 @@ export const meta = defineMeta({
   a11y:
     "Focus is trapped while open and restored to the trigger on close; Escape and an overlay " +
     "click dismiss. Always render a DialogTitle — it names the dialog for screen readers. " +
-    "Use DialogDescription, or aria-describedby, to explain consequential actions.",
+    "Use DialogDescription, or aria-describedby, to explain consequential actions. The " +
+    "optional spring entrance and section stagger stop under reduced motion.",
 });

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,15 +312,19 @@ 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} />
       <LineNumber value={row.after} />
-      <td className="w-4 pr-1 text-center text-muted-foreground select-none" aria-hidden="true">
+      <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 pr-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 pr-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} />
@@ -267,7 +406,7 @@ function LineNumber({ value }: { value?: number }) {
       // Decorative: the line number is orientation for a sighted reader, and
       // announcing two numbers before every line makes the diff unlistenable.
       aria-hidden="true"
-      className="w-10 border-r border-border bg-muted/40 px-2 py-0.5 text-right text-muted-foreground tabular-nums select-none"
+      className="w-10 border-e border-border bg-muted/40 px-2 py-0.5 text-end text-muted-foreground tabular-nums select-none"
     >
       {value ?? ""}
     </td>

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/direction/direction.tsx

@@ -0,0 +1,38 @@
+"use client";
+
+import { Direction as DirectionPrimitive } from "radix-ui";
+import type { ReactNode } from "react";
+
+/**
+ * Tells the component set which way the writing runs.
+ *
+ * Every direction-dependent style in this library is written logically —
+ * `ps-`, `me-`, `text-end` — so the CSS follows `dir` on its own. The
+ * primitives underneath do not: several of them read direction from React
+ * context rather than from the document, and with no provider they assume
+ * left-to-right and set `dir="ltr"` on their own elements. The result is a page
+ * that mirrors correctly except for its menus, selects and sliders, which is
+ * worse than one that does not mirror at all, because it looks deliberate.
+ *
+ * So an RTL application needs both: `dir` on the document for the CSS, and this
+ * for the primitives.
+ *
+ * ```tsx
+ * <html dir="rtl" lang="ar">
+ *   <body>
+ *     <DirectionProvider dir="rtl">{children}</DirectionProvider>
+ *   </body>
+ * </html>
+ * ```
+ *
+ * A left-to-right application needs neither. Nothing here is required to render
+ * English correctly, which is why it is easy to ship without it and never know.
+ */
+export interface DirectionProviderProps {
+  dir: "ltr" | "rtl";
+  children?: ReactNode;
+}
+
+export function DirectionProvider({ dir, children }: DirectionProviderProps) {
+  return <DirectionPrimitive.Provider dir={dir}>{children}</DirectionPrimitive.Provider>;
+}

package/src/components/direction/index.ts

@@ -0,0 +1 @@
+export { DirectionProvider, type DirectionProviderProps } from "./direction";

package/src/components/direction/meta.ts

@@ -0,0 +1,19 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "direction",
+  title: "Direction Provider",
+  description:
+    "Tells the component primitives which way the writing runs, so menus and sliders mirror with the rest of the page.",
+  category: "foundation",
+  status: "stable",
+  dependencies: ["radix-ui"],
+  registryDependencies: [],
+  files: ["direction.tsx"],
+  a11y:
+    "Needed only for right-to-left languages, and needed in addition to `dir` on the document " +
+    "rather than instead of it. The styling here is written with logical properties and follows " +
+    "`dir` by itself; the primitives underneath read direction from React context and assume " +
+    "left-to-right without a provider, which mirrors a page correctly except for its menus, " +
+    "selects and sliders — worse than not mirroring at all, because it looks deliberate.",
+});