@superxd-studio/adptr 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superxd-studio/adptr",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "license": "MIT",
   "description": "ADPTR by SuperXD: React components and finished product flows for conversation, review and AI-assisted work, with every state designed.",
@@ -108,6 +108,7 @@
     "clsx": "^2.1.1",
     "tailwind-merge": "^3.7.0",
     "react-aria-components": "^1.21.1",
+    "react-aria": "3.52.1",
     "react-markdown": ">=10.0.0 <=10.1.0",
     "remark-gfm": ">=4.0.0 <=4.0.1",
     "@internationalized/date": "^3.12.4",

package/source/components/icons.tsx

@@ -136,6 +136,20 @@ export const IconEdit = createIcon(
   </>,
 );
 export const IconCheck = createIcon("Check", <path d="M20 6 9 17l-5-5" />);
+export const IconBookOpen = createIcon(
+  "BookOpen",
+  <>
+    <path d="M12 7v14" />
+    <path d="M3 18a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1h5a4 4 0 0 1 4 4 4 4 0 0 1 4-4h5a1 1 0 0 1 1 1v13a1 1 0 0 1-1 1h-6a3 3 0 0 0-3 3 3 3 0 0 0-3-3z" />
+  </>,
+);
+export const IconTerminal = createIcon(
+  "Terminal",
+  <>
+    <path d="M12 19h8" />
+    <path d="m4 17 6-6-6-6" />
+  </>,
+);
 
 export const IconX = createIcon(
   "X",

package/source/components/peek.tsx

@@ -0,0 +1,113 @@
+import { useEffect, useRef, useState, type ReactNode } from "react";
+import { mergeProps, useButton, useFocusRing, useHover } from "react-aria";
+import { Dialog, Popover } from "react-aria-components";
+import { PortalTheme } from "./ui/portal-theme.js";
+import { cn } from "../lib/cn.js";
+
+/** How long the pointer rests on a word before its detail peeks open, and lingers after */
+const OPEN_MS = 280;
+const CLOSE_MS = 160;
+
+/**
+ * A word in a sentence with more behind it, like an explorable explanation or the hover card
+ * behind an @mention. Resting the pointer on it peeks the detail open; pressing it (click,
+ * tap, Enter or Space) keeps it open as a small dialog, closed with Escape or by pressing
+ * elsewhere. The dotted underline is the only hint, so the sentence still reads as text.
+ *
+ * A file looks like a link, as in VS Code: ultramarine and monospaced, and it opens when pressed
+ * rather than when the pointer rests on it.
+ */
+export function Peek({
+  label,
+  title,
+  look = "word",
+  children,
+}: {
+  label: ReactNode;
+  /** What the detail is, for screen readers */
+  title: string;
+  look?: "word" | "file";
+  children: ReactNode | ((close: () => void) => ReactNode);
+}) {
+  const hovers = look === "word";
+  // A span, not a <button>, so a long phrase wraps with the sentence like ordinary text
+  const trigger = useRef<HTMLSpanElement>(null);
+  const timer = useRef<number | undefined>(undefined);
+  const [open, setOpen] = useState(false);
+  const [pinned, setPinned] = useState(false);
+  useEffect(() => () => window.clearTimeout(timer.current), []);
+  const later = (next: boolean, ms: number) => {
+    window.clearTimeout(timer.current);
+    timer.current = window.setTimeout(() => setOpen(next), ms);
+  };
+  const close = () => {
+    window.clearTimeout(timer.current);
+    setOpen(false);
+    setPinned(false);
+  };
+  const { buttonProps } = useButton(
+    {
+      elementType: "span",
+      "aria-expanded": open,
+      onPress: () => {
+        window.clearTimeout(timer.current);
+        if (pinned) return close();
+        setPinned(true);
+        setOpen(true);
+      },
+    },
+    trigger,
+  );
+  const { hoverProps, isHovered } = useHover({
+    onHoverStart: () => hovers && !pinned && later(true, OPEN_MS),
+    onHoverEnd: () => hovers && !pinned && later(false, CLOSE_MS),
+  });
+  const { focusProps, isFocusVisible } = useFocusRing();
+  return (
+    <PortalTheme>
+      {(theme) => (
+        <>
+          <span
+            ref={trigger}
+            {...mergeProps(buttonProps, hoverProps, focusProps)}
+            data-hovered={isHovered || undefined}
+            data-focus-visible={isFocusVisible || undefined}
+            className={cn(
+              "cursor-pointer rounded-cell wrap-anywhere outline-none data-focus-visible:focus-ring",
+              look === "word"
+                ? "font-medium text-fg-emphasis underline decoration-line-emphasis decoration-dotted decoration-[1.5px] underline-offset-[5px] transition-[text-decoration-color] duration-(--duration-snap) ease-snap data-hovered:decoration-fg-subtle"
+                : "font-mono text-done underline-offset-[3px] data-hovered:underline",
+            )}
+          >
+            {label}
+          </span>
+          <Popover
+            triggerRef={trigger}
+            isOpen={open}
+            onOpenChange={(next) => (next ? setOpen(true) : close())}
+            // A peek doesn't take focus or block the page; a pressed word opens a real dialog
+            isNonModal={!pinned}
+            placement="bottom start"
+            offset={8}
+            style={theme.style}
+            className={cn(
+              theme.className,
+              // Long details scroll inside the peek rather than running off the screen
+              "z-50 max-h-[min(24rem,60vh)] w-80 max-w-[calc(100vw-2rem)] origin-(--trigger-anchor-point) overflow-y-auto rounded-surface border border-line-subtle bg-surface p-4 wrap-anywhere text-fg shadow-popover outline-none data-entering:animate-pop-in data-exiting:animate-pop-out",
+            )}
+          >
+            <Dialog aria-label={title} className="outline-none">
+              {/* Moving the pointer into the detail keeps it open */}
+              <div
+                onPointerEnter={() => !pinned && window.clearTimeout(timer.current)}
+                onPointerLeave={() => !pinned && later(false, CLOSE_MS)}
+              >
+                {typeof children === "function" ? children(close) : children}
+              </div>
+            </Dialog>
+          </Popover>
+        </>
+      )}
+    </PortalTheme>
+  );
+}

package/source/components/thinking.tsx

@@ -5,9 +5,20 @@ import { cn } from "../lib/cn.js";
  * length (an AI preparing an answer). About the height of a line of text. Decorative: say
  * what's happening in words beside it.
  */
-export function Thinking({ className }: { className?: string }) {
+export function Thinking({
+  className,
+  tone = "brand",
+}: {
+  className?: string;
+  /** brand (ultramarine) while the system works; info (calm blue) while it waits on a person */
+  tone?: "brand" | "info";
+}) {
   return (
-    <span aria-hidden="true" className={cn("thinking-matrix", className)}>
+    <span
+      aria-hidden="true"
+      data-tone={tone === "info" ? "info" : undefined}
+      className={cn("thinking-matrix", className)}
+    >
       {Array.from({ length: 9 }, (_, i) => (
         <i key={i} />
       ))}

package/source/reusable/generative/index.tsx

@@ -13,6 +13,7 @@ import {
 import { renderGenerativeUI } from "@assistant-ui/react-generative-ui";
 import { Button } from "../../components/button.js";
 import { Callout } from "../../components/callout.js";
+import { IconArrowLeft } from "../../components/icons.js";
 import { Spinner } from "../../components/spinner.js";
 import { generativeCopy as defaultCopy, type GenerativeCopy } from "./copy.js";
 import { parseStructuredSpec, type StructuredSpec } from "./schema.js";
@@ -390,10 +391,11 @@ function ResponseView({
                 {!retainSteps ? (
                   <Button
                     size="sm"
-                    variant="ghost"
+                    variant="secondary"
                     className="self-start"
                     onPress={() => controller.reset()}
                   >
+                    <IconArrowLeft />
                     {copy.back}
                   </Button>
                 ) : null}
@@ -428,9 +430,19 @@ function ResponseView({
                     ))}
                   </dl>
                 ) : null}
-                <div className="flex flex-wrap gap-3">
+                {/* Back on the left, Confirm on the right */}
+                <div className="flex flex-wrap items-center gap-3">
+                  <Button
+                    variant="secondary"
+                    isDisabled={snapshot.stage !== "confirm"}
+                    onPress={() => controller.back()}
+                  >
+                    <IconArrowLeft />
+                    {copy.back}
+                  </Button>
                   <Button
                     variant="primary"
+                    className="ml-auto"
                     isDisabled={snapshot.stage !== "confirm"}
                     aria-busy={snapshot.stage !== "confirm"}
                     aria-label={
@@ -449,13 +461,6 @@ function ResponseView({
                         ? copy.working
                         : copy.confirm}
                   </Button>
-                  <Button
-                    variant="ghost"
-                    isDisabled={snapshot.stage !== "confirm"}
-                    onPress={() => controller.back()}
-                  >
-                    {copy.back}
-                  </Button>
                 </div>
                 {snapshot.stage !== "confirm" ? (
                   <p role="status" className="sr-only">

package/source/reusable/generative/vocabulary.tsx

@@ -820,8 +820,10 @@ function GeneratedButton({
               : "secondary"
       }
       className={cn(
-        "h-auto min-h-control-md max-w-full py-control-y wrap-anywhere whitespace-normal",
-        block && "w-full",
+        // Buttons fit their words and sit at the right end; a "block" button spans the width
+        // only on phones
+        "h-auto min-h-control-md max-w-full self-end py-control-y wrap-anywhere whitespace-normal",
+        block && "w-full sm:w-auto",
       )}
       isDisabled={
         blocked ||

package/source/reusable/interactions/context.tsx

@@ -32,6 +32,10 @@ export function InteractionProvider({
     agentStates: { ...parent.agentStates, ...copy.agentStates },
     artifactStates: { ...parent.artifactStates, ...copy.artifactStates },
     connection: { ...parent.connection, ...copy.connection },
+    gate: { ...parent.gate, ...copy.gate },
+    run: { ...parent.run, ...copy.run },
+    receipt: { ...parent.receipt, ...copy.receipt },
+    progress: { ...parent.progress, ...copy.progress },
   };
   return <CopyContext.Provider value={merged}>{children}</CopyContext.Provider>;
 }

package/source/reusable/interactions/copy.ts

@@ -114,4 +114,43 @@ export const interactionCopy = {
   noThreads: "No conversations in this view.",
   threadError: "Couldn’t complete that request. The current conversation is still here.",
   loading: "Loading",
+  /** The Decision Gate */
+  gate: {
+    review: "Review",
+    approve: "Approve once",
+    approving: "Approving",
+    decline: "Decline",
+    edit: "Edit before approving",
+    irreversible: "Can't be undone",
+    waiting: "Waiting for your approval",
+    changed: "Something changed while you were deciding",
+    reviewChange: "Review the change",
+    reconsider: "Reconsider",
+  },
+  /** The Action Receipt */
+  receipt: {
+    whatChanged: "What changed",
+    checking: "Checking what happened",
+    states: {
+      changed: "Changed",
+      "not-changed": "Not changed",
+      unknown: "Not known yet",
+      reverted: "Reverted",
+    },
+    minutesLeft: (minutes: number) => (minutes === 1 ? "1 min left" : `${minutes} min left`),
+    closed: "Undo has closed",
+  },
+  /** Agent task progress */
+  progress: {
+    showStages: "Show stages",
+    stagesDone: (done: number, total: number) => `${done} of ${total} stages`,
+    noAction: "No action needed",
+    review: "Review",
+    stageWords: { done: "done", now: "now", next: "to come" },
+  },
+  /** An agent's run */
+  run: {
+    number: (value: number) => new Intl.NumberFormat("en").format(value),
+    lines: (added: string, removed: string) => `${added} lines added, ${removed} removed`,
+  },
 } as const;

package/source/reusable/interactions/gate.tsx

@@ -0,0 +1,246 @@
+import { useId, useState, type ReactNode } from "react";
+import { Button } from "../../components/button.js";
+import { IconAlert, IconCheck, IconChevronDown, IconEdit, IconX } from "../../components/icons.js";
+import { Thinking } from "../../components/thinking.js";
+import { Tooltip } from "../../components/ui/navigation.js";
+import { cn } from "../../lib/cn.js";
+import { useInteractionCopy } from "./context.js";
+import { RunEntry, useInRun } from "./run.js";
+
+/** Where the request is: waiting for the person, being carried out, or settled */
+export type DecisionGateStatus = "waiting" | "approving" | "approved" | "declined";
+
+/**
+ * Text buttons whose words can wrap when text is very large or the space very narrow, between
+ * words rather than inside them
+ */
+const wraps = "h-auto min-h-control-sm whitespace-normal break-words py-1.5 text-center";
+
+export interface DecisionGateProps {
+  /** What the agent wants to do, in a few words. Closed, it's shortened to one line. */
+  title: string;
+  /** Approving can't be undone: a red mark beside the title, and a red tag when open */
+  irreversible?: boolean;
+  status?: DecisionGateStatus;
+  /** The title once approved, as a receipt */
+  approvedTitle?: string;
+  /** The title once declined */
+  declinedTitle?: string;
+  /** What will happen, in one sentence. Put details behind its words with Peek. */
+  children: ReactNode;
+  onApprove: () => void;
+  onDecline: () => void;
+  /** Shows the Edit button */
+  onEdit?: () => void;
+  /** The host's form for changing the request. While it's shown, it replaces the sentence. */
+  editor?: ReactNode;
+  /** Something changed while the person was deciding. Approval waits until they've seen it. */
+  changed?: ReactNode;
+  onReviewChange?: () => void;
+  /** Shows Reconsider once declined */
+  onReconsider?: () => void;
+  /** What the Approve button says while the request is carried out */
+  approvingLabel?: string;
+  defaultExpanded?: boolean;
+}
+
+/**
+ * The Decision Gate: what an agent wants to do, in one contained card. Closed, it's a tile with
+ * the pixel matrix, the title and Review. Review opens it like an accordion to the sentence and
+ * the decision. Nothing is approved from the closed card, so the person approves what they read.
+ *
+ * The interface asks; the product enforces. The host decides what each answer does and passes
+ * the status back.
+ */
+export function DecisionGate(props: DecisionGateProps) {
+  const card = <GateCard {...props} />;
+  if (!useInRun()) return card;
+  const status = props.status ?? "waiting";
+  return (
+    <RunEntry
+      card
+      dot={status === "approved" ? "success" : status === "declined" ? "note" : "waiting"}
+    >
+      {card}
+    </RunEntry>
+  );
+}
+
+function GateCard({
+  title,
+  irreversible = false,
+  status = "waiting",
+  approvedTitle,
+  declinedTitle,
+  children,
+  onApprove,
+  onDecline,
+  onEdit,
+  editor,
+  changed,
+  onReviewChange,
+  onReconsider,
+  approvingLabel,
+  defaultExpanded = false,
+}: DecisionGateProps) {
+  const copy = useInteractionCopy().gate;
+  const [open, setOpen] = useState(defaultExpanded);
+  const panelId = useId();
+  const approved = status === "approved";
+  const declined = status === "declined";
+  const settled = approved || declined;
+  const editing = editor !== undefined && editor !== null;
+  const expanded = !settled && (open || editing);
+  const deciding = status === "waiting" && !changed && !editing;
+  const heading = approved ? (approvedTitle ?? title) : declined ? (declinedTitle ?? title) : title;
+
+  return (
+    <div className="@container/gate overflow-hidden rounded-surface border border-line-subtle bg-surface-muted">
+      <p role="status" className="sr-only">
+        {approved
+          ? heading
+          : declined
+            ? heading
+            : status === "approving"
+              ? (approvingLabel ?? copy.approving)
+              : changed
+                ? copy.changed
+                : ""}
+      </p>
+      {/*
+       * Tile, title and Review in a row. With very large text in a narrow panel they stack.
+       */}
+      <div className="flex flex-wrap items-start gap-3 p-3">
+        {/* The matrix says it's waiting; screen readers hear it in words */}
+        <span
+          {...(settled ? { "aria-hidden": true } : { role: "img", "aria-label": copy.waiting })}
+          className={cn(
+            "flex size-10 shrink-0 items-center justify-center rounded-control border border-line-subtle bg-surface",
+            approved && "border-done bg-done text-on-done",
+          )}
+        >
+          {approved ? (
+            <IconCheck className="size-4 animate-done-in" />
+          ) : declined ? (
+            <IconX className="size-4 text-fg-subtle" />
+          ) : (
+            <Thinking tone="info" />
+          )}
+        </span>
+        {/*
+         * Closed, the card is just its title, on one line, ending in "…" if it's longer, and a
+         * red mark if it can't be undone. Review opens the title in full, with the rest. Screen
+         * readers always hear all of it.
+         */}
+        <div className="flex min-h-10 min-w-0 flex-1 basis-24 items-center gap-1.5">
+          <span
+            className={cn(
+              "min-w-0 type-label text-fg-emphasis",
+              expanded ? "text-pretty wrap-anywhere" : "truncate",
+            )}
+          >
+            {heading}
+          </span>
+          {irreversible && !settled && !expanded ? (
+            <span role="img" aria-label={copy.irreversible} className="flex shrink-0">
+              <IconAlert className="size-4 text-error" />
+            </span>
+          ) : null}
+        </div>
+        <span className="ml-auto flex min-h-10 shrink-0 items-center">
+          {settled ? (
+            declined && onReconsider ? (
+              <Button size="sm" className={wraps} onPress={onReconsider}>
+                {copy.reconsider}
+              </Button>
+            ) : null
+          ) : (
+            <Button
+              size="sm"
+              className={cn("group/trigger", wraps)}
+              aria-label={copy.review}
+              aria-expanded={expanded}
+              aria-controls={panelId}
+              isDisabled={editing}
+              onPress={() => setOpen((value) => !value)}
+            >
+              {/* In a narrow space, just the chevron */}
+              <span className="@max-sm/gate:hidden">{copy.review}</span>
+              <IconChevronDown className="transition-[rotate] duration-(--duration-settle) ease-settle group-aria-expanded/trigger:rotate-180 motion-reduce:transition-none" />
+            </Button>
+          )}
+        </span>
+      </div>
+
+      {changed && !settled ? (
+        <div className="flex flex-col gap-3 border-t border-line-subtle px-4 py-3">
+          <p className="type-body text-pretty text-attention">{changed}</p>
+          {onReviewChange ? (
+            <div className="flex justify-end">
+              <Button size="sm" className={wraps} onPress={onReviewChange}>
+                {copy.reviewChange}
+              </Button>
+            </div>
+          ) : null}
+        </div>
+      ) : null}
+
+      {expanded ? (
+        <div
+          id={panelId}
+          className="flex animate-reveal-in flex-col gap-4 border-t border-line-subtle bg-surface p-4"
+        >
+          {editing ? (
+            editor
+          ) : (
+            <>
+              {irreversible ? (
+                <span className="inline-flex items-center gap-1 self-start rounded-pill border border-error-line bg-error-subtle px-2 py-0.5 type-caption break-words text-error">
+                  <IconAlert className="size-3.5 shrink-0" />
+                  {copy.irreversible}
+                </span>
+              ) : null}
+              <div className="type-body text-pretty wrap-anywhere text-fg">{children}</div>
+              {/* The decision sits at the right end, Approve once furthest right */}
+              <div className="flex flex-wrap items-center justify-end gap-2">
+                {onEdit ? (
+                  <Tooltip content={copy.edit}>
+                    <Button
+                      variant="secondary"
+                      size="icon-sm"
+                      aria-label={copy.edit}
+                      onPress={onEdit}
+                      isDisabled={!deciding}
+                    >
+                      <IconEdit />
+                    </Button>
+                  </Tooltip>
+                ) : null}
+                <Button
+                  variant="secondary"
+                  size="sm"
+                  className={cn("text-error", wraps)}
+                  onPress={onDecline}
+                  isDisabled={!deciding}
+                >
+                  {copy.decline}
+                </Button>
+                <Button
+                  variant="primary"
+                  size="sm"
+                  className={wraps}
+                  onPress={onApprove}
+                  isDisabled={Boolean(changed)}
+                  isPending={status === "approving"}
+                  pendingLabel={approvingLabel ?? copy.approving}
+                >
+                  {copy.approve}
+                </Button>
+              </div>
+            </>
+          )}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/source/reusable/interactions/index.ts

@@ -4,6 +4,20 @@ export * from "./feedback.js";
 export * from "./threads.js";
 export * from "./presentation.js";
 export * from "./web.js";
+export { RunTimeline, RunStep, RunThought, RunMessage, RunWorking } from "./run.js";
+export type { RunFile } from "./run.js";
+export { DecisionGate } from "./gate.js";
+export type { DecisionGateProps, DecisionGateStatus } from "./gate.js";
+export { ActionReceipt } from "./receipt.js";
+export type {
+  ActionReceiptProps,
+  ReceiptAction,
+  ReceiptChange,
+  ReceiptChangeState,
+  ReceiptOutcome,
+} from "./receipt.js";
+export { TaskProgress } from "./progress.js";
+export type { TaskProgressMove, TaskProgressProps, TaskProgressStatus } from "./progress.js";
 export { interactionCopy } from "./copy.js";
 export { jsonSchema } from "./store.js";
 

package/source/reusable/interactions/presentation.tsx

@@ -333,7 +333,10 @@ export function ComposerTools({
         />
       )}{" "}
       {commands.length > 0 && onCommand && (
-        <Menu label={copy.commands} items={commands} onAction={onCommand} />
+        // In a column, a wrapper lets the Commands button fit its words
+        <div>
+          <Menu label={copy.commands} items={commands} onAction={onCommand} />
+        </div>
       )}
     </div>
   );