@dowel-ui/react 0.5.0 → 0.8.0

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

@@ -1,8 +1,17 @@
 "use client";
 
+// Motion from SmoothUI AI Reasoning (MIT, © 2024 Eduardo Calvo). See THIRD_PARTY_NOTICES.md.
 import { Collapsible as CollapsiblePrimitive } from "radix-ui";
-import type { ComponentPropsWithRef } from "react";
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  type ComponentPropsWithRef,
+} from "react";
 
+import { ShimmerText } from "@/components/shimmer-text";
 import { focusRing } from "@/lib/styles";
 import { cn } from "@/lib/utils";
 
@@ -14,35 +23,194 @@ import { cn } from "@/lib/utils";
  * and most readers never want it. It stays one keystroke away for the people
  * who do.
  */
-export type ReasoningProps = ComponentPropsWithRef<typeof CollapsiblePrimitive.Root>;
 
-export function Reasoning({ className, ...props }: ReasoningProps) {
+/** Delay before `autoCollapse={true}` closes the trace, in milliseconds. */
+const AUTO_COLLAPSE_DELAY = 600;
+
+interface ReasoningContextValue {
+  streaming: boolean | undefined;
+}
+
+const ReasoningContext = createContext<ReasoningContextValue>({ streaming: undefined });
+
+export interface ReasoningProps extends Omit<
+  ComponentPropsWithRef<typeof CollapsiblePrimitive.Root>,
+  "onOpenChange"
+> {
+  /** Called when the reader opens or closes the trace. */
+  onOpenChange?: (open: boolean) => void;
+  /**
+   * Reasoning is still arriving. Feeds the trigger's default label and the
+   * auto behaviours below.
+   */
+  streaming?: boolean;
+  /**
+   * Open when `streaming` turns true, until the reader toggles it themselves.
+   *
+   * Off by default (ADR 0009): an open trace gives reasoning the same weight
+   * as the answer while it streams. Ignored when `open` is controlled.
+   */
+  autoOpen?: boolean;
+  /**
+   * Close after streaming ends, unless the reader has toggled it; a number is
+   * the delay in milliseconds. Never closes while focus or the pointer is
+   * inside the trace. Ignored when `open` is controlled.
+   */
+  autoCollapse?: boolean | number;
+}
+
+export function Reasoning({
+  className,
+  streaming,
+  autoOpen = false,
+  autoCollapse = false,
+  open,
+  defaultOpen,
+  onOpenChange,
+  ref,
+  ...props
+}: ReasoningProps) {
+  const controlled = open !== undefined;
+  const automatic = !controlled && (autoOpen || autoCollapse !== false);
+  const collapseDelay =
+    typeof autoCollapse === "number" ? autoCollapse : autoCollapse ? AUTO_COLLAPSE_DELAY : null;
+
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  // A trace mounted mid-stream opens straight away under autoOpen.
+  const [internalOpen, setInternalOpen] = useState(
+    () => defaultOpen ?? (automatic && autoOpen && streaming === true),
+  );
+  // Once the reader has toggled it, the component stops deciding for them.
+  const [userToggled, setUserToggled] = useState(false);
+  const [previousStreaming, setPreviousStreaming] = useState(streaming);
+  const [pendingCollapse, setPendingCollapse] = useState(false);
+
+  // Streaming edges, adjusted during render so there is no frame in between.
+  if (streaming !== previousStreaming) {
+    setPreviousStreaming(streaming);
+    if (automatic && !userToggled) {
+      if (streaming) {
+        setPendingCollapse(false);
+        if (autoOpen) setInternalOpen(true);
+      } else if (previousStreaming && collapseDelay !== null) {
+        setPendingCollapse(true);
+      }
+    }
+  }
+
+  useEffect(() => {
+    if (!pendingCollapse || collapseDelay === null) return;
+    const timer = setTimeout(() => {
+      setPendingCollapse(false);
+      // Never yank the trace out from under someone reading or tabbing in it.
+      const content = rootRef.current?.querySelector("[data-slot='reasoning-content']");
+      if (content?.contains(document.activeElement) || content?.matches(":hover")) return;
+      setInternalOpen(false);
+    }, collapseDelay);
+    return () => {
+      clearTimeout(timer);
+    };
+  }, [pendingCollapse, collapseDelay]);
+
+  useEffect(() => {
+    if (process.env.NODE_ENV === "production") return;
+    if (!controlled || (!autoOpen && autoCollapse === false)) return;
+    console.warn(
+      "Reasoning: `autoOpen` and `autoCollapse` are ignored when `open` is controlled. " +
+        "Drive `open` from `streaming` yourself, or drop `open`.",
+    );
+  }, [controlled, autoOpen, autoCollapse]);
+
+  const openProps = automatic
+    ? {
+        open: internalOpen,
+        onOpenChange: (next: boolean) => {
+          setUserToggled(true);
+          setPendingCollapse(false);
+          setInternalOpen(next);
+          onOpenChange?.(next);
+        },
+      }
+    : { open, defaultOpen, onOpenChange };
+
   return (
-    <CollapsiblePrimitive.Root
-      data-slot="reasoning"
-      className={cn("text-sm", className)}
-      {...props}
-    />
+    <ReasoningContext.Provider value={{ streaming }}>
+      <CollapsiblePrimitive.Root
+        ref={(node: HTMLDivElement | null) => {
+          rootRef.current = node;
+          if (typeof ref === "function") return ref(node);
+          if (ref) ref.current = node;
+        }}
+        data-slot="reasoning"
+        data-streaming={streaming || undefined}
+        className={cn("text-sm", className)}
+        {...openProps}
+        {...props}
+      />
+    </ReasoningContext.Provider>
   );
 }
 
+/**
+ * Seconds between `active` turning true and turning false, for "Thought for
+ * 4.2s". `null` until the first run ends; a new run keeps the last value
+ * until it, too, ends.
+ */
+export function useElapsedSeconds(active: boolean): number | null {
+  const startedAt = useRef<number | null>(null);
+  const [elapsed, setElapsed] = useState<number | null>(null);
+
+  useEffect(() => {
+    if (active) {
+      startedAt.current = performance.now();
+      return;
+    }
+    const start = startedAt.current;
+    if (start === null) return;
+    startedAt.current = null;
+    setElapsed((performance.now() - start) / 1000);
+  }, [active]);
+
+  return elapsed;
+}
+
 export interface ReasoningTriggerProps extends ComponentPropsWithRef<
   typeof CollapsiblePrimitive.Trigger
 > {
-  /** Shown while reasoning is still arriving. */
+  /** Shown while reasoning is still arriving. Defaults to the root's `streaming`. */
   streaming?: boolean;
   label?: string;
   streamingLabel?: string;
+  /**
+   * Seconds spent reasoning. When set and not streaming, the label becomes
+   * `durationLabel(duration)`. Pair it with `useElapsedSeconds`.
+   */
+  duration?: number;
+  /** Words for a duration. */
+  durationLabel?: (seconds: number) => string;
+  /** Shimmer the label while streaming. Decoration: it stops under reduced motion. */
+  shimmer?: boolean;
+}
+
+function defaultDurationLabel(seconds: number): string {
+  return `Thought for ${seconds.toFixed(1)}s`;
 }
 
 export function ReasoningTrigger({
   className,
-  streaming,
+  streaming: streamingProp,
   label = "Reasoning",
   streamingLabel = "Thinking…",
+  duration,
+  durationLabel = defaultDurationLabel,
+  shimmer = false,
   children,
   ...props
 }: ReasoningTriggerProps) {
+  const context = useContext(ReasoningContext);
+  const streaming = streamingProp ?? context.streaming;
+  const idleLabel = duration === undefined ? label : durationLabel(duration);
+
   return (
     <CollapsiblePrimitive.Trigger
       data-slot="reasoning-trigger"
@@ -64,12 +232,23 @@ export function ReasoningTrigger({
           strokeLinejoin="round"
         />
       </svg>
-      {children ?? (streaming ? streamingLabel : label)}
+      {children ??
+        (streaming ? (
+          shimmer ? (
+            <ShimmerText duration={1800} repeatDelay={0}>
+              {streamingLabel}
+            </ShimmerText>
+          ) : (
+            streamingLabel
+          )
+        ) : (
+          idleLabel
+        ))}
       <svg
         viewBox="0 0 24 24"
         fill="none"
         aria-hidden="true"
-        className="size-3.5 shrink-0 transition-transform duration-[var(--duration-normal)]"
+        className="size-3.5 shrink-0 transition-transform duration-[var(--duration-normal)] ease-[var(--ease-out-quint)]"
       >
         <path
           d="m6 9 6 6 6-6"
@@ -98,7 +277,7 @@ export function ReasoningContent({
       )}
       {...props}
     >
-      <div className="mt-2 border-l-2 border-border pl-3 text-sm whitespace-pre-wrap text-muted-foreground">
+      <div className="mt-2 border-s-2 border-border ps-3 text-sm whitespace-pre-wrap text-muted-foreground">
         {children}
       </div>
     </CollapsiblePrimitive.Content>

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

@@ -2,6 +2,7 @@ export {
   Reasoning,
   ReasoningContent,
   ReasoningTrigger,
+  useElapsedSeconds,
   type ReasoningProps,
   type ReasoningTriggerProps,
 } from "./ai-reasoning";

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

@@ -7,11 +7,13 @@ export const meta = defineMeta({
   category: "ai",
   status: "stable",
   dependencies: ["radix-ui"],
-  registryDependencies: [],
+  registryDependencies: ["shimmer-text"],
   files: ["ai-reasoning.tsx"],
   a11y:
     "A standard disclosure with aria-expanded on the trigger. Collapsed by default because " +
     "reasoning is supporting material — giving it the same weight as the answer buries the " +
     "answer. The trigger's label changes while reasoning streams, so its accessible name matches " +
-    "what is happening.",
+    'what is happening — and to "Thought for 4.2s" when given a duration. autoOpen and ' +
+    "autoCollapse are opt-in; auto-collapse never closes the trace while focus or the pointer is " +
+    "inside it. The optional shimmer is decoration and stops under reduced motion.",
 });

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

@@ -1,5 +1,6 @@
 "use client";
 
+// Motion from SmoothUI AI Response (MIT, © 2024 Eduardo Calvo). See THIRD_PARTY_NOTICES.md.
 import type { ComponentPropsWithRef } from "react";
 
 import { cn } from "@/lib/utils";
@@ -31,7 +32,7 @@ export function Response({ className, streaming, children, ...props }: ResponseP
         // Minimal prose styling for consumers who pass rendered Markdown.
         "[&_a]:text-primary [&_a]:underline [&_a]:underline-offset-4",
         "[&_code]:rounded [&_code]:bg-muted [&_code]:px-1 [&_code]:py-0.5 [&_code]:font-mono [&_code]:text-[0.9em]",
-        "[&_ol]:my-2 [&_ol]:list-decimal [&_ol]:pl-5 [&_ul]:my-2 [&_ul]:list-disc [&_ul]:pl-5",
+        "[&_ol]:my-2 [&_ol]:list-decimal [&_ol]:ps-5 [&_ul]:my-2 [&_ul]:list-disc [&_ul]:ps-5",
         "[&_p+p]:mt-3",
         className,
       )}
@@ -52,7 +53,7 @@ export function ResponseCaret({ className, ...props }: ComponentPropsWithRef<"sp
       aria-hidden="true"
       data-motion="indicator"
       className={cn(
-        "ml-0.5 inline-block h-[1em] w-[2px] translate-y-[0.15em] animate-caret bg-current align-baseline",
+        "ms-0.5 inline-block h-[1em] w-[2px] translate-y-[0.15em] animate-caret bg-current align-baseline",
         className,
       )}
       {...props}
@@ -66,6 +67,10 @@ export function ResponseCaret({ className, ...props }: ComponentPropsWithRef<"sp
  * A distinct state from streaming: nothing has arrived yet, so there is no text
  * to show a caret after. Labelled for assistive technology because, unlike the
  * caret, this is the only thing on screen.
+ *
+ * An indicator in the ADR 0012 sense: it is the only sign that anything is
+ * happening, and a frozen one says the app has hung. So under reduced motion
+ * the dots slow (via --motion-scale-indicator) rather than stop.
  */
 export interface ThinkingIndicatorProps extends ComponentPropsWithRef<"div"> {
   label?: string;
@@ -87,8 +92,12 @@ export function ThinkingIndicator({
         <span
           key={index}
           aria-hidden="true"
+          data-motion="indicator"
           className="size-1.5 animate-pulse-soft rounded-full bg-current"
-          style={{ animationDelay: `${String(index * 160)}ms` }}
+          style={{
+            animationDuration: "calc(1.8s * var(--motion-scale-indicator, 1))",
+            animationDelay: `calc(${String(index * 160)}ms * var(--motion-scale-indicator, 1))`,
+          }}
         />
       ))}
     </div>

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

@@ -5,3 +5,4 @@ export {
   type ResponseProps,
   type ThinkingIndicatorProps,
 } from "./ai-response";
+export { ResponseText, type ResponseCitation, type ResponseTextProps } from "./response-text";

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

@@ -7,11 +7,14 @@ export const meta = defineMeta({
   category: "ai",
   status: "stable",
   dependencies: [],
-  registryDependencies: [],
-  files: ["ai-response.tsx"],
+  registryDependencies: ["ai-sources"],
+  files: ["ai-response.tsx", "response-text.tsx"],
   a11y:
     "Deliberately not a live region: announcing streamed text as it arrives interrupts a screen " +
     "reader user on every token. Announce state through ConversationStatus and let them read the " +
     "response when it settles. The caret is decorative; ThinkingIndicator carries a label because " +
-    "it is the only thing on screen while waiting for the first token.",
+    "it is the only thing on screen while waiting for the first token, and it slows rather than " +
+    "stops under reduced motion because a frozen one says the app has hung. ResponseText blurs " +
+    "in only newly arrived words, adds no live region, and leaves the text content unchanged; " +
+    "its [n] markers are InlineCitations named by their source title.",
 });

package/src/components/ai-response/response-text.tsx

@@ -0,0 +1,119 @@
+"use client";
+
+// Motion from SmoothUI AI Response (MIT, © 2024 Eduardo Calvo). See THIRD_PARTY_NOTICES.md.
+import { useState, type ComponentPropsWithRef, type ReactNode } from "react";
+
+import { InlineCitation } from "@/components/ai-sources";
+import { cn } from "@/lib/utils";
+
+/**
+ * Streamed plain text whose words blur in as they arrive.
+ *
+ * Only words that arrive after the first render animate. Keys are positional,
+ * so a word that already exists keeps its DOM node — and a node that is not
+ * remounted does not replay its entrance. That is "animate only what arrived"
+ * without reading a ref during render. There is no stagger: token arrival is
+ * the stagger.
+ *
+ * Whitespace and bare punctuation stay text nodes, so text extraction is
+ * unchanged and a line never breaks between a word and its comma. `[n]`
+ * markers matching a citation become `InlineCitation`s, which carry the
+ * source title in their accessible name.
+ *
+ * Like `Response`, this is not a live region: announcing a stream token by
+ * token is unusable with a screen reader (ADR 0009).
+ */
+
+export interface ResponseCitation {
+  /** Matches the `[n]` marker in the text. */
+  index: number;
+  /** Becomes the citation's accessible name. */
+  title: string;
+  /** Without one the marker is text, not a dead link. */
+  href?: string;
+}
+
+export interface ResponseTextProps extends Omit<ComponentPropsWithRef<"span">, "children"> {
+  /** The plain-text stream so far. Re-render it as it grows. */
+  text: string;
+  /** Sources for `[n]` markers. Unmatched markers stay literal text. */
+  citations?: ResponseCitation[];
+  /**
+   * Animate the words present on first render. Off by default, so a replayed
+   * transcript does not blur in its entire history.
+   */
+  animateInitial?: boolean;
+}
+
+const PREFIX = "dowel-ai-response";
+
+const STYLES = `
+@keyframes ${PREFIX}-word{from{opacity:0;filter:blur(4px);translate:0 2px}}
+@keyframes ${PREFIX}-pop{from{opacity:0;scale:.6}}
+.${PREFIX}-word{display:inline-block;animation:${PREFIX}-word calc(220ms * var(--motion-scale,1)) var(--ease-out-quint) both}
+.${PREFIX}-pop{display:inline-block;animation:${PREFIX}-pop calc(250ms * var(--motion-scale,1)) var(--ease-overshoot) both}
+`;
+
+const TOKEN_SPLIT = /(\s+|\[\d+\])/;
+const CITATION_MARKER = /^\[(\d+)\]$/;
+const HAS_WORD_CHARACTER = /[\p{L}\p{N}]/u;
+const WHITESPACE = /^\s+$/;
+
+function tokenize(text: string): string[] {
+  return text.split(TOKEN_SPLIT).filter((token) => token !== "");
+}
+
+export function ResponseText({
+  className,
+  text,
+  citations,
+  animateInitial = false,
+  ...props
+}: ResponseTextProps) {
+  const tokens = tokenize(text);
+  // Everything below this index was on screen at first render.
+  const [baseline] = useState(() => (animateInitial ? 0 : tokens.length));
+
+  const rendered: ReactNode[] = tokens.map((token, position) => {
+    const arrived = position >= baseline;
+
+    if (WHITESPACE.test(token)) return token;
+
+    const marker = CITATION_MARKER.exec(token);
+    if (marker) {
+      const index = Number(marker[1]);
+      const citation = citations?.find((candidate) => candidate.index === index);
+      if (!citation) return token;
+      return (
+        <span
+          key={position}
+          data-slot="response-citation"
+          className={arrived ? `${PREFIX}-pop` : undefined}
+        >
+          <InlineCitation index={index} title={citation.title} href={citation.href} />
+        </span>
+      );
+    }
+
+    if (!HAS_WORD_CHARACTER.test(token)) return token;
+
+    return (
+      <span
+        key={position}
+        data-slot="response-word"
+        className={arrived ? `${PREFIX}-word` : undefined}
+      >
+        {token}
+      </span>
+    );
+  });
+
+  return (
+    <span data-slot="response-text" className={cn(className)} {...props}>
+      <style href={PREFIX} precedence="dowel">
+        {STYLES}
+      </style>
+      {rendered}
+    </span>
+  );
+}