@dowel-ui/react 0.1.0 → 0.2.0

package/src/components/ai-action-ledger/ai-action-ledger.tsx

@@ -0,0 +1,381 @@
+"use client";
+
+import { cva, type VariantProps } from "class-variance-authority";
+import { Collapsible as CollapsiblePrimitive } from "radix-ui";
+import {
+  createContext,
+  useContext,
+  useId,
+  useMemo,
+  useState,
+  type ComponentPropsWithRef,
+  type ReactNode,
+} from "react";
+
+import { focusRing } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+/**
+ * What an agent actually did, and what can be undone.
+ *
+ * Every AI component library stops at the conversation boundary: approve a tool
+ * call before it runs, then treat whatever it did to the database as the
+ * application's problem. But the thing that blocks agents from getting write
+ * access in real products is not "did I approve this", it is "it did the wrong
+ * thing, now what".
+ *
+ * The load-bearing idea is that undo is not uniform. Deleting a row can be
+ * reverted. A refund can be compensated by another transaction, which is not
+ * the same as never having happened. A sent email cannot be taken back at all.
+ * Presenting all three behind one "Undo" button is a lie the user only
+ * discovers after clicking, so reversibility is a required field and the
+ * affordance follows from it.
+ *
+ * This renders and selects. It performs nothing — `onRevert` receives the
+ * chosen actions and the application decides what that means.
+ */
+
+export type Reversibility = "revertible" | "compensable" | "irreversible";
+
+export type ActionStatus = "applied" | "reverting" | "reverted" | "failed";
+
+export interface LedgerAction {
+  id: string;
+  /** What was done, in the user's language: "Deleted 3 contacts". */
+  summary: string;
+  reversibility: Reversibility;
+  status: ActionStatus;
+  /** What the action touched, for grouping and scanning. */
+  target?: string;
+  timestamp?: string;
+  /** Why a revert failed. Shown only when status is "failed". */
+  error?: string;
+}
+
+const REVERSIBILITY_LABEL: Record<Reversibility, string> = {
+  revertible: "Can be undone",
+  compensable: "Can be offset, not undone",
+  irreversible: "Cannot be undone",
+};
+
+const STATUS_LABEL: Record<ActionStatus, string> = {
+  applied: "Applied",
+  reverting: "Reverting",
+  reverted: "Reverted",
+  failed: "Revert failed",
+};
+
+/** Only an applied action can be selected — the rest are already resolved. */
+function isSelectable(action: LedgerAction): boolean {
+  return action.status === "applied" && action.reversibility !== "irreversible";
+}
+
+const ledgerEntryVariants = cva("rounded-lg border text-sm transition-colors", {
+  variants: {
+    status: {
+      applied: "border-border bg-card",
+      reverting: "border-info/30 bg-info/5",
+      reverted: "border-border bg-muted/40",
+      failed: "border-destructive/40 bg-destructive/5",
+    },
+  },
+  defaultVariants: { status: "applied" },
+});
+
+interface LedgerContextValue {
+  actions: LedgerAction[];
+  selected: Set<string>;
+  toggle: (id: string) => void;
+  selectAll: () => void;
+  clear: () => void;
+  selectableIds: string[];
+  onRevert?: (actions: LedgerAction[]) => void;
+}
+
+const LedgerContext = createContext<LedgerContextValue | null>(null);
+
+function useLedgerContext(component: string): LedgerContextValue {
+  const context = useContext(LedgerContext);
+  if (!context) {
+    throw new Error(`${component} must be rendered inside <ActionLedger>.`);
+  }
+  return context;
+}
+
+export interface ActionLedgerProps extends Omit<ComponentPropsWithRef<"div">, "onSelect"> {
+  actions: LedgerAction[];
+  /** Receives the selected actions. The application performs the revert. */
+  onRevert?: (actions: LedgerAction[]) => void;
+  children?: ReactNode;
+}
+
+export function ActionLedger({
+  className,
+  actions,
+  onRevert,
+  children,
+  ...props
+}: ActionLedgerProps) {
+  const [selected, setSelected] = useState<Set<string>>(new Set());
+
+  const selectableIds = useMemo(
+    () => actions.filter(isSelectable).map((action) => action.id),
+    [actions],
+  );
+
+  const context = useMemo<LedgerContextValue>(
+    () => ({
+      actions,
+      selected,
+      selectableIds,
+      onRevert,
+      toggle: (id: string) => {
+        setSelected((current) => {
+          const next = new Set(current);
+          if (next.has(id)) next.delete(id);
+          else next.add(id);
+          return next;
+        });
+      },
+      selectAll: () => {
+        setSelected(new Set(selectableIds));
+      },
+      clear: () => {
+        setSelected(new Set());
+      },
+    }),
+    [actions, selected, selectableIds, onRevert],
+  );
+
+  return (
+    <LedgerContext.Provider value={context}>
+      <div
+        data-slot="action-ledger"
+        className={cn("flex flex-col gap-3", className)}
+        {...props}
+      >
+        {children}
+      </div>
+    </LedgerContext.Provider>
+  );
+}
+
+/**
+ * Selection controls and the revert action.
+ *
+ * The count is stated on the button rather than beside it, so the accessible
+ * name says what pressing it will do.
+ */
+export function ActionLedgerToolbar({ className, ...props }: ComponentPropsWithRef<"div">) {
+  const { selected, selectableIds, actions, selectAll, clear, onRevert } =
+    useLedgerContext("ActionLedgerToolbar");
+
+  const count = selected.size;
+  const allSelected = selectableIds.length > 0 && count === selectableIds.length;
+
+  return (
+    <div
+      data-slot="action-ledger-toolbar"
+      className={cn("flex flex-wrap items-center gap-2", className)}
+      {...props}
+    >
+      <button
+        type="button"
+        disabled={selectableIds.length === 0}
+        onClick={allSelected ? clear : selectAll}
+        className={cn(
+          "rounded-md border border-input bg-background px-2.5 py-1 text-xs font-medium",
+          "transition-colors hover:bg-accent hover:text-accent-foreground",
+          "disabled:pointer-events-none disabled:opacity-50",
+          focusRing,
+        )}
+      >
+        {allSelected
+          ? "Clear selection"
+          : `Select all ${String(selectableIds.length)} undoable`}
+      </button>
+
+      <button
+        type="button"
+        data-slot="action-ledger-revert"
+        disabled={count === 0}
+        onClick={() => {
+          onRevert?.(actions.filter((action) => selected.has(action.id)));
+        }}
+        className={cn(
+          "rounded-md bg-primary px-2.5 py-1 text-xs font-medium text-primary-foreground",
+          "transition-colors hover:bg-primary-hover",
+          "disabled:pointer-events-none disabled:opacity-50",
+          focusRing,
+        )}
+      >
+        {count === 0 ? "Undo selected" : `Undo ${String(count)} selected`}
+      </button>
+    </div>
+  );
+}
+
+export interface ActionLedgerEntryProps
+  extends
+    Omit<ComponentPropsWithRef<"li">, "children">,
+    VariantProps<typeof ledgerEntryVariants> {
+  action: LedgerAction;
+  /** The payload inspector. Collapsed, because it is provenance not content. */
+  children?: ReactNode;
+}
+
+export function ActionLedgerEntry({
+  className,
+  action,
+  children,
+  ...props
+}: ActionLedgerEntryProps) {
+  const { selected, toggle } = useLedgerContext("ActionLedgerEntry");
+  const checkboxId = useId();
+  const selectable = isSelectable(action);
+  const isSelected = selected.has(action.id);
+
+  return (
+    <li
+      data-slot="action-ledger-entry"
+      data-status={action.status}
+      data-reversibility={action.reversibility}
+      className={cn(ledgerEntryVariants({ status: action.status }), className)}
+      {...props}
+    >
+      <div className="flex items-start gap-3 p-3">
+        {/* A native checkbox: this is a list of things to act on, and the
+            selection has to survive without JavaScript-driven roles. */}
+        <input
+          type="checkbox"
+          id={checkboxId}
+          disabled={!selectable}
+          checked={isSelected}
+          onChange={() => {
+            toggle(action.id);
+          }}
+          className={cn(
+            "mt-0.5 size-4 shrink-0 rounded border-input",
+            "disabled:cursor-not-allowed disabled:opacity-40",
+            focusRing,
+          )}
+        />
+
+        <div className="flex min-w-0 flex-1 flex-col gap-1">
+          <label
+            htmlFor={checkboxId}
+            className={cn("font-medium", !selectable && "opacity-70")}
+          >
+            {action.summary}
+          </label>
+
+          <p className="flex flex-wrap items-center gap-x-2 gap-y-0.5 text-xs text-muted-foreground">
+            {/* Reversibility in words, always. It decides whether the undo
+                button means anything, so it cannot be a colour or an icon. */}
+            <span data-slot="action-ledger-reversibility">
+              {REVERSIBILITY_LABEL[action.reversibility]}
+            </span>
+            <span aria-hidden="true">·</span>
+            <span data-slot="action-ledger-status">{STATUS_LABEL[action.status]}</span>
+            {action.target ? (
+              <>
+                <span aria-hidden="true">·</span>
+                <span>{action.target}</span>
+              </>
+            ) : null}
+            {action.timestamp ? (
+              <>
+                <span aria-hidden="true">·</span>
+                <time dateTime={action.timestamp}>{action.timestamp}</time>
+              </>
+            ) : null}
+          </p>
+
+          {/* A failed revert is the state people most need to understand, so
+              the reason is shown rather than hidden behind the inspector. */}
+          {action.status === "failed" && action.error ? (
+            <p data-slot="action-ledger-error" className="text-xs text-destructive">
+              {action.error}
+            </p>
+          ) : null}
+
+          {children}
+        </div>
+      </div>
+    </li>
+  );
+}
+
+/** The list wrapper. A real list, so its length is announced. */
+export function ActionLedgerList({ className, ...props }: ComponentPropsWithRef<"ul">) {
+  return (
+    <ul
+      data-slot="action-ledger-list"
+      className={cn("flex list-none flex-col gap-2", className)}
+      {...props}
+    />
+  );
+}
+
+/** Collapsed payload for one entry: the arguments, the result, the diff. */
+export function ActionLedgerPayload({
+  className,
+  label = "Details",
+  children,
+  ...props
+}: ComponentPropsWithRef<typeof CollapsiblePrimitive.Root> & { label?: string }) {
+  return (
+    <CollapsiblePrimitive.Root
+      data-slot="action-ledger-payload"
+      className={cn("mt-1", className)}
+      {...props}
+    >
+      <CollapsiblePrimitive.Trigger
+        className={cn(
+          "rounded-md text-xs text-muted-foreground transition-colors hover:text-foreground",
+          focusRing,
+        )}
+      >
+        {label}
+      </CollapsiblePrimitive.Trigger>
+      <CollapsiblePrimitive.Content className="pt-2">{children}</CollapsiblePrimitive.Content>
+    </CollapsiblePrimitive.Root>
+  );
+}
+
+/**
+ * A summary of what is selected and what it will and will not undo.
+ *
+ * This exists because "Undo 4 selected" is not enough information when one of
+ * the four can only be compensated. Saying so before the click is the whole
+ * difference between an honest control and a misleading one.
+ */
+export function ActionLedgerSelectionSummary({
+  className,
+  ...props
+}: ComponentPropsWithRef<"p">) {
+  const { actions, selected } = useLedgerContext("ActionLedgerSelectionSummary");
+
+  const chosen = actions.filter((action) => selected.has(action.id));
+  const compensable = chosen.filter((a) => a.reversibility === "compensable").length;
+
+  if (chosen.length === 0) return null;
+
+  return (
+    <p
+      data-slot="action-ledger-selection-summary"
+      // Selection changes are user-driven and the wording matters, so it is
+      // announced politely rather than silently updating under the button.
+      aria-live="polite"
+      className={cn("text-xs text-muted-foreground", className)}
+      {...props}
+    >
+      {`${String(chosen.length)} selected`}
+      {compensable > 0
+        ? `, of which ${String(compensable)} can only be offset by a further action, not undone`
+        : ""}
+    </p>
+  );
+}
+
+export { ledgerEntryVariants };

package/src/components/ai-action-ledger/index.ts

@@ -0,0 +1,14 @@
+export {
+  ActionLedger,
+  ActionLedgerEntry,
+  ActionLedgerList,
+  ActionLedgerPayload,
+  ActionLedgerSelectionSummary,
+  ActionLedgerToolbar,
+  ledgerEntryVariants,
+  type ActionLedgerEntryProps,
+  type ActionLedgerProps,
+  type ActionStatus,
+  type LedgerAction,
+  type Reversibility,
+} from "./ai-action-ledger";

package/src/components/ai-action-ledger/meta.ts

@@ -0,0 +1,19 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "ai-action-ledger",
+  title: "AI Action Ledger",
+  description: "What an agent actually did, classified by what can be undone.",
+  category: "ai",
+  status: "stable",
+  dependencies: ["class-variance-authority", "radix-ui"],
+  registryDependencies: [],
+  files: ["ai-action-ledger.tsx"],
+  a11y:
+    "Reversibility is stated in words on every entry, never by colour or icon alone — it decides " +
+    "whether the undo control means anything, so it cannot be decoration. Selection uses native " +
+    "checkboxes with real labels, and the revert button carries the count in its accessible name " +
+    "so it says what pressing it will do. The selection summary is an aria-live region because " +
+    "the wording changes as the choice changes, and warns before the click when something can " +
+    "only be offset rather than undone.",
+});

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.",
+});