@dowel-ui/react 0.5.0 → 0.8.0

package/src/components/ai-branch/meta.ts

@@ -0,0 +1,18 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "ai-branch",
+  title: "Branch",
+  description:
+    "Alternative versions of a conversation turn — regenerated answers, edited prompts — with a wrapping pager between them.",
+  category: "ai",
+  status: "beta",
+  dependencies: ["class-variance-authority"],
+  registryDependencies: ["button"],
+  files: ["ai-branch.tsx"],
+  a11y:
+    'The pager is a group named "Versions" with real Previous/Next buttons (their chevrons mirror in right-to-left ' +
+    'layouts) and a polite, atomic "2 of 3" indicator, so paging says where it went. Inactive versions are hidden ' +
+    "rather than unmounted, keeping their state. The pager disappears when there is only one version. The " +
+    "entrance is decoration and stops under reduced motion.",
+});

package/src/components/ai-conversation/ai-conversation.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+// Motion from SmoothUI AI Conversation (MIT, © 2024 Eduardo Calvo). See THIRD_PARTY_NOTICES.md.
 import {
   createContext,
   useCallback,
@@ -50,6 +51,19 @@ function useConversation(component: string): ConversationContextValue {
   return context;
 }
 
+/**
+ * Resolves `"smooth"` to `"auto"` for readers who asked for less motion.
+ *
+ * The theme's `scroll-behavior: auto !important` only governs the CSS default:
+ * an explicit `behavior: "smooth"` passed to `scrollTo` still animates, so the
+ * preference has to be honoured here.
+ */
+function resolveBehavior(behavior: ScrollBehavior): ScrollBehavior {
+  if (behavior !== "smooth") return behavior;
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return behavior;
+  return window.matchMedia("(prefers-reduced-motion: reduce)").matches ? "auto" : behavior;
+}
+
 /** How close to the bottom still counts as "at the bottom", in pixels. */
 const BOTTOM_THRESHOLD = 32;
 
@@ -74,7 +88,12 @@ export function Conversation({
   const scrollToBottom = useCallback((behavior: ScrollBehavior = "smooth") => {
     const viewport = viewportRef.current;
     if (!viewport) return;
-    viewport.scrollTo({ top: viewport.scrollHeight, behavior });
+    // jsdom and some embedded webviews have no Element.scrollTo.
+    if (typeof viewport.scrollTo !== "function") {
+      viewport.scrollTop = viewport.scrollHeight;
+      return;
+    }
+    viewport.scrollTo({ top: viewport.scrollHeight, behavior: resolveBehavior(behavior) });
   }, []);
 
   useEffect(() => {
@@ -153,9 +172,32 @@ export function ConversationMessages({ className, ...props }: ComponentPropsWith
   );
 }
 
+/**
+ * The conversation's state, in SmoothUI's AIState vocabulary.
+ *
+ * Named for this component rather than `AIState` so it can never collide with
+ * a shared type exported elsewhere in the library.
+ */
+export type ConversationState =
+  "idle" | "listening" | "thinking" | "streaming" | "done" | "error";
+
+/** Default wording per state. `idle` is empty, so first paint announces nothing. */
+const STATE_LABELS: Record<ConversationState, string> = {
+  idle: "",
+  listening: "Listening",
+  thinking: "Thinking",
+  streaming: "Generating response",
+  done: "Response complete",
+  error: "Response failed",
+};
+
 export interface ConversationStatusProps extends ComponentPropsWithRef<"div"> {
   /** Announced politely when it changes. Keep it short: state, never content. */
   children?: ReactNode;
+  /** Renders default wording for a state. `children` wins when both are given. */
+  state?: ConversationState;
+  /** Overrides the default wording per state. */
+  stateLabels?: Partial<Record<ConversationState, string>>;
 }
 
 /**
@@ -165,7 +207,17 @@ export interface ConversationStatusProps extends ComponentPropsWithRef<"div"> {
  * the response *text* here instead is the mistake this component exists to
  * prevent.
  */
-export function ConversationStatus({ className, children, ...props }: ConversationStatusProps) {
+export function ConversationStatus({
+  className,
+  children,
+  state,
+  stateLabels,
+  ...props
+}: ConversationStatusProps) {
+  // Only the text changes with `state`: the region itself stays mounted from
+  // first paint, because a live region announces nothing until it exists.
+  const worded =
+    state === undefined ? undefined : (stateLabels?.[state] ?? STATE_LABELS[state]);
   return (
     <div
       data-slot="conversation-status"
@@ -174,7 +226,7 @@ export function ConversationStatus({ className, children, ...props }: Conversati
       className={cn("px-4 text-xs text-muted-foreground", className)}
       {...props}
     >
-      {children}
+      {children ?? worded}
     </div>
   );
 }
@@ -183,47 +235,106 @@ export interface ConversationScrollButtonProps extends ComponentPropsWithRef<"bu
   label?: string;
 }
 
+const PREFIX = "dowel-ai-conversation";
+
+/* The pill rises in and sinks out. Exits are one step faster than entrances
+ * (ADR 0004), and both run through --motion-scale, so under reduced motion the
+ * exit still ends — which is what unmounts the button. */
+const STYLES = `
+@keyframes ${PREFIX}-pill-in{from{opacity:0;translate:0 8px;scale:.96}}
+@keyframes ${PREFIX}-pill-out{to{opacity:0;translate:0 8px;scale:.96}}
+[data-slot=conversation-scroll-button][data-state=open]{animation:${PREFIX}-pill-in calc(250ms * var(--motion-scale,1)) var(--ease-out-quint) both}
+[data-slot=conversation-scroll-button][data-state=closed]{animation:${PREFIX}-pill-out calc(130ms * var(--motion-scale,1)) var(--ease-in-quint) both;pointer-events:none}
+`;
+
+/** Unmounts a closing pill even if its exit animation never reports ending. */
+const EXIT_FALLBACK_MS = 400;
+
+type PillPhase = "hidden" | "open" | "closing";
+
 /**
  * Returns the reader to the newest message.
  *
  * Rendered only when they have scrolled away, and removed from the DOM
  * otherwise so it is never a focus stop pointing at where the reader already
- * is.
+ * is. While it plays its exit it is `inert` and `aria-hidden`: already gone as
+ * far as focus, clicks and assistive technology are concerned.
  */
 export function ConversationScrollButton({
   className,
   label = "Jump to latest",
+  ref,
   ...props
 }: ConversationScrollButtonProps) {
   const { atBottom, scrollToBottom } = useConversation("ConversationScrollButton");
-  if (atBottom) return null;
+  const [phase, setPhase] = useState<PillPhase>(atBottom ? "hidden" : "open");
+  const buttonRef = useRef<HTMLButtonElement | null>(null);
+
+  // Adjusted during render rather than in an effect, so the pill never paints
+  // a frame in the wrong state.
+  if (!atBottom && phase !== "open") setPhase("open");
+  if (atBottom && phase === "open") setPhase("closing");
+
+  // A native listener rather than onAnimationEnd: React picks a vendor-prefixed
+  // event name wherever AnimationEvent is missing, and would never hear it.
+  useEffect(() => {
+    if (phase !== "closing") return;
+    const button = buttonRef.current;
+    const finish = (event?: Event) => {
+      if (event && event.target !== button) return;
+      setPhase("hidden");
+    };
+    const timer = setTimeout(finish, EXIT_FALLBACK_MS);
+    button?.addEventListener("animationend", finish);
+    return () => {
+      clearTimeout(timer);
+      button?.removeEventListener("animationend", finish);
+    };
+  }, [phase]);
+
+  if (phase === "hidden") return null;
+  const closing = phase === "closing";
 
   return (
-    <button
-      type="button"
-      data-slot="conversation-scroll-button"
-      onClick={() => {
-        scrollToBottom();
-      }}
-      className={cn(
-        "absolute bottom-3 left-1/2 z-[var(--z-sticky)] flex -translate-x-1/2 items-center gap-1.5",
-        "rounded-full border border-border bg-popover px-3 py-1.5 text-xs font-medium shadow-md",
-        "transition-colors duration-[var(--duration-fast)] hover:bg-accent",
-        "outline-none focus-visible:ring-2 focus-visible:ring-ring/55",
-        className,
-      )}
-      {...props}
-    >
-      <svg viewBox="0 0 24 24" fill="none" aria-hidden="true" className="size-3.5">
-        <path
-          d="M12 5v14m0 0-6-6m6 6 6-6"
-          stroke="currentColor"
-          strokeWidth="2"
-          strokeLinecap="round"
-          strokeLinejoin="round"
-        />
-      </svg>
-      {label}
-    </button>
+    <>
+      <style href={PREFIX} precedence="dowel">
+        {STYLES}
+      </style>
+      <button
+        type="button"
+        ref={(node) => {
+          buttonRef.current = node;
+          if (typeof ref === "function") return ref(node);
+          if (ref) ref.current = node;
+        }}
+        data-slot="conversation-scroll-button"
+        data-state={closing ? "closed" : "open"}
+        inert={closing || undefined}
+        aria-hidden={closing || undefined}
+        tabIndex={closing ? -1 : undefined}
+        onClick={() => {
+          scrollToBottom();
+        }}
+        className={cn(
+          "absolute inset-x-0 bottom-3 z-[var(--z-sticky)] mx-auto flex w-fit items-center gap-1.5",
+          "rounded-full border border-border bg-popover px-3 py-1.5 text-xs font-medium shadow-md",
+          "transition-colors duration-[var(--duration-fast)] hover:bg-accent",
+          "outline-none focus-visible:ring-2 focus-visible:ring-ring/55",
+          className,
+        )}
+        {...props}
+      >
+        <svg viewBox="0 0 24 24" fill="none" aria-hidden="true" className="size-3.5">
+          <path
+            d="M12 5v14m0 0-6-6m6 6 6-6"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          />
+        </svg>
+        {label}
+      </button>
+    </>
   );
 }

package/src/components/ai-conversation/index.ts

@@ -5,5 +5,6 @@ export {
   ConversationStatus,
   type ConversationProps,
   type ConversationScrollButtonProps,
+  type ConversationState,
   type ConversationStatusProps,
 } from "./ai-conversation";

package/src/components/ai-extraction-review/ai-extraction-review.tsx

@@ -456,7 +456,7 @@ function ReviewField({
           {sourced ? (
             <FieldButton
               aria-label={`Show in source — ${field.label}`}
-              className="ml-auto"
+              className="ms-auto"
               onClick={onActivate}
             >
               Show in source

package/src/components/ai-loader/ai-loader.tsx

@@ -0,0 +1,112 @@
+"use client";
+
+// Ported from SmoothUI AI Loader (MIT, © 2024 Eduardo Calvo). See THIRD_PARTY_NOTICES.md.
+import { cva, type VariantProps } from "class-variance-authority";
+import { useEffect, useState, type ComponentPropsWithRef } from "react";
+
+import { BarLoader } from "@/components/bar-loader";
+import { DotsLoader } from "@/components/dots-loader";
+import { GridLoader } from "@/components/grid-loader";
+import { cn } from "@/lib/utils";
+
+/*
+ * The AI waiting indicator: a label, one of three loaders, and an optional
+ * elapsed counter. The motion is not reimplemented here — it is Dowel's own
+ * loader families, whose "thinking" dots, indeterminate bar and "thinking"
+ * grid already share SmoothUI's 1.2s cycle, so a page can mix them and stay in
+ * step. They carry data-motion="indicator" themselves: under reduced motion
+ * they slow rather than freeze.
+ *
+ * The root is the one status region. The loader inside it stays aria-hidden,
+ * and the elapsed counter is hidden from assistive technology too: a live
+ * region whose text changes ten times a second would announce continuously.
+ */
+
+export type AILoaderVariant = "dots" | "bar" | "grid";
+
+const aiLoaderVariants = cva("inline-flex items-center gap-2 text-muted-foreground", {
+  variants: {
+    size: {
+      sm: "text-xs",
+      md: "text-sm",
+      lg: "text-base",
+    },
+  },
+  defaultVariants: {
+    size: "md",
+  },
+});
+
+const LOADER_SIZE = { sm: "sm", md: "md", lg: "lg" } as const;
+
+/** Seconds since mount, to one decimal, re-rendering only when that changes. */
+function useElapsed(enabled: boolean): number {
+  const [tenths, setTenths] = useState(0);
+  useEffect(() => {
+    if (!enabled) return;
+    const start = performance.now();
+    const id = setInterval(() => {
+      setTenths(Math.floor((performance.now() - start) / 100));
+    }, 100);
+    return () => clearInterval(id);
+  }, [enabled]);
+  return tenths / 10;
+}
+
+export interface AILoaderProps
+  extends
+    Omit<ComponentPropsWithRef<"span">, "children">,
+    VariantProps<typeof aiLoaderVariants> {
+  /** Which loader: thinking dots, an indeterminate bar, or a thinking grid. */
+  variant?: AILoaderVariant;
+  /** Visible text before the indicator, e.g. "Thinking". Also what is announced. */
+  label?: string;
+  /** Announced when there is no visible label. */
+  srLabel?: string;
+  /** Appends a live elapsed-seconds counter. Long waits need a sign of progress. */
+  showElapsed?: boolean;
+}
+
+/** A labelled AI waiting indicator, optionally counting the seconds. */
+export function AILoader({
+  className,
+  variant = "dots",
+  size,
+  label,
+  srLabel = "Loading",
+  showElapsed = false,
+  ...props
+}: AILoaderProps) {
+  const elapsed = useElapsed(showElapsed);
+  const loaderSize = LOADER_SIZE[size ?? "md"];
+
+  return (
+    <span
+      role="status"
+      data-slot="ai-loader"
+      data-variant={variant}
+      className={cn(aiLoaderVariants({ size }), className)}
+      {...props}
+    >
+      {label ? (
+        <span data-slot="ai-loader-label">{label}</span>
+      ) : (
+        <span className="sr-only">{srLabel}</span>
+      )}
+      {variant === "dots" ? <DotsLoader variant="thinking" size={loaderSize} /> : null}
+      {variant === "bar" ? <BarLoader variant="indeterminate" size={loaderSize} /> : null}
+      {variant === "grid" ? <GridLoader variant="thinking" size={loaderSize} /> : null}
+      {showElapsed ? (
+        <span
+          data-slot="ai-loader-elapsed"
+          aria-hidden="true"
+          className="tabular-nums opacity-60"
+        >
+          {elapsed.toFixed(1)}s
+        </span>
+      ) : null}
+    </span>
+  );
+}
+
+export { aiLoaderVariants };

package/src/components/ai-loader/index.ts

@@ -0,0 +1,6 @@
+export {
+  AILoader,
+  aiLoaderVariants,
+  type AILoaderProps,
+  type AILoaderVariant,
+} from "./ai-loader";

package/src/components/ai-loader/meta.ts

@@ -0,0 +1,18 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "ai-loader",
+  title: "AI Loader",
+  description:
+    "A labelled AI waiting indicator — thinking dots, an indeterminate bar or a thinking grid — with an optional elapsed-seconds counter.",
+  category: "ai",
+  status: "beta",
+  dependencies: ["class-variance-authority"],
+  registryDependencies: ["bar-loader", "dots-loader", "grid-loader"],
+  files: ["ai-loader.tsx"],
+  a11y:
+    'The root is a single role="status" region announcing the label (or `srLabel`, "Loading" by default). The ' +
+    "loader inside it and the elapsed counter are aria-hidden — a counter ticking ten times a second inside a " +
+    "live region would announce continuously. The loaders are indicators: under reduced motion they slow rather " +
+    "than stop. None fakes determinate progress.",
+});

package/src/components/ai-message/ai-message.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+// Motion from SmoothUI AI Message (MIT, © 2024 Eduardo Calvo). See THIRD_PARTY_NOTICES.md.
 import { cva, type VariantProps } from "class-variance-authority";
 import { Slot } from "radix-ui";
 import type { ComponentPropsWithRef } from "react";
@@ -126,23 +127,67 @@ export function MessageAvatar({ className, asChild, ...props }: MessageAvatarPro
   );
 }
 
+const PREFIX = "dowel-ai-message";
+
+/*
+ * Only a private custom property lives here: which way the actions slide in.
+ * They come out of the bubble's own edge — the inline start for the assistant,
+ * the inline end for the user — and the sign flips in RTL. Everything visible
+ * is a layered utility on the container, so a consumer className still wins.
+ */
+const STYLES = `
+[data-slot=message-actions]{--dowel-message-slide:-6px}
+[data-from=user] [data-slot=message-actions]{--dowel-message-slide:6px}
+[data-slot=message-actions]:dir(rtl){--dowel-message-slide:6px}
+[data-from=user] [data-slot=message-actions]:dir(rtl){--dowel-message-slide:-6px}
+`;
+
 /**
  * Per-message controls: copy, regenerate, feedback.
  *
  * Revealed on hover for pointer users but always present in the DOM and in the
  * tab order — hiding controls behind hover makes them unreachable by keyboard
- * and invisible on touch.
+ * and invisible on touch. On devices that cannot hover they are always shown.
  */
 export function MessageActions({ className, ...props }: ComponentPropsWithRef<"div">) {
   return (
-    <div
-      data-slot="message-actions"
-      className={cn(
-        "mt-1.5 flex items-center gap-1",
-        "opacity-0 transition-opacity duration-[var(--duration-fast)]",
-        "group-focus-within/message:opacity-100 group-hover/message:opacity-100",
-        className,
-      )}
+    <>
+      <style href={PREFIX} precedence="dowel">
+        {STYLES}
+      </style>
+      <div
+        data-slot="message-actions"
+        className={cn(
+          "mt-1.5 flex items-center gap-1",
+          "translate-x-(--dowel-message-slide) scale-90 opacity-0",
+          "transition-[opacity,translate,scale] duration-[var(--duration-normal)] ease-[var(--ease-out-quint)]",
+          "group-focus-within/message:translate-x-0 group-focus-within/message:scale-100 group-focus-within/message:opacity-100",
+          "group-hover/message:translate-x-0 group-hover/message:scale-100 group-hover/message:opacity-100",
+          "[@media(hover:none)]:translate-x-0 [@media(hover:none)]:scale-100 [@media(hover:none)]:opacity-100",
+          className,
+        )}
+        {...props}
+      />
+    </>
+  );
+}
+
+export interface MessageTimestampProps extends ComponentPropsWithRef<"time"> {
+  /** Machine-readable value for `dateTime`. Children are the display text. */
+  dateTime?: string;
+}
+
+/**
+ * When the message was sent.
+ *
+ * A real `<time>`, so the display text can be relative ("2 min ago") while the
+ * machine-readable value stays exact.
+ */
+export function MessageTimestamp({ className, ...props }: MessageTimestampProps) {
+  return (
+    <time
+      data-slot="message-timestamp"
+      className={cn("text-xs text-muted-foreground tabular-nums", className)}
       {...props}
     />
   );

package/src/components/ai-message/index.ts

@@ -4,10 +4,12 @@ export {
   MessageAvatar,
   MessageBody,
   MessageFooter,
+  MessageTimestamp,
   messageBodyVariants,
   messageVariants,
   type MessageAvatarProps,
   type MessageBodyProps,
   type MessageProps,
   type MessageRole,
+  type MessageTimestampProps,
 } from "./ai-message";

package/src/components/ai-message/meta.ts

@@ -13,5 +13,6 @@ export const meta = defineMeta({
     "Every message carries a visually hidden label naming the speaker. Alignment and colour tell " +
     "a sighted reader who is talking and tell a screen reader user nothing, so the role is always " +
     "in text. Message actions fade in on hover but stay in the DOM and in the tab order — a " +
-    "control that only exists on hover is unreachable by keyboard and invisible on touch.",
+    "control that only exists on hover is unreachable by keyboard and invisible on touch — and " +
+    "on devices that cannot hover they are always shown. MessageTimestamp is a real <time>.",
 });

package/src/components/ai-prompt-input/ai-prompt-input.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+// Motion from SmoothUI AI Prompt Input (MIT, © 2024 Eduardo Calvo). See THIRD_PARTY_NOTICES.md.
 import {
   createContext,
   useContext,
@@ -214,41 +215,67 @@ export function PromptInputSubmit({
 }: PromptInputSubmitProps) {
   const { busy, disabled } = usePromptInput("PromptInputSubmit");
 
+  // Both glyphs stay mounted in one grid cell and cross-fade, so the swap is a
+  // scale-and-fade rather than a jump. The accessible name carries the state;
+  // the glyphs are decoration.
+  const glyph =
+    "col-start-1 row-start-1 transition-[opacity,scale] duration-[var(--duration-normal)] ease-[var(--ease-out-quint)]";
+
   return (
     <button
       type={busy ? "button" : "submit"}
       data-slot="prompt-input-submit"
+      data-state={busy ? "stop" : "send"}
       aria-label={busy ? stopLabel : label}
       disabled={disabled}
       onClick={busy ? onStop : undefined}
       className={cn(
-        "ml-auto grid size-8 shrink-0 place-items-center rounded-lg",
-        "bg-primary text-primary-foreground transition-colors duration-[var(--duration-fast)]",
-        "hover:bg-primary-hover disabled:pointer-events-none disabled:opacity-55",
+        "ms-auto grid size-8 shrink-0 place-items-center rounded-lg",
+        "bg-primary text-primary-foreground",
+        "transition-[color,background-color,scale] duration-[var(--duration-fast)] ease-[var(--ease-out-quint)]",
+        "hover:scale-105 hover:bg-primary-hover active:scale-95",
+        "disabled:pointer-events-none disabled:scale-100 disabled:opacity-55",
         focusRing,
         className,
       )}
       {...props}
     >
-      {busy ? (
-        <svg viewBox="0 0 24 24" fill="none" aria-hidden="true" className="size-3.5">
-          <rect x="6" y="6" width="12" height="12" rx="2" fill="currentColor" />
-        </svg>
-      ) : (
-        <svg viewBox="0 0 24 24" fill="none" aria-hidden="true" className="size-4">
-          <path
-            d="M12 19V5m0 0-6 6m6-6 6 6"
-            stroke="currentColor"
-            strokeWidth="2"
-            strokeLinecap="round"
-            strokeLinejoin="round"
-          />
-        </svg>
-      )}
+      <svg
+        viewBox="0 0 24 24"
+        fill="none"
+        aria-hidden="true"
+        data-glyph="send"
+        className={cn(glyph, "size-4", busy ? "scale-60 opacity-0" : "scale-100 opacity-100")}
+      >
+        <path
+          d="M12 19V5m0 0-6 6m6-6 6 6"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+      </svg>
+      <svg
+        viewBox="0 0 24 24"
+        fill="none"
+        aria-hidden="true"
+        data-glyph="stop"
+        className={cn(glyph, "size-3.5", busy ? "scale-100 opacity-100" : "scale-60 opacity-0")}
+      >
+        <rect x="6" y="6" width="12" height="12" rx="2" fill="currentColor" />
+      </svg>
     </button>
   );
 }
 
+const PREFIX = "dowel-ai-prompt-input";
+
+/* The "value / max" reading rises in once, when the limit first matters. */
+const STYLES = `
+@keyframes ${PREFIX}-counter-in{from{opacity:0;translate:0 4px}}
+[data-slot=prompt-input-counter-value][data-warning]{display:inline-block;animation:${PREFIX}-counter-in calc(200ms * var(--motion-scale,1)) var(--ease-out-quint) both}
+`;
+
 export interface PromptInputCounterProps extends ComponentPropsWithRef<"div"> {
   value: number;
   max: number;
@@ -291,7 +318,18 @@ export function PromptInputCounter({
       )}
       {...props}
     >
-      <span aria-hidden="true">
+      <style href={PREFIX} precedence="dowel">
+        {STYLES}
+      </style>
+      {/* Keyed so crossing the threshold remounts the visible reading, which is
+          what plays its entrance. Never key the status span below: it has to
+          stay the same live region from first paint (ADR 0009). */}
+      <span
+        key={warning ? "limit" : "count"}
+        aria-hidden="true"
+        data-slot="prompt-input-counter-value"
+        data-warning={warning || undefined}
+      >
         {warning ? `${String(value)} / ${String(max)}` : String(value)}
       </span>
       <span role="status" aria-live="polite" className="sr-only">