@dowel-ui/react 0.7.0 → 0.8.0

package/src/components/ai-approval-request/ai-approval-request.tsx

@@ -1,6 +1,15 @@
 "use client";
 
-import { useId, useMemo, useState, type ComponentPropsWithRef, type ReactNode } from "react";
+// Motion from SmoothUI AI Approval (MIT, © 2024 Eduardo Calvo). See THIRD_PARTY_NOTICES.md.
+import {
+  useId,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentPropsWithRef,
+  type ReactNode,
+} from "react";
 
 import { disabledStyles, focusRing } from "@/lib/styles";
 import { cn } from "@/lib/utils";
@@ -71,8 +80,28 @@ export interface ApprovalRequestProps extends Omit<
   /** Set once decided, to render the outcome instead of the controls. */
   decision?: ApprovalDecision;
   children?: ReactNode;
+  /**
+   * Keep focus in the request as its controls swap: onto the outcome when a
+   * decision lands, into the reason field when Deny… opens, and back to Deny…
+   * from Back. Only acts when focus was already inside the request, so a
+   * decision applied elsewhere (another tab, a replay) never steals focus.
+   */
+  manageFocus?: boolean;
 }
 
+const PREFIX = "dowel-ai-approval-request";
+
+/* The outcome resolves in when a decision lands live (a replayed one does not
+ * animate), and the deny panel rises in. */
+const STYLES = `
+@keyframes ${PREFIX}-resolve{from{opacity:0;scale:.97}}
+@keyframes ${PREFIX}-reveal{from{opacity:0;translate:0 4px}}
+[data-slot=approval-request][data-resolved=live] [data-slot=approval-outcome]{animation:${PREFIX}-resolve calc(250ms * var(--motion-scale,1)) var(--ease-out-quint) both}
+[data-slot=approval-deny]{animation:${PREFIX}-reveal calc(200ms * var(--motion-scale,1)) var(--ease-out-quint) both}
+`;
+
+type FocusTarget = "outcome" | "reason" | "deny";
+
 export function ApprovalRequest({
   className,
   tool,
@@ -84,6 +113,8 @@ export function ApprovalRequest({
   irreversible,
   decision,
   children,
+  manageFocus = true,
+  ref,
   ...props
 }: ApprovalRequestProps) {
   const headingId = useId();
@@ -91,6 +122,54 @@ export function ApprovalRequest({
   const [denying, setDenying] = useState(false);
   const [reason, setReason] = useState("");
 
+  // A decision present on first render is a replay: it neither animates nor
+  // takes focus.
+  const [initiallyDecided] = useState(decision !== undefined);
+  const sectionRef = useRef<HTMLElement | null>(null);
+  const outcomeRef = useRef<HTMLParagraphElement | null>(null);
+  const reasonRef = useRef<HTMLTextAreaElement | null>(null);
+  const denyRef = useRef<HTMLButtonElement | null>(null);
+  // Where focus should go after the next swap. Set only by the reader's own
+  // actions, and only while focus is inside the request.
+  const focusTarget = useRef<FocusTarget | null>(null);
+
+  function queueFocus(target: FocusTarget) {
+    if (!manageFocus) return;
+    const inside = sectionRef.current?.contains(document.activeElement) ?? false;
+    focusTarget.current = inside ? target : null;
+  }
+
+  const decided = decision !== undefined;
+  useLayoutEffect(() => {
+    const target = focusTarget.current;
+    if (!target) return;
+    const element =
+      target === "outcome"
+        ? outcomeRef.current
+        : target === "reason"
+          ? reasonRef.current
+          : denyRef.current;
+    if (!element) return;
+    focusTarget.current = null;
+    // If the reader moved on while an async decision was pending, leave them be.
+    const active = document.activeElement;
+    const stillHere =
+      !active || active === document.body || (sectionRef.current?.contains(active) ?? false);
+    if (stillHere) element.focus();
+  }, [decided, denying]);
+
+  const setSectionRef = (node: HTMLElement | null) => {
+    sectionRef.current = node;
+    if (typeof ref === "function") return ref(node);
+    if (ref) ref.current = node;
+  };
+
+  const sheet = (
+    <style href={PREFIX} precedence="dowel">
+      {STYLES}
+    </style>
+  );
+
   // The model's proposal with the human's corrections applied on top. Keeping
   // them apart is what lets the component say which is which.
   const values = useMemo(() => ({ ...proposed, ...edits }), [proposed, edits]);
@@ -106,8 +185,10 @@ export function ApprovalRequest({
   if (decision) {
     return (
       <section
+        ref={setSectionRef}
         data-slot="approval-request"
         data-state={decision.approved ? "approved" : "denied"}
+        data-resolved={initiallyDecided ? undefined : "live"}
         aria-labelledby={headingId}
         className={cn(
           "rounded-lg border p-4 text-sm",
@@ -116,10 +197,18 @@ export function ApprovalRequest({
         )}
         {...props}
       >
+        {sheet}
         <h3 id={headingId} className="text-sm font-medium">
           {summary}
         </h3>
-        <p data-slot="approval-outcome" className="mt-1 text-xs text-muted-foreground">
+        {/* tabIndex -1: a focus target for the person who just decided, so
+            they hear the outcome, but never a Tab stop. */}
+        <p
+          ref={outcomeRef}
+          tabIndex={-1}
+          data-slot="approval-outcome"
+          className="mt-1 text-xs text-muted-foreground outline-none"
+        >
           {decision.approved
             ? `Approved ${decision.scope === "always" ? "for every call to this tool" : "once"}` +
               (decision.edited.length > 0
@@ -133,6 +222,7 @@ export function ApprovalRequest({
 
   return (
     <section
+      ref={setSectionRef}
       data-slot="approval-request"
       data-state={settled ? "pending" : "forming"}
       aria-labelledby={headingId}
@@ -142,6 +232,7 @@ export function ApprovalRequest({
       className={cn("rounded-lg border border-border bg-card p-4", className)}
       {...props}
     >
+      {sheet}
       <div className="flex flex-wrap items-baseline justify-between gap-2">
         <h3 id={headingId} className="text-sm font-medium">
           {summary}
@@ -180,11 +271,12 @@ export function ApprovalRequest({
       ) : null}
 
       {denying ? (
-        <div className="mt-3 flex flex-col gap-2">
+        <div data-slot="approval-deny" className="mt-3 flex flex-col gap-2">
           <label htmlFor={`${headingId}-reason`} className="text-xs text-muted-foreground">
             Why not? The model sees this.
           </label>
           <textarea
+            ref={reasonRef}
             id={`${headingId}-reason`}
             rows={2}
             value={reason}
@@ -200,6 +292,7 @@ export function ApprovalRequest({
             <Action
               variant="destructive"
               onClick={() => {
+                queueFocus("outcome");
                 onDecision({ approved: false, reason: reason.trim() || undefined });
               }}
             >
@@ -207,6 +300,7 @@ export function ApprovalRequest({
             </Action>
             <Action
               onClick={() => {
+                queueFocus("deny");
                 setDenying(false);
               }}
             >
@@ -220,6 +314,7 @@ export function ApprovalRequest({
             variant="primary"
             disabled={!settled}
             onClick={() => {
+              queueFocus("outcome");
               onDecision({ approved: true, scope: "once", arguments: values, edited });
             }}
           >
@@ -231,6 +326,7 @@ export function ApprovalRequest({
           <Action
             disabled={!settled}
             onClick={() => {
+              queueFocus("outcome");
               onDecision({ approved: true, scope: "always", arguments: values, edited });
             }}
           >
@@ -238,7 +334,9 @@ export function ApprovalRequest({
           </Action>
 
           <Action
+            ref={denyRef}
             onClick={() => {
+              queueFocus("reason");
               setDenying(true);
             }}
           >
@@ -351,7 +449,8 @@ function Action({
     <button
       type="button"
       className={cn(
-        "rounded-md border px-2.5 py-1 text-xs font-medium transition-colors",
+        "rounded-md border px-2.5 py-1 text-xs font-medium",
+        "transition-[color,background-color,border-color,scale] duration-[var(--duration-fast)] ease-[var(--ease-out-quint)] active:scale-[0.99]",
         variant === "primary" &&
           "border-primary bg-primary text-primary-foreground hover:bg-primary-hover",
         variant === "destructive" &&

package/src/components/ai-approval-request/meta.ts

@@ -17,5 +17,8 @@ export const meta = defineMeta({
     "arguments are still arriving and the decision controls stay disabled until it is whole — " +
     "rendering nothing until then, as the common implementation does, means nothing is on screen " +
     "at the moment approval becomes relevant. Irreversibility is stated as a sentence, never as a " +
-    "severity colour.",
+    "severity colour. Focus never falls to the page as controls swap: deciding moves it to the " +
+    "outcome (tabindex -1, never a Tab stop), Deny… moves it into the reason field and Back " +
+    "returns it — but only when focus was already inside, so a replayed or remote decision " +
+    "never steals it (manageFocus={false} opts out).",
 });

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

@@ -0,0 +1,203 @@
+"use client";
+
+// Ported from SmoothUI AI Artifact (MIT, © 2024 Eduardo Calvo). See THIRD_PARTY_NOTICES.md.
+import { useId, useState, type ComponentPropsWithRef, type ReactNode } from "react";
+
+import { CopyButton } from "@/components/copy-button";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/tabs";
+import { focusRingInset } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+/*
+ * A frame around something the model produced: a title, a rendered preview,
+ * the raw source, and a copy action.
+ *
+ * The two panes live on one horizontal axis — preview before code, always —
+ * so switching has a direction: code arrives from the inline end, preview from
+ * the inline start, and after one go the user knows where the other pane went.
+ * A cross-fade would leave no such memory. The slide is a CSS keyframe that
+ * only runs after the first switch (not on mount), mirrors in right-to-left
+ * layouts, and stops under reduced motion.
+ *
+ * SmoothUI slides a shared indicator between the tabs with Motion's layoutId;
+ * that belongs to Tabs itself, so this composes Dowel's Tabs as they are.
+ */
+
+const PREFIX = "dowel-ai-artifact";
+const STYLES = `
+.${PREFIX}{--artifact-dir:1}
+.${PREFIX}:dir(rtl){--artifact-dir:-1}
+.${PREFIX}[data-switched] [data-slot=artifact-pane][data-state=active]{animation:${PREFIX}-in var(--duration-normal) var(--ease-out-quint)}
+@keyframes ${PREFIX}-in{from{opacity:0;transform:translateX(calc(var(--artifact-from) * var(--artifact-dir)))}}
+`;
+
+export type ArtifactPane = "preview" | "code";
+
+export interface ArtifactProps extends Omit<ComponentPropsWithRef<"div">, "title"> {
+  /** Names the artifact so it can be referred to in conversation. */
+  title: ReactNode;
+  /** The rendered form. */
+  preview?: ReactNode;
+  /** The raw form — source, JSON, markup. Pre-highlighted markup is fine. */
+  code?: ReactNode;
+  /** Plain text for the clipboard. Omit to hide the copy action. */
+  copyValue?: string;
+  /** Controlled pane. */
+  pane?: ArtifactPane;
+  /** Initial pane when uncontrolled. */
+  defaultPane?: ArtifactPane;
+  onPaneChange?: (pane: ArtifactPane) => void;
+  /** Extra toolbar actions, after the pane switch. */
+  actions?: ReactNode;
+  /** Tab labels. */
+  labels?: Partial<Record<ArtifactPane, string>>;
+}
+
+const paneClass = "mt-0 rounded-b-xl";
+
+/** A titled frame for generated output, with preview and code panes. */
+export function Artifact({
+  className,
+  title,
+  preview,
+  code,
+  copyValue,
+  pane: paneProp,
+  defaultPane = "preview",
+  onPaneChange,
+  actions,
+  labels,
+  ...props
+}: ArtifactProps) {
+  const titleId = useId();
+  const [uncontrolled, setUncontrolled] = useState<ArtifactPane>(defaultPane);
+  const [switched, setSwitched] = useState(false);
+  const available: ArtifactPane[] = [];
+  if (preview != null) available.push("preview");
+  if (code != null) available.push("code");
+  const requested = paneProp ?? uncontrolled;
+  const pane = available.includes(requested) ? requested : (available[0] ?? "preview");
+  const tabbed = available.length > 1;
+  const names = { preview: "Preview", code: "Code", ...labels };
+
+  function change(next: string) {
+    const value = next as ArtifactPane;
+    setSwitched(true);
+    if (paneProp === undefined) setUncontrolled(value);
+    onPaneChange?.(value);
+  }
+
+  const codeBlock = (
+    <pre className="overflow-x-auto p-3 font-mono text-xs leading-relaxed text-foreground">
+      {code}
+    </pre>
+  );
+  const previewBlock = <div className="p-3">{preview}</div>;
+
+  const toolbar = (
+    <div
+      data-slot="artifact-header"
+      className="flex items-center gap-2 border-b border-border px-2 py-1.5"
+    >
+      <span id={titleId} className="min-w-0 truncate px-1 text-xs font-medium text-foreground">
+        {title}
+      </span>
+      <div className="ms-auto flex items-center gap-1">
+        {tabbed ? (
+          <TabsList className="h-auto gap-0.5 p-0.5">
+            {available.map((candidate) => (
+              <TabsTrigger key={candidate} value={candidate} className="h-6 px-2 text-xs">
+                {names[candidate]}
+              </TabsTrigger>
+            ))}
+          </TabsList>
+        ) : null}
+        {actions}
+        {copyValue !== undefined ? (
+          <CopyButton
+            value={copyValue}
+            variant="ghost"
+            size="icon-sm"
+            aria-label="Copy"
+            className="size-7 text-muted-foreground"
+          />
+        ) : null}
+      </div>
+    </div>
+  );
+
+  const root = cn(
+    PREFIX,
+    "w-full overflow-hidden rounded-xl border border-border bg-background",
+    className,
+  );
+
+  if (!tabbed) {
+    return (
+      <div
+        role="group"
+        aria-labelledby={titleId}
+        data-slot="artifact"
+        data-pane={pane}
+        className={root}
+        {...props}
+      >
+        <style href={PREFIX} precedence="dowel">
+          {STYLES}
+        </style>
+        {toolbar}
+        {pane === "code" ? (
+          // A scroll box must be reachable by keyboard, so it is a focusable,
+          // named region (ADR 0009).
+          <div
+            role="region"
+            aria-labelledby={titleId}
+            tabIndex={0}
+            className={cn("rounded-b-xl", focusRingInset)}
+          >
+            {codeBlock}
+          </div>
+        ) : (
+          previewBlock
+        )}
+      </div>
+    );
+  }
+
+  return (
+    <Tabs value={pane} onValueChange={change} asChild>
+      <div
+        role="group"
+        aria-labelledby={titleId}
+        data-slot="artifact"
+        data-pane={pane}
+        data-switched={switched ? "" : undefined}
+        className={root}
+        {...props}
+      >
+        <style href={PREFIX} precedence="dowel">
+          {STYLES}
+        </style>
+        {toolbar}
+        <div className="overflow-hidden">
+          <TabsContent
+            value="preview"
+            data-slot="artifact-pane"
+            className={paneClass}
+            style={{ ["--artifact-from" as string]: "-24px" }}
+          >
+            {previewBlock}
+          </TabsContent>
+          <TabsContent
+            value="code"
+            data-slot="artifact-pane"
+            className={paneClass}
+            style={{ ["--artifact-from" as string]: "24px" }}
+          >
+            {codeBlock}
+          </TabsContent>
+        </div>
+      </div>
+    </Tabs>
+  );
+}

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

@@ -0,0 +1 @@
+export { Artifact, type ArtifactPane, type ArtifactProps } from "./ai-artifact";

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

@@ -0,0 +1,18 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "ai-artifact",
+  title: "Artifact",
+  description:
+    "A titled frame for something the model produced, with preview and code panes that slide along one axis and a copy action.",
+  category: "ai",
+  status: "beta",
+  dependencies: [],
+  registryDependencies: ["copy-button", "tabs"],
+  files: ["ai-artifact.tsx"],
+  a11y:
+    "A group named by its title. With both panes it is a real tablist (arrow keys move between Preview and Code, " +
+    "each panel focusable and named by its tab); with one code pane, the scrolling source is a focusable region " +
+    "named by the title. Copying announces success and failure through Copy Button. The pane slide mirrors in " +
+    "right-to-left layouts, never plays on mount, and stops under reduced motion.",
+});

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

@@ -0,0 +1,222 @@
+"use client";
+
+// Ported from SmoothUI AI Branch (MIT, © 2024 Eduardo Calvo). See THIRD_PARTY_NOTICES.md.
+import { cva, type VariantProps } from "class-variance-authority";
+import {
+  Children,
+  createContext,
+  useCallback,
+  useContext,
+  useLayoutEffect,
+  useMemo,
+  useState,
+  type ComponentPropsWithRef,
+  type ReactNode,
+} from "react";
+
+import { Button, type ButtonProps } from "@/components/button";
+import { mirrorForDirection } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+/*
+ * Alternative versions of a turn — regenerated answers, edited prompts — with
+ * a pager to move between them.
+ *
+ * Every version stays mounted and the inactive ones are `hidden`, so switching
+ * keeps whatever state lives inside them. Revealing one restarts its CSS
+ * entrance (a fade and a 10px rise), because an element leaving display:none
+ * replays its animation; reduced motion stops it. The page indicator is a
+ * polite live region, so pressing Next says where it went.
+ */
+
+const PREFIX = "dowel-ai-branch";
+const STYLES = `
+[data-slot=branch-message][data-state=active]{animation:${PREFIX}-in var(--duration-slow) var(--ease-out-quint)}
+@keyframes ${PREFIX}-in{from{opacity:0;transform:translateY(10px)}}
+`;
+
+interface BranchContextValue {
+  current: number;
+  total: number;
+  setTotal: (total: number) => void;
+  go: (delta: number) => void;
+}
+
+const BranchContext = createContext<BranchContextValue | null>(null);
+
+function useBranch(part: string): BranchContextValue {
+  const context = useContext(BranchContext);
+  if (!context) throw new Error(`<${part}> must be used within <Branch>.`);
+  return context;
+}
+
+export interface BranchProps extends Omit<ComponentPropsWithRef<"div">, "defaultValue"> {
+  /** Controlled index of the visible version. */
+  value?: number;
+  /** Initial index when uncontrolled. */
+  defaultValue?: number;
+  onValueChange?: (index: number) => void;
+}
+
+/** The root: holds which version is showing. Paging wraps around. */
+export function Branch({
+  className,
+  value,
+  defaultValue = 0,
+  onValueChange,
+  ...props
+}: BranchProps) {
+  const [uncontrolled, setUncontrolled] = useState(defaultValue);
+  const [total, setTotal] = useState(0);
+  const raw = value ?? uncontrolled;
+  const current = total > 0 ? Math.min(Math.max(raw, 0), total - 1) : raw;
+
+  const go = useCallback(
+    (delta: number) => {
+      if (total < 2) return;
+      const next = (current + delta + total) % total;
+      if (value === undefined) setUncontrolled(next);
+      onValueChange?.(next);
+    },
+    [current, total, value, onValueChange],
+  );
+
+  const context = useMemo(() => ({ current, total, setTotal, go }), [current, total, go]);
+
+  return (
+    <BranchContext.Provider value={context}>
+      <style href={PREFIX} precedence="dowel">
+        {STYLES}
+      </style>
+      <div data-slot="branch" className={cn("grid w-full gap-2", className)} {...props} />
+    </BranchContext.Provider>
+  );
+}
+
+/** Each child is one version. Only the current one is shown. */
+export function BranchMessages({ children }: { children: ReactNode }) {
+  const { current, setTotal } = useBranch("BranchMessages");
+  const versions = Children.toArray(children);
+  const count = versions.length;
+
+  // Layout effect, so the pager knows the count before first paint.
+  useLayoutEffect(() => {
+    setTotal(count);
+  }, [count, setTotal]);
+
+  return versions.map((version, index) => (
+    <div
+      key={index}
+      data-slot="branch-message"
+      data-state={index === current ? "active" : "inactive"}
+      hidden={index !== current}
+      className="grid gap-2"
+    >
+      {version}
+    </div>
+  ));
+}
+
+const branchSelectorVariants = cva("flex items-center gap-1", {
+  variants: {
+    from: {
+      user: "justify-end self-end",
+      assistant: "justify-start self-start",
+    },
+  },
+  defaultVariants: {
+    from: "assistant",
+  },
+});
+
+export interface BranchSelectorProps
+  extends ComponentPropsWithRef<"div">, VariantProps<typeof branchSelectorVariants> {}
+
+/** The pager. Renders nothing while there is only one version. */
+export function BranchSelector({ className, from, ...props }: BranchSelectorProps) {
+  const { total } = useBranch("BranchSelector");
+  if (total <= 1) return null;
+  return (
+    <div
+      role="group"
+      aria-label="Versions"
+      data-slot="branch-selector"
+      className={cn(branchSelectorVariants({ from }), className)}
+      {...props}
+    />
+  );
+}
+
+function Chevron({ d }: { d: string }) {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      className={mirrorForDirection}
+    >
+      <path d={d} />
+    </svg>
+  );
+}
+
+type PagerButtonProps = Omit<ButtonProps, "asChild">;
+
+function PagerButton({
+  delta,
+  name,
+  path,
+  className,
+  children,
+  onClick,
+  ...props
+}: PagerButtonProps & { delta: number; name: string; path: string }) {
+  const { go, total } = useBranch(delta < 0 ? "BranchPrevious" : "BranchNext");
+  return (
+    <Button
+      type="button"
+      variant="ghost"
+      size="icon-sm"
+      aria-label={name}
+      disabled={total <= 1}
+      className={cn("size-7 rounded-full text-muted-foreground active:scale-95", className)}
+      onClick={(event) => {
+        onClick?.(event);
+        if (!event.defaultPrevented) go(delta);
+      }}
+      {...props}
+    >
+      {children ?? <Chevron d={path} />}
+    </Button>
+  );
+}
+
+export function BranchPrevious(props: PagerButtonProps) {
+  return <PagerButton delta={-1} name="Previous version" path="m15 18-6-6 6-6" {...props} />;
+}
+
+export function BranchNext(props: PagerButtonProps) {
+  return <PagerButton delta={1} name="Next version" path="m9 18 6-6-6-6" {...props} />;
+}
+
+/** "2 of 3", announced politely when it changes. */
+export function BranchPage({ className, ...props }: ComponentPropsWithRef<"span">) {
+  const { current, total } = useBranch("BranchPage");
+  return (
+    <span
+      data-slot="branch-page"
+      aria-live="polite"
+      aria-atomic="true"
+      className={cn("text-xs font-medium text-muted-foreground tabular-nums", className)}
+      {...props}
+    >
+      {current + 1} of {total}
+    </span>
+  );
+}
+
+export { branchSelectorVariants };

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

@@ -0,0 +1,11 @@
+export {
+  Branch,
+  BranchMessages,
+  BranchNext,
+  BranchPage,
+  BranchPrevious,
+  BranchSelector,
+  branchSelectorVariants,
+  type BranchProps,
+  type BranchSelectorProps,
+} from "./ai-branch";