@superxd-studio/adptr 0.5.0 → 0.6.0

package/source/reusable/interactions/progress.tsx

@@ -0,0 +1,240 @@
+import { useId, useState, type ReactNode } from "react";
+import { Button } from "../../components/button.js";
+import { IconAlert, IconCheck, IconChevronDown } from "../../components/icons.js";
+import { Thinking } from "../../components/thinking.js";
+import { Progress } from "../../components/ui/display.js";
+import { cn } from "../../lib/cn.js";
+import { useInteractionCopy } from "./context.js";
+
+/** Working, possibly stuck, waiting for the person, or done */
+export type TaskProgressStatus = "working" | "stuck" | "needs-you" | "done";
+
+export interface TaskProgressMove {
+  id: string;
+  label: string;
+  onPress: () => void;
+  primary?: boolean;
+}
+
+export interface TaskProgressProps {
+  /** The task, in words: "Building the new pricing page". Shown once it's done. */
+  task: string;
+  /** What it's doing now, in human words: "Testing the annual toggle", not "Running command" */
+  now: string;
+  /** The agent's plan */
+  stages: readonly string[];
+  /** The stage it's on, from 0. Stages before it are done; stages.length means all done. */
+  stage: number;
+  status?: TaskProgressStatus;
+  /** Time as a range, never a countdown: "~3–8 min left" */
+  estimate: string;
+  /** What the estimate is based on: "From the last 20 runs" */
+  basis?: string;
+  /** Counted progress, when the work can be counted */
+  counted?: { label: string; value: number; max: number; valueLabel?: string };
+  /** Why the estimate changed */
+  changed?: ReactNode;
+  /** Whether it needs the person, in words. Defaults to "No action needed". */
+  needs?: string;
+  /** Shows Review on the line while it needs the person */
+  onReview?: () => void;
+  /** Moves such as Keep waiting or Stop, at the right end */
+  moves?: readonly TaskProgressMove[];
+  defaultExpanded?: boolean;
+}
+
+/**
+ * Agent task progress, in one line: what it's doing, how many stages are done and roughly how
+ * long is left. Progress is a fact; time is a range with its basis. It opens to the stages.
+ */
+export function TaskProgress({
+  task,
+  now,
+  stages,
+  stage,
+  status = "working",
+  estimate,
+  basis,
+  counted,
+  changed,
+  needs,
+  onReview,
+  moves = [],
+  defaultExpanded = false,
+}: TaskProgressProps) {
+  const copy = useInteractionCopy().progress;
+  const [open, setOpen] = useState(defaultExpanded);
+  const panel = useId();
+  const total = stages.length;
+  const done = status === "done";
+  const sorted = [...moves].sort((a, b) => Number(Boolean(a.primary)) - Number(Boolean(b.primary)));
+
+  return (
+    <article className="flex w-full min-w-0 flex-col overflow-hidden rounded-surface border border-line-subtle bg-surface-muted">
+      <div className="flex flex-wrap items-center gap-x-3 gap-y-2 p-3">
+        <span
+          aria-hidden="true"
+          className={cn(
+            "flex size-8 shrink-0 items-center justify-center rounded-control border border-line-subtle bg-surface",
+            done && "border-done bg-done text-on-done",
+            status === "stuck" && "border-attention-line bg-attention-subtle text-attention",
+          )}
+        >
+          {done ? (
+            <IconCheck className="size-4" />
+          ) : status === "stuck" ? (
+            <IconAlert className="size-4" />
+          ) : (
+            <Thinking tone={status === "needs-you" ? "info" : "brand"} />
+          )}
+        </span>
+        <div role="status" className="flex min-w-0 flex-1 flex-col gap-1">
+          <span className="truncate type-label text-fg-emphasis">{done ? task : now}</span>
+          <span className="flex flex-wrap gap-1.5 type-caption text-fg-subtle">
+            <span>{copy.stagesDone(Math.min(stage, total), total)}</span>
+            <span aria-hidden="true">·</span>
+            <span
+              className={cn(
+                status === "stuck" && "text-attention",
+                status === "needs-you" && "text-info",
+              )}
+            >
+              {estimate}
+            </span>
+          </span>
+        </div>
+        {status === "needs-you" && onReview ? (
+          <Button size="sm" variant="primary" onPress={onReview}>
+            {copy.review}
+          </Button>
+        ) : null}
+        <Button
+          size="sm"
+          variant="ghost"
+          className="group/trigger"
+          aria-label={copy.showStages}
+          aria-expanded={open}
+          aria-controls={panel}
+          onPress={() => setOpen((value) => !value)}
+        >
+          <IconChevronDown className="transition-[rotate] duration-(--duration-settle) ease-settle group-aria-expanded/trigger:rotate-180 motion-reduce:transition-none" />
+        </Button>
+      </div>
+      {open ? (
+        <div
+          id={panel}
+          className="flex animate-reveal-in flex-col gap-4 border-t border-line-subtle bg-surface p-4"
+        >
+          {/* The plan: done ✓, now ●, still to come ○ */}
+          <ol className="flex flex-col gap-2.5">
+            {stages.map((name, index) => {
+              const past = index < stage;
+              const current = index === stage && !done;
+              return (
+                <li key={name} className="flex gap-3 type-body">
+                  {/* A marker column one line high, so every stage's words line up */}
+                  <span aria-hidden="true" className="flex h-5 shrink-0 items-center">
+                    <span className="flex size-4 items-center justify-center">
+                      {past ? (
+                        <IconCheck className="size-3.5 text-success" />
+                      ) : current ? (
+                        status === "stuck" ? (
+                          <IconAlert className="size-3.5 text-attention" />
+                        ) : (
+                          <Thinking tone={status === "needs-you" ? "info" : "brand"} />
+                        )
+                      ) : (
+                        <span className="size-2 rounded-pill border border-line-emphasis" />
+                      )}
+                    </span>
+                  </span>
+                  <div className="flex min-w-0 flex-1 flex-col gap-1.5">
+                    <span
+                      className={cn(
+                        current
+                          ? "font-medium text-fg-emphasis"
+                          : past
+                            ? "text-fg"
+                            : "text-fg-subtle",
+                      )}
+                    >
+                      {name}
+                      <span className="sr-only">
+                        {" "}
+                        ·{" "}
+                        {past
+                          ? copy.stageWords.done
+                          : current
+                            ? copy.stageWords.now
+                            : copy.stageWords.next}
+                      </span>
+                    </span>
+                    {current ? (
+                      <>
+                        <span className="type-caption text-fg-subtle">{now}</span>
+                        {counted ? (
+                          <Progress
+                            label={counted.label}
+                            value={counted.value}
+                            maxValue={counted.max}
+                            valueLabel={counted.valueLabel}
+                          />
+                        ) : null}
+                      </>
+                    ) : null}
+                  </div>
+                </li>
+              );
+            })}
+          </ol>
+          {changed ? (
+            <p className="rounded-control border border-attention-line bg-attention-subtle px-3 py-2 type-body text-attention">
+              {changed}
+            </p>
+          ) : null}
+          {/* The estimate far left, whether it needs you far right */}
+          <div className="flex flex-wrap items-start justify-between gap-4 border-t border-line-subtle pt-3">
+            <div className="flex min-w-0 flex-col gap-0.5">
+              <span className="type-label text-fg-emphasis">{estimate}</span>
+              {basis ? <span className="type-caption text-fg-subtle">{basis}</span> : null}
+            </div>
+            <span
+              className={cn(
+                "flex items-center gap-1.5 type-label",
+                status === "stuck"
+                  ? "text-attention"
+                  : status === "needs-you"
+                    ? "text-info"
+                    : "text-fg-subtle",
+              )}
+            >
+              {status === "stuck" ? (
+                <IconAlert className="size-4" />
+              ) : status === "needs-you" ? (
+                <Thinking tone="info" />
+              ) : (
+                <IconCheck className="size-4" />
+              )}
+              {needs ?? copy.noAction}
+            </span>
+          </div>
+          {/* Review is already on the line itself */}
+          {sorted.length && status !== "needs-you" ? (
+            <div className="flex flex-wrap justify-end gap-2">
+              {sorted.map((move) => (
+                <Button
+                  key={move.id}
+                  size="sm"
+                  variant={move.primary ? "primary" : "secondary"}
+                  onPress={move.onPress}
+                >
+                  {move.label}
+                </Button>
+              ))}
+            </div>
+          ) : null}
+        </div>
+      ) : null}
+    </article>
+  );
+}

package/source/reusable/interactions/receipt.tsx

@@ -0,0 +1,230 @@
+import { useEffect, useState, type ReactNode } from "react";
+import { Button } from "../../components/button.js";
+import { IconAlert, IconCheck, IconHourglass, IconRotate, IconX } from "../../components/icons.js";
+import { Thinking } from "../../components/thinking.js";
+import { cn } from "../../lib/cn.js";
+import { useInteractionCopy } from "./context.js";
+
+/** How it went: as approved, differently, partly, not at all, not known yet, or undone */
+export type ReceiptOutcome = "done" | "different" | "partial" | "failed" | "unknown" | "undone";
+export type ReceiptChangeState = "changed" | "not-changed" | "unknown" | "reverted";
+
+export interface ReceiptChange {
+  id: string;
+  /** What changed, in a word or two: "Padding" */
+  what: string;
+  /** How: "12 → 16px" */
+  detail: string;
+  state?: ReceiptChangeState;
+  /** Your own word for the state, such as "Held back" */
+  stateLabel?: string;
+  /** This line's own way back, available while undo is open */
+  back?: { label: string; onPress: () => void };
+}
+
+export interface ReceiptAction {
+  id: string;
+  label: string;
+  onPress: () => void;
+  primary?: boolean;
+}
+
+export interface ActionReceiptProps {
+  outcome: ReceiptOutcome;
+  /** What happened, as a fact with its scale: "Updated the shared Button on 34 screens" */
+  title: string;
+  /** When, and who approved it: "3:41pm · approved by you" */
+  meta?: string;
+  /** What differs from what was approved, or why: said before anything else */
+  note?: ReactNode;
+  changes: readonly ReceiptChange[];
+  /**
+   * A choice with too many answers for buttons, handed back to the person to answer in the
+   * conversation: "What should happen to the 3 locked screens? Reply to the build agent."
+   */
+  ask?: ReactNode;
+  /** Next moves such as Try again or Check what happened; they sit at the right end */
+  actions?: readonly ReceiptAction[];
+  /** When the ways back close. Shows a quiet countdown in whole minutes. */
+  undoClosesAt?: Date;
+  /** When undo closes, in words, for screen readers: "to undo, until 3:51pm" */
+  undoClosesLabel?: string;
+  /** While the host checks what happened */
+  checking?: boolean;
+}
+
+/** Undo closes at a set time: count the minutes quietly, never the seconds */
+function useMinutesLeft(closesAt?: Date) {
+  const stamp = closesAt?.getTime();
+  const deadline = stamp !== undefined && Number.isFinite(stamp) ? stamp : undefined;
+  const [clock, setClock] = useState(() => ({ deadline, now: Date.now() }));
+  // A new host deadline must take effect immediately, before the next quiet clock tick.
+  if (clock.deadline !== deadline) setClock(() => ({ deadline, now: Date.now() }));
+  useEffect(() => {
+    if (deadline === undefined) return;
+    const update = () =>
+      setClock((current) =>
+        current.deadline === deadline ? { deadline, now: Date.now() } : current,
+      );
+    const interval = window.setInterval(update, 15_000);
+    // Remove ways back at the actual expiry, including between the quarter-minute ticks.
+    const expiry = window.setTimeout(update, Math.max(0, deadline - Date.now()));
+    return () => {
+      window.clearInterval(interval);
+      window.clearTimeout(expiry);
+    };
+  }, [deadline]);
+  return deadline === undefined ? 0 : Math.max(0, Math.ceil((deadline - clock.now) / 60_000));
+}
+
+/** The tile says the outcome at a glance; the title says it in words */
+function Tile({ outcome, checking }: { outcome: ReceiptOutcome; checking: boolean }) {
+  const done = !checking && (outcome === "done" || outcome === "different");
+  return (
+    <span
+      aria-hidden="true"
+      className={cn(
+        "flex size-8 shrink-0 items-center justify-center rounded-control border",
+        checking && "border-line-subtle bg-surface",
+        done && "border-done bg-done text-on-done",
+        !checking &&
+          outcome === "partial" &&
+          "border-attention-line bg-attention-subtle text-attention",
+        !checking && outcome === "failed" && "border-error-line bg-error-subtle text-error",
+        !checking &&
+          (outcome === "unknown" || outcome === "undone") &&
+          "border-line-subtle bg-surface text-fg-subtle",
+      )}
+    >
+      {checking ? (
+        <Thinking />
+      ) : done ? (
+        <IconCheck className="size-4" />
+      ) : outcome === "partial" ? (
+        <IconAlert className="size-4" />
+      ) : outcome === "failed" ? (
+        <IconX className="size-4" />
+      ) : outcome === "unknown" ? (
+        <IconHourglass className="size-4" />
+      ) : (
+        <IconRotate className="size-4" />
+      )}
+    </span>
+  );
+}
+
+/**
+ * The Action Receipt: what happened after the person approved, what changed, and how to undo
+ * it. Each change is a line with its own way back while undo is open, and a quiet countdown
+ * says how long that lasts. Facts, not reassurance; the host proves what happened.
+ */
+export function ActionReceipt({
+  outcome,
+  title,
+  meta,
+  note,
+  changes,
+  ask,
+  actions = [],
+  undoClosesAt,
+  undoClosesLabel,
+  checking = false,
+}: ActionReceiptProps) {
+  const copy = useInteractionCopy().receipt;
+  const minutesLeft = useMinutesLeft(undoClosesAt);
+  const open = Boolean(undoClosesAt) && minutesLeft > 0 && outcome !== "undone";
+  const tone =
+    outcome === "different" || outcome === "partial"
+      ? "text-attention"
+      : outcome === "failed"
+        ? "text-error"
+        : "text-fg";
+  // Next moves sit at the right end, the main one furthest right
+  const moves = [...actions].sort(
+    (a, b) => Number(Boolean(a.primary)) - Number(Boolean(b.primary)),
+  );
+
+  return (
+    <article className="flex w-full min-w-0 flex-col gap-4 rounded-surface border border-line-subtle bg-surface p-5">
+      <p role="status" className="sr-only">
+        {checking ? copy.checking : title}
+        {!checking && undoClosesAt && !open && outcome !== "undone" ? ` ${copy.closed}` : null}
+      </p>
+      <div className="flex items-start gap-3">
+        <Tile outcome={outcome} checking={checking} />
+        <div className="flex min-w-0 flex-col gap-0.5">
+          <span className="type-label text-pretty text-fg-emphasis">
+            {checking ? copy.checking : title}
+          </span>
+          {meta ? <span className="font-mono type-caption text-fg-subtle">{meta}</span> : null}
+        </div>
+      </div>
+      {checking ? null : (
+        <>
+          {note ? <p className={cn("type-body text-pretty", tone)}>{note}</p> : null}
+          <div className="flex flex-col gap-2">
+            <span className="font-mono type-caption text-fg-subtle">{copy.whatChanged}</span>
+            <ul className="flex flex-col divide-y divide-line-subtle rounded-control border border-line-subtle bg-surface">
+              {changes.map((change) => {
+                const state = change.state ?? "changed";
+                return (
+                  <li key={change.id} className="flex flex-wrap items-center gap-x-3 p-3 type-body">
+                    <span className="font-medium text-fg-emphasis">{change.what}</span>
+                    <span className="min-w-0 flex-1 text-fg-subtle">{change.detail}</span>
+                    {/* The same slot on every line, so rows keep one height whatever they hold */}
+                    <span className="flex h-control-sm shrink-0 items-center">
+                      {state !== "changed" || change.stateLabel ? (
+                        <span
+                          className={cn(
+                            "type-caption",
+                            state === "not-changed" ? "text-attention" : "text-fg-subtle",
+                          )}
+                        >
+                          {change.stateLabel ?? copy.states[state]}
+                        </span>
+                      ) : change.back && open ? (
+                        <Button
+                          size="sm"
+                          aria-label={`${change.back.label} ${change.what.toLowerCase()}`}
+                          onPress={() => {
+                            if (undoClosesAt && Date.now() < undoClosesAt.getTime())
+                              change.back?.onPress();
+                          }}
+                        >
+                          {change.back.label}
+                        </Button>
+                      ) : null}
+                    </span>
+                  </li>
+                );
+              })}
+            </ul>
+          </div>
+          {ask ? <p className="type-body text-pretty text-fg-emphasis">{ask}</p> : null}
+          {moves.length || undoClosesAt ? (
+            <div className="flex flex-wrap items-center justify-end gap-2">
+              {moves.map((action) => (
+                <Button
+                  key={action.id}
+                  size="sm"
+                  variant={action.primary ? "primary" : "secondary"}
+                  onPress={action.onPress}
+                >
+                  {action.label}
+                </Button>
+              ))}
+              {undoClosesAt && outcome !== "undone" ? (
+                <span className="font-mono type-label text-fg-subtle">
+                  {open ? copy.minutesLeft(minutesLeft) : copy.closed}
+                  {open && undoClosesLabel ? (
+                    <span className="sr-only"> {undoClosesLabel}</span>
+                  ) : null}
+                </span>
+              ) : null}
+            </div>
+          ) : null}
+        </>
+      )}
+    </article>
+  );
+}

package/source/reusable/interactions/run.tsx

@@ -0,0 +1,206 @@
+import { createContext, useContext, type ReactNode } from "react";
+import { IconBookOpen, IconEdit, IconTerminal } from "../../components/icons.js";
+import { cn } from "../../lib/cn.js";
+import { Peek } from "../../components/peek.js";
+import { Thinking } from "../../components/thinking.js";
+import { useInteractionCopy } from "./context.js";
+
+/**
+ * What a dot says: green when a step succeeded, grey for thoughts and the agent's words (smaller
+ * for thoughts), blue while waiting for the person, the pixel matrix while working.
+ */
+export type RunDot = "success" | "note" | "thought" | "waiting" | "working";
+
+/** Inside a run, a Decision Gate becomes the run's next entry */
+export const RunContext = createContext(false);
+export const useInRun = () => useContext(RunContext);
+
+/**
+ * An agent's run as a timeline, like Claude Code or VS Code: one rail down the left through a
+ * dot for each entry. Put RunStep, RunThought, RunMessage, a DecisionGate and RunWorking inside.
+ */
+export function RunTimeline({ label, children }: { label?: string; children: ReactNode }) {
+  return (
+    <RunContext.Provider value={true}>
+      <ol aria-label={label} className="run-timeline flex flex-col gap-4">
+        {children}
+      </ol>
+    </RunContext.Provider>
+  );
+}
+
+/**
+ * One entry: a dot and what happened. The rail runs from the first dot to the last. A text
+ * entry's dot sits on its first line; a card's sits level with the card's tile.
+ */
+export function RunEntry({
+  dot,
+  card = false,
+  children,
+}: {
+  dot: RunDot;
+  card?: boolean;
+  children: ReactNode;
+}) {
+  return (
+    // The columns, the rail and the dot's height come from .run-entry in library.css
+    <li data-card={card || undefined} className="run-entry grid gap-x-3 type-body">
+      <span aria-hidden="true" className="run-dot flex items-center justify-center">
+        {dot === "working" ? (
+          <Thinking />
+        ) : (
+          <span
+            className={cn(
+              "relative rounded-pill",
+              dot === "thought" ? "size-1" : "size-1.5",
+              dot === "success" && "bg-success-line",
+              (dot === "note" || dot === "thought") && "bg-line-emphasis",
+              dot === "waiting" && "animate-pulse-soft bg-info",
+            )}
+          />
+        )}
+      </span>
+      <div className="min-w-0 type-body wrap-anywhere">{children}</div>
+    </li>
+  );
+}
+
+/** A file the agent touched */
+export interface RunFile {
+  name: string;
+  path: string;
+  /** Its contents, or the part worth showing: opens when the name is pressed */
+  lines: readonly string[];
+}
+
+/** A file's name, as a link to it: ultramarine and monospaced, opening when pressed */
+export function RunFileLink({ file }: { file: RunFile }) {
+  return (
+    <Peek look="file" label={file.name} title={file.path}>
+      <div className="flex flex-col gap-2">
+        <span className="font-mono type-caption text-fg-subtle">{file.path}</span>
+        <pre className="rounded-control bg-surface-muted px-3 py-2 font-mono type-caption whitespace-pre-wrap text-fg">
+          {file.lines.join("\n")}
+        </pre>
+      </div>
+    </Peek>
+  );
+}
+
+/** The icon beside what a step did, as in Claude Code */
+const kindIcons = {
+  read: IconBookOpen,
+  edit: IconEdit,
+  run: IconTerminal,
+};
+
+/**
+ * A step that succeeded: an icon and what it did, to which file or with which command, and what
+ * came of it underneath. An edit can show how many lines changed and its first lines.
+ */
+export function RunStep({
+  kind,
+  icon,
+  verb,
+  file,
+  command,
+  result,
+  added,
+  removed,
+  preview = false,
+}: {
+  /** Picks the icon beside the verb: an open book, a pencil or a terminal */
+  kind?: keyof typeof kindIcons;
+  /** Your own icon, for any other kind of step, sized like the text */
+  icon?: ReactNode;
+  verb: string;
+  file?: RunFile;
+  command?: string;
+  result?: string;
+  added?: number;
+  removed?: number;
+  /** Show the file's first lines under the step, fading out, as VS Code does for an edit */
+  preview?: boolean;
+}) {
+  const copy = useInteractionCopy().run;
+  const changed = added !== undefined && removed !== undefined;
+  const Kind = kind ? kindIcons[kind] : undefined;
+  const glyph = icon ?? (Kind ? <Kind className="size-3.5" /> : null);
+  return (
+    <RunEntry dot="success">
+      {/* The icon has its own column; the name, file, result and preview line up beside it */}
+      <div className="flex gap-2.5">
+        {glyph ? (
+          <span aria-hidden="true" className="flex h-5 shrink-0 items-center text-fg-subtle">
+            {glyph}
+          </span>
+        ) : null}
+        <div className="flex min-w-0 flex-1 flex-col gap-1">
+          <div>
+            <span className="run-verb font-medium text-fg-emphasis">{verb}</span>{" "}
+            {file ? (
+              <RunFileLink file={file} />
+            ) : command ? (
+              <code className="font-mono text-fg">{command}</code>
+            ) : null}
+          </div>
+          {changed || result ? (
+            <p className="type-caption text-fg-subtle">
+              {changed ? (
+                <>
+                  <span aria-hidden="true">
+                    <span className="text-success">+{copy.number(added)}</span>{" "}
+                    <span className="text-error">−{copy.number(removed)}</span>
+                  </span>
+                  <span className="sr-only">
+                    {copy.lines(copy.number(added), copy.number(removed))}
+                  </span>
+                </>
+              ) : null}
+              {result}
+            </p>
+          ) : null}
+          {preview && file ? (
+            // The first lines, fading out; the file's name opens all of it
+            <div
+              aria-hidden="true"
+              className="mt-1 rounded-control border border-line-subtle bg-surface-muted px-3 py-2"
+            >
+              <pre className="run-preview-fade max-h-[3lh] overflow-hidden font-mono type-caption whitespace-pre-wrap text-fg">
+                {file.lines.join("\n")}
+              </pre>
+            </div>
+          ) : null}
+        </div>
+      </div>
+    </RunEntry>
+  );
+}
+
+/** A thought, such as "Thought for 12s": a smaller grey dot and quiet text */
+export function RunThought({ children }: { children: ReactNode }) {
+  return (
+    <RunEntry dot="thought">
+      <span className="text-fg-subtle">{children}</span>
+    </RunEntry>
+  );
+}
+
+/** The agent, in its own words */
+export function RunMessage({ children }: { children: ReactNode }) {
+  return (
+    <RunEntry dot="note">
+      {/* A div, not a p: the agent's words can hold a Peek, whose detail isn't phrasing */}
+      <div className="text-pretty text-fg">{children}</div>
+    </RunEntry>
+  );
+}
+
+/** What the agent is doing now, with the working matrix */
+export function RunWorking({ children }: { children: ReactNode }) {
+  return (
+    <RunEntry dot="working">
+      <span className="text-fg-emphasis">{children}</span>
+    </RunEntry>
+  );
+}

package/source/reusable/ui/index.ts

@@ -19,6 +19,7 @@ export { Avatar } from "../../components/avatar.js";
 export { Skeleton } from "../../components/skeleton.js";
 export { Spinner } from "../../components/spinner.js";
 export { ScrollArea } from "../../components/scroll-area.js";
+export { Peek } from "../../components/peek.js";
 export { ResponsiveOverlay } from "../../components/responsive-overlay.js";
 export { DateTimeField } from "../../components/date-time-field.js";