@dowel-ui/react 0.2.0 → 0.3.0

package/README.md

@@ -54,17 +54,18 @@ they want to change something.
 
 ## What is in it
 
-**52 components** and **8 blocks**, every one keyboard-operable and audited for
+**56 components** and **8 blocks**, every one keyboard-operable and audited for
 contrast.
 
 **AI** — the reason this library exists
 Conversation · Message · Response · Prompt Input · Tool Call · Reasoning ·
-Sources · Model Selector · Token Usage · Agent Status · **Action Ledger** ·
-**Structured Output** · **Inline Completion**
+Sources · Model Selector · Token Usage · Agent Status · **Agent Plan** ·
+**Approval Request** · **Action Ledger** · **Structured Output** ·
+**Inline Completion**
 
 **Forms**
 Input · Label · Checkbox · Radio Group · Switch · Slider · Select · Combobox ·
-Form · Calendar · Date Picker
+Form · Calendar · Date Picker · **Tags Input** · **File Upload**
 
 **Overlays**
 Dialog · Sheet · Drawer · Popover · Tooltip · Dropdown Menu
@@ -87,6 +88,11 @@ Most "AI component libraries" ship a chat transcript and stop. Real AI features
 inside real software are extraction, enrichment, autofill and agents that
 _change things_ — and those need surfaces nobody else provides.
 
+**`ai-agent-plan` + `ai-approval-request` + `ai-action-ledger`** — the whole
+sequence, which no other library covers: what the agent intends, the gate where
+you approve it (after correcting the arguments it got wrong), and the record of
+what it actually did.
+
 **`ai-action-ledger`** — what the agent actually did, and what can be undone.
 Everyone ships approval _before_ a tool runs. Nothing ships the part after,
 where a deletion can be reverted, a refund can only be offset by another

package/dist/components/ai-agent-plan/ai-agent-plan.d.ts

@@ -0,0 +1,50 @@
+import { ComponentPropsWithRef, ReactNode } from "react";
+//#region src/components/ai-agent-plan/ai-agent-plan.d.ts
+/**
+ * What an agent intends to do, and how far through it is.
+ *
+ * Not a stepper. A wizard's steps are decided up front and never change; an
+ * agent's plan is a hypothesis it revises as it learns — it adds a step when a
+ * lookup fails, drops one that turned out to be unnecessary, and reorders when
+ * a dependency appears. Every stepper treats its step list as fixed, so a plan
+ * rendered in one either silently mutates under the reader or re-renders from
+ * scratch and loses their place.
+ *
+ * So revision is the feature here, not an edge case. When the plan changes, the
+ * change is announced — "the model added a step" is information, and watching a
+ * list quietly grow is not the same as being told.
+ *
+ * Approval is not here. Deciding whether a plan may run is a different
+ * component with a different shape; this one displays and reports.
+ */
+type StepStatus = "pending" | "running" | "done" | "failed" | "skipped";
+interface PlanStep {
+  id: string;
+  title: string;
+  status: StepStatus;
+  /** What the step will do, or what it found. Shown under the title. */
+  detail?: string;
+  /** Why it failed. Shown only when the status is "failed". */
+  error?: string;
+  /** One level of sub-steps. Deeper nesting is a tree, which this is not. */
+  steps?: PlanStep[];
+}
+interface AgentPlanProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
+  steps: PlanStep[];
+  /** Names the plan, so the list is not an unlabelled sequence. */
+  label: string;
+  children?: ReactNode;
+}
+declare function AgentPlan({ className, steps, label, children, ...props }: AgentPlanProps): import("react").JSX.Element;
+/** "Step 3 of 6" plus the overall state, in words. */
+declare function AgentPlanSummary({ className, ...props }: ComponentPropsWithRef<"p">): import("react").JSX.Element;
+declare function AgentPlanSteps({ className, ...props }: ComponentPropsWithRef<"ol">): import("react").JSX.Element;
+interface AgentPlanStepProps extends Omit<ComponentPropsWithRef<"li">, "children"> {
+  step: PlanStep;
+  /** Set on sub-steps. Not part of the public API surface. */
+  nested?: boolean;
+}
+declare function AgentPlanStep({ className, step, nested, ...props }: AgentPlanStepProps): import("react").JSX.Element;
+//#endregion
+export { AgentPlan, AgentPlanProps, AgentPlanStep, AgentPlanStepProps, AgentPlanSteps, AgentPlanSummary, PlanStep, StepStatus };
+//# sourceMappingURL=ai-agent-plan.d.ts.map

package/dist/components/ai-agent-plan/ai-agent-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-agent-plan.d.ts","names":[],"sources":["../../../src/components/ai-agent-plan/ai-agent-plan.tsx"],"mappings":";;;;;;;;;;;;;;;;;;;KA+BY;UAEK;EACf;EACA;EACA,QAAQ;;EAER;;EAEA;;EAEA,QAAQ;;UAyCO,uBAAuB,KAAK;EAC3C,OAAO;;EAEP;EACA,WAAW;;iBAGG,YAAY,WAAW,OAAO,OAAO,aAAa,SAAS,iCAAc,IAAA;;iBAqDzE,mBAAmB,cAAc,SAAS,6CAA0B,IAAA;iBA2BpE,iBAAiB,cAAc,SAAS,8CAA2B,IAAA;UAkBlE,2BAA2B,KAAK;EAC/C,MAAM;;EAEN;;iBAGc,gBACd,WACA,MACA,WACG,SACF,qCAAkB,IAAA"}

package/dist/components/ai-agent-plan/ai-agent-plan.js

@@ -0,0 +1,156 @@
+"use client";
+import { cn } from "../../lib/utils.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { createContext, useContext, useMemo, useState } from "react";
+//#region src/components/ai-agent-plan/ai-agent-plan.tsx
+const STATUS_LABEL = {
+	pending: "Not started",
+	running: "In progress",
+	done: "Done",
+	failed: "Failed",
+	skipped: "Skipped"
+};
+/** Flattens one level, so counting and "step N of M" include sub-steps. */
+function flatten(steps) {
+	return steps.flatMap((step) => [step, ...step.steps ?? []]);
+}
+function describeRevision(added, removed) {
+	const parts = [];
+	if (added.length === 1 && added[0]) parts.push(`Plan updated: added "${added[0].title}"`);
+	else if (added.length > 1) parts.push(`Plan updated: ${String(added.length)} steps added`);
+	if (removed === 1) parts.push("1 step removed");
+	else if (removed > 1) parts.push(`${String(removed)} steps removed`);
+	return parts.join(", ");
+}
+const PlanContext = createContext(null);
+function usePlanContext(component) {
+	const context = useContext(PlanContext);
+	if (!context) throw new Error(`${component} must be rendered inside <AgentPlan>.`);
+	return context;
+}
+function AgentPlan({ className, steps, label, children, ...props }) {
+	const flat = useMemo(() => flatten(steps), [steps]);
+	const ids = flat.map((step) => step.id);
+	const [seen, setSeen] = useState(ids);
+	const [revision, setRevision] = useState("");
+	if (ids.join("\0") !== seen.join("\0")) {
+		const added = flat.filter((step) => !seen.includes(step.id));
+		const removed = seen.filter((id) => !ids.includes(id)).length;
+		setSeen(ids);
+		setRevision(added.length > 0 || removed > 0 ? describeRevision(added, removed) : "");
+	}
+	const currentIndex = flat.findIndex((step) => step.status === "running");
+	const context = useMemo(() => ({
+		steps,
+		flat,
+		currentIndex
+	}), [
+		steps,
+		flat,
+		currentIndex
+	]);
+	return /* @__PURE__ */ jsx(PlanContext.Provider, {
+		value: context,
+		children: /* @__PURE__ */ jsxs("div", {
+			"data-slot": "agent-plan",
+			"aria-label": label,
+			role: "group",
+			className: cn("flex flex-col gap-2", className),
+			...props,
+			children: [children ?? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(AgentPlanSummary, {}), /* @__PURE__ */ jsx(AgentPlanSteps, {})] }), /* @__PURE__ */ jsx("span", {
+				"aria-live": "polite",
+				"data-slot": "agent-plan-revision",
+				className: "sr-only",
+				children: revision
+			})]
+		})
+	});
+}
+/** "Step 3 of 6" plus the overall state, in words. */
+function AgentPlanSummary({ className, ...props }) {
+	const { flat, currentIndex } = usePlanContext("AgentPlanSummary");
+	const done = flat.filter((step) => step.status === "done").length;
+	const failed = flat.filter((step) => step.status === "failed").length;
+	const running = currentIndex >= 0;
+	const message = !flat.some((step) => step.status !== "pending") ? `Proposed plan, ${String(flat.length)} steps` : running ? `Step ${String(currentIndex + 1)} of ${String(flat.length)}` : failed > 0 ? `${String(done)} of ${String(flat.length)} done, ${String(failed)} failed` : `${String(done)} of ${String(flat.length)} done`;
+	return /* @__PURE__ */ jsx("p", {
+		"data-slot": "agent-plan-summary",
+		className: cn("text-xs text-muted-foreground tabular-nums", className),
+		...props,
+		children: message
+	});
+}
+function AgentPlanSteps({ className, ...props }) {
+	const { steps } = usePlanContext("AgentPlanSteps");
+	return /* @__PURE__ */ jsx("ol", {
+		"data-slot": "agent-plan-steps",
+		className: cn("flex list-none flex-col gap-1", className),
+		...props,
+		children: steps.map((step) => /* @__PURE__ */ jsx(AgentPlanStep, { step }, step.id))
+	});
+}
+function AgentPlanStep({ className, step, nested = false, ...props }) {
+	const { status, title, detail, error, steps: children } = step;
+	return /* @__PURE__ */ jsxs("li", {
+		"data-slot": "agent-plan-step",
+		"data-status": status,
+		"aria-current": status === "running" ? "step" : void 0,
+		className: cn("flex flex-col gap-1", nested && "ml-5", className),
+		...props,
+		children: [/* @__PURE__ */ jsxs("div", {
+			className: "flex items-start gap-2",
+			children: [/* @__PURE__ */ jsx(StepMarker, { status }), /* @__PURE__ */ jsxs("div", {
+				className: "flex min-w-0 flex-1 flex-col",
+				children: [
+					/* @__PURE__ */ jsxs("span", {
+						className: cn("text-sm", status === "pending" && "text-muted-foreground", status === "skipped" && "text-muted-foreground line-through", status === "failed" && "text-destructive", status === "running" && "font-medium"),
+						children: [title, /* @__PURE__ */ jsxs("span", {
+							className: "sr-only",
+							children: [", ", STATUS_LABEL[status]]
+						})]
+					}),
+					detail ? /* @__PURE__ */ jsx("span", {
+						className: "text-xs text-muted-foreground",
+						children: detail
+					}) : null,
+					status === "failed" && error ? /* @__PURE__ */ jsx("span", {
+						"data-slot": "agent-plan-error",
+						className: "text-xs text-destructive",
+						children: error
+					}) : null
+				]
+			})]
+		}), children && children.length > 0 ? /* @__PURE__ */ jsx("ol", {
+			className: "flex list-none flex-col gap-1",
+			children: children.map((child) => /* @__PURE__ */ jsx(AgentPlanStep, {
+				step: child,
+				nested: true
+			}, child.id))
+		}) : null]
+	});
+}
+/**
+* The status shape.
+*
+* aria-hidden throughout: every marker repeats what the step already states in
+* text, and announcing both means hearing the status twice per step.
+*/
+function StepMarker({ status }) {
+	const base = "mt-0.5 grid size-4 shrink-0 place-items-center rounded-full border text-[9px]";
+	if (status === "running") return /* @__PURE__ */ jsx("span", {
+		"aria-hidden": "true",
+		"data-slot": "agent-plan-marker",
+		className: cn(base, "animate-pulse-soft border-primary bg-primary/15 text-primary"),
+		children: /* @__PURE__ */ jsx("span", { className: "size-1.5 rounded-full bg-primary" })
+	});
+	return /* @__PURE__ */ jsx("span", {
+		"aria-hidden": "true",
+		"data-slot": "agent-plan-marker",
+		className: cn(base, status === "done" && "border-success bg-success text-success-foreground", status === "failed" && "border-destructive bg-destructive text-destructive-foreground", status === "skipped" && "border-border-strong text-muted-foreground", status === "pending" && "border-border-strong"),
+		children: status === "done" ? "✓" : status === "failed" ? "✕" : status === "skipped" ? "–" : null
+	});
+}
+//#endregion
+export { AgentPlan, AgentPlanStep, AgentPlanSteps, AgentPlanSummary };
+
+//# sourceMappingURL=ai-agent-plan.js.map

package/dist/components/ai-agent-plan/ai-agent-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-agent-plan.js","names":[],"sources":["../../../src/components/ai-agent-plan/ai-agent-plan.tsx"],"sourcesContent":["\"use client\";\n\nimport {\n  createContext,\n  useContext,\n  useMemo,\n  useState,\n  type ComponentPropsWithRef,\n  type ReactNode,\n} from \"react\";\n\nimport { cn } from \"@/lib/utils\";\n\n/**\n * What an agent intends to do, and how far through it is.\n *\n * Not a stepper. A wizard's steps are decided up front and never change; an\n * agent's plan is a hypothesis it revises as it learns — it adds a step when a\n * lookup fails, drops one that turned out to be unnecessary, and reorders when\n * a dependency appears. Every stepper treats its step list as fixed, so a plan\n * rendered in one either silently mutates under the reader or re-renders from\n * scratch and loses their place.\n *\n * So revision is the feature here, not an edge case. When the plan changes, the\n * change is announced — \"the model added a step\" is information, and watching a\n * list quietly grow is not the same as being told.\n *\n * Approval is not here. Deciding whether a plan may run is a different\n * component with a different shape; this one displays and reports.\n */\n\nexport type StepStatus = \"pending\" | \"running\" | \"done\" | \"failed\" | \"skipped\";\n\nexport interface PlanStep {\n  id: string;\n  title: string;\n  status: StepStatus;\n  /** What the step will do, or what it found. Shown under the title. */\n  detail?: string;\n  /** Why it failed. Shown only when the status is \"failed\". */\n  error?: string;\n  /** One level of sub-steps. Deeper nesting is a tree, which this is not. */\n  steps?: PlanStep[];\n}\n\nconst STATUS_LABEL: Record<StepStatus, string> = {\n  pending: \"Not started\",\n  running: \"In progress\",\n  done: \"Done\",\n  failed: \"Failed\",\n  skipped: \"Skipped\",\n};\n\n/** Flattens one level, so counting and \"step N of M\" include sub-steps. */\nfunction flatten(steps: PlanStep[]): PlanStep[] {\n  return steps.flatMap((step) => [step, ...(step.steps ?? [])]);\n}\n\nfunction describeRevision(added: PlanStep[], removed: number): string {\n  const parts: string[] = [];\n  if (added.length === 1 && added[0]) parts.push(`Plan updated: added \"${added[0].title}\"`);\n  else if (added.length > 1) parts.push(`Plan updated: ${String(added.length)} steps added`);\n  if (removed === 1) parts.push(\"1 step removed\");\n  else if (removed > 1) parts.push(`${String(removed)} steps removed`);\n  return parts.join(\", \");\n}\n\ninterface PlanContextValue {\n  steps: PlanStep[];\n  flat: PlanStep[];\n  currentIndex: number;\n}\n\nconst PlanContext = createContext<PlanContextValue | null>(null);\n\nfunction usePlanContext(component: string): PlanContextValue {\n  const context = useContext(PlanContext);\n  if (!context) {\n    throw new Error(`${component} must be rendered inside <AgentPlan>.`);\n  }\n  return context;\n}\n\nexport interface AgentPlanProps extends Omit<ComponentPropsWithRef<\"div\">, \"children\"> {\n  steps: PlanStep[];\n  /** Names the plan, so the list is not an unlabelled sequence. */\n  label: string;\n  children?: ReactNode;\n}\n\nexport function AgentPlan({ className, steps, label, children, ...props }: AgentPlanProps) {\n  const flat = useMemo(() => flatten(steps), [steps]);\n  const ids = flat.map((step) => step.id);\n\n  // Revision detection, adjusted during render rather than in an effect: an\n  // effect would announce a frame after the change is already on screen, and a\n  // ref read during render is unsafe under concurrent rendering.\n  const [seen, setSeen] = useState<string[]>(ids);\n  const [revision, setRevision] = useState(\"\");\n\n  if (ids.join(\"\u0000\") !== seen.join(\"\u0000\")) {\n    const added = flat.filter((step) => !seen.includes(step.id));\n    const removed = seen.filter((id) => !ids.includes(id)).length;\n    setSeen(ids);\n    // A plan whose steps only changed status has not been revised. Only\n    // structural change is worth interrupting for.\n    setRevision(added.length > 0 || removed > 0 ? describeRevision(added, removed) : \"\");\n  }\n\n  const currentIndex = flat.findIndex((step) => step.status === \"running\");\n\n  const context = useMemo<PlanContextValue>(\n    () => ({ steps, flat, currentIndex }),\n    [steps, flat, currentIndex],\n  );\n\n  return (\n    <PlanContext.Provider value={context}>\n      <div\n        data-slot=\"agent-plan\"\n        aria-label={label}\n        role=\"group\"\n        className={cn(\"flex flex-col gap-2\", className)}\n        {...props}\n      >\n        {children ?? (\n          <>\n            <AgentPlanSummary />\n            <AgentPlanSteps />\n          </>\n        )}\n\n        {/* Structural changes only. Announcing every status transition would\n            talk over the reader continuously on a plan of any length. */}\n        <span aria-live=\"polite\" data-slot=\"agent-plan-revision\" className=\"sr-only\">\n          {revision}\n        </span>\n      </div>\n    </PlanContext.Provider>\n  );\n}\n\n/** \"Step 3 of 6\" plus the overall state, in words. */\nexport function AgentPlanSummary({ className, ...props }: ComponentPropsWithRef<\"p\">) {\n  const { flat, currentIndex } = usePlanContext(\"AgentPlanSummary\");\n\n  const done = flat.filter((step) => step.status === \"done\").length;\n  const failed = flat.filter((step) => step.status === \"failed\").length;\n  const running = currentIndex >= 0;\n  const started = flat.some((step) => step.status !== \"pending\");\n\n  const message = !started\n    ? `Proposed plan, ${String(flat.length)} steps`\n    : running\n      ? `Step ${String(currentIndex + 1)} of ${String(flat.length)}`\n      : failed > 0\n        ? `${String(done)} of ${String(flat.length)} done, ${String(failed)} failed`\n        : `${String(done)} of ${String(flat.length)} done`;\n\n  return (\n    <p\n      data-slot=\"agent-plan-summary\"\n      className={cn(\"text-xs text-muted-foreground tabular-nums\", className)}\n      {...props}\n    >\n      {message}\n    </p>\n  );\n}\n\nexport function AgentPlanSteps({ className, ...props }: ComponentPropsWithRef<\"ol\">) {\n  const { steps } = usePlanContext(\"AgentPlanSteps\");\n\n  return (\n    // An ordered list: a plan is a sequence, and the order carries meaning that\n    // an unordered list would throw away.\n    <ol\n      data-slot=\"agent-plan-steps\"\n      className={cn(\"flex list-none flex-col gap-1\", className)}\n      {...props}\n    >\n      {steps.map((step) => (\n        <AgentPlanStep key={step.id} step={step} />\n      ))}\n    </ol>\n  );\n}\n\nexport interface AgentPlanStepProps extends Omit<ComponentPropsWithRef<\"li\">, \"children\"> {\n  step: PlanStep;\n  /** Set on sub-steps. Not part of the public API surface. */\n  nested?: boolean;\n}\n\nexport function AgentPlanStep({\n  className,\n  step,\n  nested = false,\n  ...props\n}: AgentPlanStepProps) {\n  const { status, title, detail, error, steps: children } = step;\n\n  return (\n    <li\n      data-slot=\"agent-plan-step\"\n      data-status={status}\n      // Marks where the reader is in the sequence without moving focus, which\n      // would fight anyone reading ahead.\n      aria-current={status === \"running\" ? \"step\" : undefined}\n      className={cn(\"flex flex-col gap-1\", nested && \"ml-5\", className)}\n      {...props}\n    >\n      <div className=\"flex items-start gap-2\">\n        <StepMarker status={status} />\n\n        <div className=\"flex min-w-0 flex-1 flex-col\">\n          <span\n            className={cn(\n              \"text-sm\",\n              status === \"pending\" && \"text-muted-foreground\",\n              status === \"skipped\" && \"text-muted-foreground line-through\",\n              status === \"failed\" && \"text-destructive\",\n              status === \"running\" && \"font-medium\",\n            )}\n          >\n            {title}\n            {/* Status in text, always. The marker is a shape and a colour, and\n                neither is information on its own. */}\n            <span className=\"sr-only\">, {STATUS_LABEL[status]}</span>\n          </span>\n\n          {detail ? <span className=\"text-xs text-muted-foreground\">{detail}</span> : null}\n          {status === \"failed\" && error ? (\n            <span data-slot=\"agent-plan-error\" className=\"text-xs text-destructive\">\n              {error}\n            </span>\n          ) : null}\n        </div>\n      </div>\n\n      {children && children.length > 0 ? (\n        <ol className=\"flex list-none flex-col gap-1\">\n          {children.map((child) => (\n            <AgentPlanStep key={child.id} step={child} nested />\n          ))}\n        </ol>\n      ) : null}\n    </li>\n  );\n}\n\n/**\n * The status shape.\n *\n * aria-hidden throughout: every marker repeats what the step already states in\n * text, and announcing both means hearing the status twice per step.\n */\nfunction StepMarker({ status }: { status: StepStatus }) {\n  const base = \"mt-0.5 grid size-4 shrink-0 place-items-center rounded-full border text-[9px]\";\n\n  if (status === \"running\") {\n    return (\n      // Deliberately not data-motion=\"indicator\". The bar for that exemption is\n      // that stopping the animation would say something false, and it would\n      // not: the step already states \"In progress\" in text and carries\n      // aria-current. This pulse is reinforcement, so under reduced motion it\n      // stops like any other decoration.\n      <span\n        aria-hidden=\"true\"\n        data-slot=\"agent-plan-marker\"\n        className={cn(base, \"animate-pulse-soft border-primary bg-primary/15 text-primary\")}\n      >\n        <span className=\"size-1.5 rounded-full bg-primary\" />\n      </span>\n    );\n  }\n\n  return (\n    <span\n      aria-hidden=\"true\"\n      data-slot=\"agent-plan-marker\"\n      className={cn(\n        base,\n        status === \"done\" && \"border-success bg-success text-success-foreground\",\n        status === \"failed\" && \"border-destructive bg-destructive text-destructive-foreground\",\n        status === \"skipped\" && \"border-border-strong text-muted-foreground\",\n        status === \"pending\" && \"border-border-strong\",\n      )}\n    >\n      {status === \"done\" ? \"✓\" : status === \"failed\" ? \"✕\" : status === \"skipped\" ? \"–\" : null}\n    </span>\n  );\n}\n"],"mappings":"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"}

package/dist/components/ai-agent-plan/index.d.ts

@@ -0,0 +1,2 @@
+import { AgentPlan, AgentPlanProps, AgentPlanStep, AgentPlanStepProps, AgentPlanSteps, AgentPlanSummary, PlanStep, StepStatus } from "./ai-agent-plan.js";
+export { AgentPlan, type AgentPlanProps, AgentPlanStep, type AgentPlanStepProps, AgentPlanSteps, AgentPlanSummary, type PlanStep, type StepStatus };

package/dist/components/ai-agent-plan/index.js

@@ -0,0 +1,2 @@
+import { AgentPlan, AgentPlanStep, AgentPlanSteps, AgentPlanSummary } from "./ai-agent-plan.js";
+export { AgentPlan, AgentPlanStep, AgentPlanSteps, AgentPlanSummary };

package/dist/components/ai-agent-plan/meta.js

@@ -0,0 +1,17 @@
+import { defineMeta } from "../../registry/schema.js";
+//#region src/components/ai-agent-plan/meta.ts
+const meta = defineMeta({
+	name: "ai-agent-plan",
+	title: "AI Agent Plan",
+	description: "What an agent intends to do — including when it changes its mind mid-run.",
+	category: "ai",
+	status: "stable",
+	dependencies: [],
+	registryDependencies: [],
+	files: ["ai-agent-plan.tsx"],
+	a11y: "An ordered list, because a plan is a sequence and the order carries meaning an unordered list would discard. The running step carries aria-current=\"step\", which marks the reader's place without moving focus and fighting anyone reading ahead. Every status is stated in text as well as drawn, and the markers are aria-hidden so the status is not heard twice per step. The live region reports structural revisions only — announcing every status transition would talk over the reader continuously on a plan of any length."
+});
+//#endregion
+export { meta };
+
+//# sourceMappingURL=meta.js.map

package/dist/components/ai-agent-plan/meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.js","names":[],"sources":["../../../src/components/ai-agent-plan/meta.ts"],"sourcesContent":["import { defineMeta } from \"@/registry/schema\";\n\nexport const meta = defineMeta({\n  name: \"ai-agent-plan\",\n  title: \"AI Agent Plan\",\n  description: \"What an agent intends to do — including when it changes its mind mid-run.\",\n  category: \"ai\",\n  status: \"stable\",\n  dependencies: [],\n  registryDependencies: [],\n  files: [\"ai-agent-plan.tsx\"],\n  a11y:\n    \"An ordered list, because a plan is a sequence and the order carries meaning an unordered \" +\n    'list would discard. The running step carries aria-current=\"step\", which marks the reader\\'s ' +\n    \"place without moving focus and fighting anyone reading ahead. Every status is stated in text \" +\n    \"as well as drawn, and the markers are aria-hidden so the status is not heard twice per step. \" +\n    \"The live region reports structural revisions only — announcing every status transition would \" +\n    \"talk over the reader continuously on a plan of any length.\",\n});\n"],"mappings":";;AAEA,MAAa,OAAO,WAAW;CAC7B,MAAM;CACN,OAAO;CACP,aAAa;CACb,UAAU;CACV,QAAQ;CACR,cAAc,CAAC;CACf,sBAAsB,CAAC;CACvB,OAAO,CAAC,mBAAmB;CAC3B,MACE;AAMJ,CAAC"}

package/dist/components/ai-agent-status/ai-agent-status.d.ts

@@ -10,7 +10,7 @@ import { ComponentPropsWithRef } from "react";
  */
 type AgentState = "idle" | "thinking" | "working" | "waiting" | "done" | "error";
 declare const agentStatusVariants: (props?: ({
-  state?: "done" | "idle" | "thinking" | "working" | "waiting" | "error" | null | undefined;
+  state?: "done" | "error" | "idle" | "thinking" | "working" | "waiting" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 interface AgentStatusProps extends ComponentPropsWithRef<"span">, VariantProps<typeof agentStatusVariants> {
   state?: AgentState;

package/dist/components/ai-approval-request/ai-approval-request.d.ts

@@ -0,0 +1,67 @@
+import { ComponentPropsWithRef, ReactNode } from "react";
+//#region src/components/ai-approval-request/ai-approval-request.d.ts
+/**
+ * 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.
+ */
+type ApprovalScope = "once" | "always";
+type ApprovalDecision = {
+  approved: true;
+  scope: ApprovalScope;
+  arguments: Record<string, string>;
+  edited: string[];
+} | {
+  approved: false;
+  reason?: string;
+};
+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;
+}
+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;
+}
+declare function ApprovalRequest({ className, tool, summary, arguments: proposed, fields, onDecision, streaming, irreversible, decision, children, ...props }: ApprovalRequestProps): import("react").JSX.Element;
+//#endregion
+export { ApprovalDecision, ApprovalField, ApprovalRequest, ApprovalRequestProps, ApprovalScope };
+//# sourceMappingURL=ai-approval-request.d.ts.map

package/dist/components/ai-approval-request/ai-approval-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-approval-request.d.ts","names":[],"sources":["../../../src/components/ai-approval-request/ai-approval-request.tsx"],"mappings":";;;;;;;;;;;;;;;;;;;;;KA2BY;KAEA;EAEN;EACA,OAAO;EACP,WAAW;EACX;;EAEA;EAAiB;;UAEN;EACf;EACA;;EAEA;;EAEA;;UAGe,6BAA6B,KAC5C;;EAIA;;EAEA;;EAEA,WAAW;;EAEX,QAAQ;EACR,aAAa,UAAU;;;;;EAKvB;;;;;EAKA;;EAEA,WAAW;EACX,WAAW;;iBAGG,kBACd,WACA,MACA,SACA,WAAW,UACX,QACA,YACA,WACA,cACA,UACA,aACG,SACF,uCAAoB,IAAA"}

package/dist/components/ai-approval-request/ai-approval-request.js

@@ -0,0 +1,218 @@
+"use client";
+import { disabledStyles, focusRing } from "../../lib/styles.js";
+import { cn } from "../../lib/utils.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useId, useMemo, useState } from "react";
+//#region src/components/ai-approval-request/ai-approval-request.tsx
+function ApprovalRequest({ className, tool, summary, arguments: proposed, fields, onDecision, streaming = false, irreversible, decision, children, ...props }) {
+	const headingId = useId();
+	const [edits, setEdits] = useState({});
+	const [denying, setDenying] = useState(false);
+	const [reason, setReason] = useState("");
+	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] === void 0);
+	const settled = !streaming && missing.length === 0;
+	if (decision) return /* @__PURE__ */ jsxs("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,
+		children: [/* @__PURE__ */ jsx("h3", {
+			id: headingId,
+			className: "text-sm font-medium",
+			children: summary
+		}), /* @__PURE__ */ jsx("p", {
+			"data-slot": "approval-outcome",
+			className: "mt-1 text-xs text-muted-foreground",
+			children: 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}` : ""}`
+		})]
+	});
+	return /* @__PURE__ */ jsxs("section", {
+		"data-slot": "approval-request",
+		"data-state": settled ? "pending" : "forming",
+		"aria-labelledby": headingId,
+		"aria-busy": !settled,
+		className: cn("rounded-lg border border-border bg-card p-4", className),
+		...props,
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex flex-wrap items-baseline justify-between gap-2",
+				children: [/* @__PURE__ */ jsx("h3", {
+					id: headingId,
+					className: "text-sm font-medium",
+					children: summary
+				}), /* @__PURE__ */ jsx("code", {
+					className: "rounded bg-muted px-1.5 py-0.5 font-mono text-2xs text-muted-foreground",
+					children: tool
+				})]
+			}),
+			/* @__PURE__ */ jsx("dl", {
+				className: "mt-3 flex flex-col gap-2.5",
+				children: fields.map((field) => {
+					const arrived = proposed[field.name] !== void 0;
+					const changed = edited.includes(field.name);
+					return /* @__PURE__ */ jsx(ApprovalArgument, {
+						field,
+						value: values[field.name] ?? "",
+						arrived,
+						changed,
+						onChange: (next) => {
+							setEdits((current) => ({
+								...current,
+								[field.name]: next
+							}));
+						}
+					}, field.name);
+				})
+			}),
+			children,
+			irreversible ? /* @__PURE__ */ jsx("p", {
+				"data-slot": "approval-warning",
+				className: "mt-3 text-xs text-destructive",
+				children: irreversible
+			}) : null,
+			denying ? /* @__PURE__ */ jsxs("div", {
+				className: "mt-3 flex flex-col gap-2",
+				children: [
+					/* @__PURE__ */ jsx("label", {
+						htmlFor: `${headingId}-reason`,
+						className: "text-xs text-muted-foreground",
+						children: "Why not? The model sees this."
+					}),
+					/* @__PURE__ */ jsx("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)
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						className: "flex flex-wrap gap-2",
+						children: [/* @__PURE__ */ jsx(Action, {
+							variant: "destructive",
+							onClick: () => {
+								onDecision({
+									approved: false,
+									reason: reason.trim() || void 0
+								});
+							},
+							children: "Deny"
+						}), /* @__PURE__ */ jsx(Action, {
+							onClick: () => {
+								setDenying(false);
+							},
+							children: "Back"
+						})]
+					})
+				]
+			}) : /* @__PURE__ */ jsxs("div", {
+				className: "mt-4 flex flex-wrap items-center gap-2",
+				children: [
+					/* @__PURE__ */ jsx(Action, {
+						variant: "primary",
+						disabled: !settled,
+						onClick: () => {
+							onDecision({
+								approved: true,
+								scope: "once",
+								arguments: values,
+								edited
+							});
+						},
+						children: edited.length > 0 ? "Approve with changes" : "Approve once"
+					}),
+					/* @__PURE__ */ jsxs(Action, {
+						disabled: !settled,
+						onClick: () => {
+							onDecision({
+								approved: true,
+								scope: "always",
+								arguments: values,
+								edited
+							});
+						},
+						children: ["Always allow ", tool]
+					}),
+					/* @__PURE__ */ jsx(Action, {
+						onClick: () => {
+							setDenying(true);
+						},
+						children: "Deny…"
+					}),
+					!settled ? /* @__PURE__ */ jsx("span", {
+						"aria-live": "polite",
+						className: "text-xs text-muted-foreground",
+						children: "Waiting for the model to finish the request"
+					}) : null
+				]
+			})
+		]
+	});
+}
+function ApprovalArgument({ field, value, arrived, changed, onChange }) {
+	const id = useId();
+	const changedId = useId();
+	const editable = !field.readOnly && arrived;
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "approval-argument",
+		"data-changed": changed || void 0,
+		className: "flex flex-col gap-1",
+		children: [/* @__PURE__ */ jsxs("dt", {
+			className: "flex items-baseline gap-1",
+			children: [/* @__PURE__ */ jsx("label", {
+				htmlFor: editable ? id : void 0,
+				className: "text-xs text-muted-foreground",
+				children: field.label
+			}), changed ? /* @__PURE__ */ jsx("span", {
+				id: changedId,
+				className: "text-xs text-warning",
+				children: "· changed from the model’s proposal"
+			}) : null]
+		}), /* @__PURE__ */ jsx("dd", {
+			className: "m-0",
+			children: !arrived ? /* @__PURE__ */ jsx("span", {
+				"aria-hidden": "true",
+				className: "block h-8 w-full animate-pulse-soft rounded-md bg-muted"
+			}) : editable ? field.multiline ? /* @__PURE__ */ jsx("textarea", {
+				id,
+				"aria-describedby": changed ? changedId : void 0,
+				rows: 3,
+				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)
+			}) : /* @__PURE__ */ jsx("input", {
+				id,
+				type: "text",
+				"aria-describedby": changed ? changedId : void 0,
+				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)
+			}) : /* @__PURE__ */ jsx("p", {
+				className: "rounded-md bg-muted px-2 py-1.5 font-mono text-xs break-words",
+				children: value
+			})
+		})]
+	});
+}
+function Action({ className, variant = "default", ...props }) {
+	return /* @__PURE__ */ jsx("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
+	});
+}
+//#endregion
+export { ApprovalRequest };
+
+//# sourceMappingURL=ai-approval-request.js.map