@dowel-ui/react 0.1.1 → 0.3.0

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

@@ -0,0 +1,368 @@
+"use client";
+
+import { useId, useMemo, useState, type ComponentPropsWithRef, type ReactNode } from "react";
+
+import { disabledStyles, focusRing } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+/**
+ * The gate between an agent deciding to act and it acting.
+ *
+ * Two things separate this from the confirmations that already exist.
+ *
+ * The first is that the proposed arguments are editable. Every implementation
+ * surveyed returns a boolean over a read-only payload, which forces a false
+ * choice: approve a call whose recipient is wrong, or deny it and make the
+ * model try again. "Approve this, but fix the address first" is the answer
+ * people actually want, and it is only possible if the arguments are fields.
+ * Edited values come back in the decision, and are marked as changed so an
+ * audit trail can tell the model's proposal from the human's correction.
+ *
+ * The second is that it renders while the arguments are still arriving. The
+ * common implementation returns null until the tool input is complete, which
+ * means nothing is on screen at the moment approval becomes relevant and the
+ * request appears abruptly, fully formed. Here the request is visible as it
+ * forms, with the decision held until there is something whole to decide on.
+ */
+
+export type ApprovalScope = "once" | "always";
+
+export type ApprovalDecision =
+  | {
+      approved: true;
+      scope: ApprovalScope;
+      arguments: Record<string, string>;
+      edited: string[];
+    }
+  | { approved: false; reason?: string };
+
+export interface ApprovalField {
+  name: string;
+  label: string;
+  /** A textarea instead of a single line. For message bodies and prompts. */
+  multiline?: boolean;
+  /** Locked arguments are shown but not editable — an id, a resolved amount. */
+  readOnly?: boolean;
+}
+
+export interface ApprovalRequestProps extends Omit<
+  ComponentPropsWithRef<"section">,
+  "onSubmit" | "children"
+> {
+  /** The tool the model wants to call, as it named it. */
+  tool: string;
+  /** What the call will do, in the reader's language rather than the API's. */
+  summary: string;
+  /** Proposed arguments. Missing keys are treated as still arriving. */
+  arguments: Record<string, string>;
+  /** Which arguments to show, in order, and which may be changed. */
+  fields: ApprovalField[];
+  onDecision: (decision: ApprovalDecision) => void;
+  /**
+   * True while the model is still producing the arguments. The request renders
+   * anyway; only the decision waits.
+   */
+  streaming?: boolean;
+  /**
+   * Said plainly above the controls when the call cannot be taken back. Not a
+   * severity colour — the sentence is the warning.
+   */
+  irreversible?: string;
+  /** Set once decided, to render the outcome instead of the controls. */
+  decision?: ApprovalDecision;
+  children?: ReactNode;
+}
+
+export function ApprovalRequest({
+  className,
+  tool,
+  summary,
+  arguments: proposed,
+  fields,
+  onDecision,
+  streaming = false,
+  irreversible,
+  decision,
+  children,
+  ...props
+}: ApprovalRequestProps) {
+  const headingId = useId();
+  const [edits, setEdits] = useState<Record<string, string>>({});
+  const [denying, setDenying] = useState(false);
+  const [reason, setReason] = useState("");
+
+  // 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]);
+
+  const edited = useMemo(
+    () => Object.keys(edits).filter((name) => edits[name] !== proposed[name]),
+    [edits, proposed],
+  );
+
+  const missing = fields.filter((field) => proposed[field.name] === undefined);
+  const settled = !streaming && missing.length === 0;
+
+  if (decision) {
+    return (
+      <section
+        data-slot="approval-request"
+        data-state={decision.approved ? "approved" : "denied"}
+        aria-labelledby={headingId}
+        className={cn(
+          "rounded-lg border p-4 text-sm",
+          decision.approved ? "border-border bg-muted/40" : "border-border bg-muted/40",
+          className,
+        )}
+        {...props}
+      >
+        <h3 id={headingId} className="text-sm font-medium">
+          {summary}
+        </h3>
+        <p data-slot="approval-outcome" className="mt-1 text-xs text-muted-foreground">
+          {decision.approved
+            ? `Approved ${decision.scope === "always" ? "for every call to this tool" : "once"}` +
+              (decision.edited.length > 0
+                ? `, with ${String(decision.edited.length)} argument${decision.edited.length === 1 ? "" : "s"} corrected`
+                : "")
+            : `Denied${decision.reason ? `: ${decision.reason}` : ""}`}
+        </p>
+      </section>
+    );
+  }
+
+  return (
+    <section
+      data-slot="approval-request"
+      data-state={settled ? "pending" : "forming"}
+      aria-labelledby={headingId}
+      // Busy while the arguments are still arriving, so a reader is told the
+      // request is not yet whole rather than acting on half of it.
+      aria-busy={!settled}
+      className={cn("rounded-lg border border-border bg-card p-4", className)}
+      {...props}
+    >
+      <div className="flex flex-wrap items-baseline justify-between gap-2">
+        <h3 id={headingId} className="text-sm font-medium">
+          {summary}
+        </h3>
+        <code className="rounded bg-muted px-1.5 py-0.5 font-mono text-2xs text-muted-foreground">
+          {tool}
+        </code>
+      </div>
+
+      <dl className="mt-3 flex flex-col gap-2.5">
+        {fields.map((field) => {
+          const arrived = proposed[field.name] !== undefined;
+          const changed = edited.includes(field.name);
+
+          return (
+            <ApprovalArgument
+              key={field.name}
+              field={field}
+              value={values[field.name] ?? ""}
+              arrived={arrived}
+              changed={changed}
+              onChange={(next) => {
+                setEdits((current) => ({ ...current, [field.name]: next }));
+              }}
+            />
+          );
+        })}
+      </dl>
+
+      {children}
+
+      {irreversible ? (
+        <p data-slot="approval-warning" className="mt-3 text-xs text-destructive">
+          {irreversible}
+        </p>
+      ) : null}
+
+      {denying ? (
+        <div 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
+            id={`${headingId}-reason`}
+            rows={2}
+            value={reason}
+            onChange={(event) => {
+              setReason(event.target.value);
+            }}
+            className={cn(
+              "w-full resize-none rounded-md border border-input bg-background px-2 py-1.5 text-sm",
+              focusRing,
+            )}
+          />
+          <div className="flex flex-wrap gap-2">
+            <Action
+              variant="destructive"
+              onClick={() => {
+                onDecision({ approved: false, reason: reason.trim() || undefined });
+              }}
+            >
+              Deny
+            </Action>
+            <Action
+              onClick={() => {
+                setDenying(false);
+              }}
+            >
+              Back
+            </Action>
+          </div>
+        </div>
+      ) : (
+        <div className="mt-4 flex flex-wrap items-center gap-2">
+          <Action
+            variant="primary"
+            disabled={!settled}
+            onClick={() => {
+              onDecision({ approved: true, scope: "once", arguments: values, edited });
+            }}
+          >
+            {edited.length > 0 ? "Approve with changes" : "Approve once"}
+          </Action>
+
+          {/* Scope is a separate decision from approval, and blanket consent
+              should never be the easiest button to reach. */}
+          <Action
+            disabled={!settled}
+            onClick={() => {
+              onDecision({ approved: true, scope: "always", arguments: values, edited });
+            }}
+          >
+            Always allow {tool}
+          </Action>
+
+          <Action
+            onClick={() => {
+              setDenying(true);
+            }}
+          >
+            Deny…
+          </Action>
+
+          {!settled ? (
+            <span aria-live="polite" className="text-xs text-muted-foreground">
+              Waiting for the model to finish the request
+            </span>
+          ) : null}
+        </div>
+      )}
+    </section>
+  );
+}
+
+function ApprovalArgument({
+  field,
+  value,
+  arrived,
+  changed,
+  onChange,
+}: {
+  field: ApprovalField;
+  value: string;
+  arrived: boolean;
+  changed: boolean;
+  onChange: (value: string) => void;
+}) {
+  const id = useId();
+  const changedId = useId();
+  const editable = !field.readOnly && arrived;
+
+  return (
+    <div
+      data-slot="approval-argument"
+      data-changed={changed || undefined}
+      className="flex flex-col gap-1"
+    >
+      <dt className="flex items-baseline gap-1">
+        <label htmlFor={editable ? id : undefined} className="text-xs text-muted-foreground">
+          {field.label}
+        </label>
+        {/* Outside the label, and attached as a description instead. Inside it,
+            editing a field would rename the field — a screen reader user would
+            hear its accessible name change under them mid-edit. Marked in text
+            rather than by border colour alone, because an audit trail has to
+            tell the model's proposal from the human's correction. */}
+        {changed ? (
+          <span id={changedId} className="text-xs text-warning">
+            · changed from the model&rsquo;s proposal
+          </span>
+        ) : null}
+      </dt>
+      <dd className="m-0">
+        {!arrived ? (
+          <span
+            aria-hidden="true"
+            className="block h-8 w-full animate-pulse-soft rounded-md bg-muted"
+          />
+        ) : editable ? (
+          field.multiline ? (
+            <textarea
+              id={id}
+              aria-describedby={changed ? changedId : undefined}
+              rows={3}
+              value={value}
+              onChange={(event) => {
+                onChange(event.target.value);
+              }}
+              className={cn(
+                "w-full resize-none rounded-md border border-input bg-background px-2 py-1.5 font-mono text-xs",
+                changed && "border-warning",
+                focusRing,
+              )}
+            />
+          ) : (
+            <input
+              id={id}
+              type="text"
+              aria-describedby={changed ? changedId : undefined}
+              value={value}
+              onChange={(event) => {
+                onChange(event.target.value);
+              }}
+              className={cn(
+                "w-full rounded-md border border-input bg-background px-2 py-1.5 font-mono text-xs",
+                changed && "border-warning",
+                focusRing,
+              )}
+            />
+          )
+        ) : (
+          <p className="rounded-md bg-muted px-2 py-1.5 font-mono text-xs break-words">
+            {value}
+          </p>
+        )}
+      </dd>
+    </div>
+  );
+}
+
+function Action({
+  className,
+  variant = "default",
+  ...props
+}: ComponentPropsWithRef<"button"> & { variant?: "default" | "primary" | "destructive" }) {
+  return (
+    <button
+      type="button"
+      className={cn(
+        "rounded-md border px-2.5 py-1 text-xs font-medium transition-colors",
+        variant === "primary" &&
+          "border-primary bg-primary text-primary-foreground hover:bg-primary-hover",
+        variant === "destructive" &&
+          "border-destructive bg-destructive text-destructive-foreground hover:bg-destructive/90",
+        variant === "default" &&
+          "border-input bg-background hover:bg-accent hover:text-accent-foreground",
+        focusRing,
+        disabledStyles,
+        className,
+      )}
+      {...props}
+    />
+  );
+}

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

@@ -0,0 +1,7 @@
+export {
+  ApprovalRequest,
+  type ApprovalDecision,
+  type ApprovalField,
+  type ApprovalRequestProps,
+  type ApprovalScope,
+} from "./ai-approval-request";

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

@@ -0,0 +1,21 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "ai-approval-request",
+  title: "AI Approval Request",
+  description: "Approve a tool call — after correcting the arguments the model got wrong.",
+  category: "ai",
+  status: "stable",
+  dependencies: [],
+  registryDependencies: [],
+  files: ["ai-approval-request.tsx"],
+  a11y:
+    "The proposed arguments are a description list of real labelled form controls, so each value " +
+    "is associated with its name and editable ones are reachable by keyboard. A corrected " +
+    "argument is marked in text rather than by border colour alone, because an audit trail has " +
+    "to distinguish the model's proposal from the human's edit. The request is aria-busy while " +
+    "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.",
+});

package/src/components/ai-inline-completion/ai-inline-completion.tsx

@@ -0,0 +1,214 @@
+"use client";
+
+import {
+  useId,
+  useRef,
+  useState,
+  type ChangeEvent,
+  type ComponentPropsWithRef,
+  type CompositionEvent,
+  type KeyboardEvent,
+  type UIEvent,
+} from "react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * Ghost-text suggestion inside a real textarea or input.
+ *
+ * Outside chat this is the most-copied AI affordance in software — Smart
+ * Compose, Copilot's grey continuation, Notion and Linear's inline suggestions —
+ * and every team rebuilds the same overlay-mirror trick from the same handful of
+ * blog posts.
+ *
+ * Two deliberate limits, both stated rather than discovered:
+ *
+ * 1. It works on `textarea` and `input`, not on contenteditable. Ghost text in
+ *    contenteditable means owning selection, undo and inline formatting, which
+ *    is an editor, not a component. Anyone in that territory already has
+ *    ProseMirror or Lexical and should extend it there.
+ * 2. The suggestion completes the END of the value. Mid-caret insertion needs
+ *    per-character measurement of wrapped text; the ghost hides whenever the
+ *    caret is not at the end rather than rendering in the wrong place.
+ *
+ * There is no WAI-ARIA pattern for generative ghost text. Combobox is the
+ * nearest and does not fit: the suggestion is not one of a known set of options,
+ * so a listbox would be a lie. What the standard does require is that the
+ * suggestion be perceivable and that the keyboard is never trapped — so the text
+ * is announced through a live description, and Escape always restores plain Tab.
+ */
+
+export interface InlineCompletionProps extends Omit<
+  ComponentPropsWithRef<"textarea">,
+  "value" | "onChange" | "children"
+> {
+  value: string;
+  onValueChange: (value: string) => void;
+  /**
+   * The continuation to show after the value. Empty or undefined shows nothing.
+   * The caller supplies this; the component never requests it.
+   */
+  suggestion?: string;
+  /** Called with the full text after the suggestion is taken. */
+  onAccept?: (value: string) => void;
+  /** Called when the reader rejects the suggestion outright. */
+  onDismiss?: () => void;
+  /** Renders a single-line input instead of a textarea. */
+  singleLine?: boolean;
+}
+
+/** The next word of a suggestion, including its leading space. */
+function nextWord(suggestion: string): string {
+  const match = /^\s*\S+/.exec(suggestion);
+  return match ? match[0] : suggestion;
+}
+
+export function InlineCompletion({
+  className,
+  value,
+  onValueChange,
+  suggestion = "",
+  onAccept,
+  onDismiss,
+  singleLine = false,
+  onKeyDown,
+  onScroll,
+  ...props
+}: InlineCompletionProps) {
+  const fieldRef = useRef<HTMLTextAreaElement | null>(null);
+  const mirrorRef = useRef<HTMLDivElement | null>(null);
+  const describedById = useId();
+
+  const [dismissed, setDismissed] = useState(false);
+  const [composing, setComposing] = useState(false);
+  const [caretAtEnd, setCaretAtEnd] = useState(true);
+
+  // A suggestion is only shown when it can be shown honestly: not mid-word of
+  // an IME composition, not after the reader has rejected it, and not when the
+  // caret sits somewhere the ghost would render in the wrong place.
+  const visible = suggestion.length > 0 && !dismissed && !composing && caretAtEnd;
+
+  function syncCaret() {
+    const field = fieldRef.current;
+    if (!field) return;
+    setCaretAtEnd(field.selectionStart === value.length && field.selectionEnd === value.length);
+  }
+
+  function accept(text: string) {
+    const next = value + text;
+    onValueChange(next);
+    onAccept?.(next);
+    setDismissed(false);
+  }
+
+  function handleKeyDown(event: KeyboardEvent<HTMLTextAreaElement>) {
+    onKeyDown?.(event);
+    if (event.defaultPrevented) return;
+
+    if (!visible) return;
+
+    // Word-at-a-time, before the plain Tab case so the modifier wins.
+    if (event.key === "ArrowRight" && (event.metaKey || event.altKey || event.ctrlKey)) {
+      event.preventDefault();
+      accept(nextWord(suggestion));
+      return;
+    }
+
+    if (event.key === "Tab") {
+      event.preventDefault();
+      accept(suggestion);
+      return;
+    }
+
+    if (event.key === "Escape") {
+      // The escape hatch. Without it, a keyboard user facing a suggestion has
+      // no way to leave the field: Tab would accept instead of moving focus.
+      event.preventDefault();
+      setDismissed(true);
+      onDismiss?.();
+    }
+  }
+
+  function handleChange(event: ChangeEvent<HTMLTextAreaElement>) {
+    // Any edit invalidates the previous rejection: the reader has moved on and
+    // the next suggestion is a different one.
+    setDismissed(false);
+    onValueChange(event.target.value);
+    queueMicrotask(syncCaret);
+  }
+
+  function handleScroll(event: UIEvent<HTMLTextAreaElement>) {
+    onScroll?.(event);
+    // The mirror has to follow the field, or the ghost detaches from the text
+    // as soon as the content is taller than the box.
+    if (mirrorRef.current) {
+      mirrorRef.current.scrollTop = event.currentTarget.scrollTop;
+      mirrorRef.current.scrollLeft = event.currentTarget.scrollLeft;
+    }
+  }
+
+  function handleComposition(event: CompositionEvent<HTMLTextAreaElement>) {
+    setComposing(event.type === "compositionstart");
+  }
+
+  // Typography must match exactly between field and mirror or the ghost lands
+  // in the wrong place. Both take the same class string for that reason.
+  const shared = cn(
+    "w-full rounded-md border border-input px-3 py-2 text-sm",
+    singleLine ? "overflow-x-auto whitespace-pre" : "break-words whitespace-pre-wrap",
+  );
+
+  return (
+    <div data-slot="inline-completion" className={cn("relative", className)}>
+      {/* The mirror sits behind the field and holds the value in transparent
+          text purely to push the ghost to the caret position. */}
+      <div
+        ref={mirrorRef}
+        aria-hidden="true"
+        data-slot="inline-completion-ghost"
+        className={cn(
+          shared,
+          "pointer-events-none absolute inset-0 overflow-hidden border-transparent text-transparent select-none",
+        )}
+      >
+        {value}
+        {visible ? (
+          <span data-slot="inline-completion-suggestion" className="text-muted-foreground">
+            {suggestion}
+          </span>
+        ) : null}
+      </div>
+
+      <textarea
+        ref={fieldRef}
+        data-slot="inline-completion-field"
+        data-suggesting={visible || undefined}
+        rows={singleLine ? 1 : props.rows}
+        value={value}
+        onChange={handleChange}
+        onKeyDown={handleKeyDown}
+        onScroll={handleScroll}
+        onSelect={syncCaret}
+        onClick={syncCaret}
+        onCompositionStart={handleComposition}
+        onCompositionEnd={handleComposition}
+        aria-describedby={visible ? describedById : undefined}
+        className={cn(
+          shared,
+          "relative resize-none bg-transparent",
+          "placeholder:text-muted-foreground",
+          "outline-none focus-visible:ring-2 focus-visible:ring-ring/55",
+          singleLine && "resize-none",
+        )}
+        {...props}
+      />
+
+      {/* The suggestion as text, for anyone who cannot see grey glyphs behind a
+          field. Polite, so it does not interrupt typing, and it states the keys
+          because a gesture nobody knows about is not an affordance. */}
+      <span id={describedById} aria-live="polite" className="sr-only">
+        {visible ? `Suggestion: ${suggestion}. Press Tab to accept, Escape to dismiss.` : ""}
+      </span>
+    </div>
+  );
+}

package/src/components/ai-inline-completion/index.ts

@@ -0,0 +1 @@
+export { InlineCompletion, type InlineCompletionProps } from "./ai-inline-completion";

package/src/components/ai-inline-completion/meta.ts

@@ -0,0 +1,20 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "ai-inline-completion",
+  title: "AI Inline Completion",
+  description: "Ghost-text suggestion inside a real textarea, accepted with Tab.",
+  category: "ai",
+  status: "beta",
+  dependencies: [],
+  registryDependencies: [],
+  files: ["ai-inline-completion.tsx"],
+  a11y:
+    "No WAI-ARIA pattern covers generative ghost text — combobox is the nearest and does not fit, " +
+    "because the suggestion is not one of a known set of options and a listbox would misdescribe " +
+    "it. So the suggestion is announced through a polite live description that names the keys, " +
+    "since a gesture nobody knows about is not an affordance, and the grey text itself is " +
+    "aria-hidden. Escape always dismisses and restores plain Tab, so the keyboard is never " +
+    "trapped in the field. The ghost hides during IME composition and whenever the caret is not " +
+    "at the end, rather than rendering somewhere it does not belong.",
+});

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

@@ -50,6 +50,7 @@ export function ResponseCaret({ className, ...props }: ComponentPropsWithRef<"sp
     <span
       data-slot="response-caret"
       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",
         className,