@robota-sdk/agent-ui-web 0.0.0-stage → 3.0.0-beta.101

package/src/components/Dialog.tsx

@@ -0,0 +1,230 @@
+'use client';
+
+import React, { useEffect, useId, useRef } from 'react';
+
+/**
+ * The shared modal-shell primitive (#3282 §4a, coordinated with #3282 §2's model/mode controls,
+ * which also need a confirmation dialog). Whichever of the two lands first defines this file; the
+ * other rebases onto it rather than shipping a second copy.
+ *
+ * `role="dialog"` (or `"alertdialog"`, see `role` below), `aria-modal`, a labelled title, focus moved
+ * inside on open, a focus trap while open, Esc to close, and focus restored to whatever had it before
+ * the dialog opened. A backdrop click closes the dialog UNLESS `destructive` is set — a destructive
+ * dialog (e.g. "Remove this rule?") is dismissed only by an explicit choice, never an accidental
+ * outside click.
+ */
+export interface IDialogProps {
+  open: boolean;
+  /** Called on Esc, a backdrop click (non-destructive only), or an explicit close control. */
+  onClose: () => void;
+  title: string;
+  children: React.ReactNode;
+  /** Disables backdrop-click-to-close for a dialog whose only correct exits are explicit buttons. */
+  destructive?: boolean;
+  /** Overrides the panel's own classes; the backdrop/overlay classes are never overridden. */
+  panelClassName?: string;
+  /** Id of an element describing the dialog, wired to `aria-describedby`. */
+  describedById?: string;
+  /**
+   * Overrides what focus returns to when the dialog closes (#3289 §1). Default behavior captures
+   * `document.activeElement` when the dialog opens — which fails for a caller whose opener element
+   * is removed from the DOM in the SAME update that opens this dialog (e.g. a menu item whose menu
+   * closes as this dialog opens): by the time this dialog's open-effect runs, the browser has already
+   * moved focus to `document.body`. Such a caller passes the stable element focus should return to.
+   */
+  restoreFocusTo?: HTMLElement | null;
+  /**
+   * #3282 §4e: `'alertdialog'` for a dialog that interrupts to demand a decision before anything else
+   * can happen (a destructive confirmation) — WAI-ARIA's distinction from a dialog the user can set
+   * aside. Default `'dialog'`.
+   */
+  role?: 'dialog' | 'alertdialog';
+}
+
+const FOCUSABLE_SELECTOR =
+  'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+/**
+ * Every currently-open `Dialog`, oldest first. All instances share one `document` keydown listener
+ * target, so listeners fire in REGISTRATION order regardless of nesting — the outer dialog's
+ * listener (registered first, when it opened) always runs before a nested `ConfirmDialog`'s
+ * (registered later, when the user triggered it). `stopImmediatePropagation` on the outer listener
+ * therefore cannot defer to the inner one; it fires first and would win. Instead, each instance
+ * checks this stack and only acts when it is the LAST (topmost) entry — an outer dialog that isn't
+ * topmost no-ops on the keydown and lets the still-registered inner listener act.
+ */
+let openDialogStack: symbol[] = [];
+
+export function Dialog({
+  open,
+  onClose,
+  title,
+  children,
+  destructive = false,
+  panelClassName,
+  describedById,
+  restoreFocusTo,
+  role = 'dialog',
+}: IDialogProps): React.ReactElement | null {
+  const panelRef = useRef<HTMLDivElement>(null);
+  const previouslyFocused = useRef<HTMLElement | null>(null);
+  const titleId = useId();
+  const dialogToken = useRef<symbol>(Symbol('dialog'));
+
+  // Move focus in on open, and restore it to the opener once the dialog goes away. `restoreFocusTo`,
+  // given, overrides the ambient `document.activeElement` this would otherwise capture.
+  useEffect(() => {
+    if (!open) return undefined;
+    previouslyFocused.current = restoreFocusTo ?? (document.activeElement as HTMLElement | null);
+    const panel = panelRef.current;
+    const firstFocusable = panel?.querySelector<HTMLElement>(FOCUSABLE_SELECTOR);
+    (firstFocusable ?? panel)?.focus();
+    return () => {
+      previouslyFocused.current?.focus?.();
+    };
+  }, [open]);
+
+  // Tracks this dialog's membership on the shared open-dialog stack. Kept separate from the
+  // keydown-listener effect below (which also depends on `onClose`) so that a caller passing a
+  // fresh `onClose` identity on every render can never re-push this dialog and wrongly promote it
+  // to topmost — membership changes only when `open` itself flips.
+  useEffect(() => {
+    if (!open) return undefined;
+    const token = dialogToken.current;
+    openDialogStack.push(token);
+    return () => {
+      openDialogStack = openDialogStack.filter((entry) => entry !== token);
+    };
+  }, [open]);
+
+  // Esc closes; Tab traps focus inside the panel while it is open. Both no-op unless this dialog
+  // is the topmost open one (see `openDialogStack` above).
+  useEffect(() => {
+    if (!open) return undefined;
+    const token = dialogToken.current;
+    const isTopmost = (): boolean => openDialogStack[openDialogStack.length - 1] === token;
+    const onKeyDown = (event: KeyboardEvent): void => {
+      if (!isTopmost()) return;
+      if (event.key === 'Escape') {
+        event.stopImmediatePropagation();
+        onClose();
+        return;
+      }
+      if (event.key !== 'Tab') return;
+      const panel = panelRef.current;
+      if (!panel) return;
+      const focusable = Array.from(panel.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR));
+      if (focusable.length === 0) return;
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+      if (event.shiftKey && document.activeElement === first) {
+        event.preventDefault();
+        last?.focus();
+      } else if (!event.shiftKey && document.activeElement === last) {
+        event.preventDefault();
+        first?.focus();
+      }
+    };
+    document.addEventListener('keydown', onKeyDown, true);
+    return () => document.removeEventListener('keydown', onKeyDown, true);
+  }, [open, onClose]);
+
+  if (!open) return null;
+
+  return (
+    <div
+      className="agent-ui fixed inset-0 z-50 flex items-center justify-center bg-black/55 p-4 backdrop-blur-[2px]"
+      onMouseDown={(event) => {
+        if (destructive) return;
+        if (event.target === event.currentTarget) onClose();
+      }}
+    >
+      <div
+        ref={panelRef}
+        role={role}
+        aria-modal="true"
+        aria-labelledby={titleId}
+        {...(describedById ? { 'aria-describedby': describedById } : {})}
+        tabIndex={-1}
+        className={
+          panelClassName ??
+          'flex max-h-[85vh] w-full max-w-lg flex-col rounded-2xl bg-card text-card-foreground shadow-[0_8px_30px_-12px_rgb(0_0_0/0.45)] focus:outline-none'
+        }
+      >
+        <h2 id={titleId} className="sr-only">
+          {title}
+        </h2>
+        {children}
+      </div>
+    </div>
+  );
+}
+
+const BUTTON =
+  'inline-flex items-center gap-2 rounded-lg px-3.5 py-1.5 text-[14px] font-medium transition-colors';
+const PRIMARY_BUTTON = `${BUTTON} bg-primary text-primary-foreground hover:opacity-90`;
+const SECONDARY_BUTTON = `${BUTTON} bg-raised text-foreground hover:bg-hover`;
+const DESTRUCTIVE_BUTTON = `${BUTTON} bg-destructive text-destructive-foreground hover:opacity-90`;
+
+export interface IConfirmDialogProps {
+  open: boolean;
+  title: string;
+  body: React.ReactNode;
+  confirmLabel: string;
+  cancelLabel?: string;
+  /** Styles the confirm button as destructive; the dialog itself also stops closing on a backdrop click. */
+  destructive?: boolean;
+  onConfirm: () => void;
+  onCancel: () => void;
+  /** Forwarded to `Dialog` — see its doc comment. */
+  restoreFocusTo?: HTMLElement | null;
+}
+
+/**
+ * A title, a body, Cancel focused by default, and a confirm button that can be styled destructive.
+ * #3282 §4e: `destructive` also picks the dialog's ARIA role — `"alertdialog"` when it is (an action
+ * that demands a decision before anything else, e.g. deleting a session), `"dialog"` otherwise.
+ */
+export function ConfirmDialog({
+  open,
+  title,
+  body,
+  confirmLabel,
+  cancelLabel = 'Cancel',
+  destructive = false,
+  onConfirm,
+  onCancel,
+  restoreFocusTo,
+}: IConfirmDialogProps): React.ReactElement | null {
+  const bodyId = useId();
+  return (
+    <Dialog
+      open={open}
+      onClose={onCancel}
+      title={title}
+      destructive={destructive}
+      role={destructive ? 'alertdialog' : 'dialog'}
+      describedById={bodyId}
+      restoreFocusTo={restoreFocusTo}
+      panelClassName="w-full max-w-sm rounded-2xl bg-card p-5 text-card-foreground shadow-[0_8px_30px_-12px_rgb(0_0_0/0.45)] focus:outline-none"
+    >
+      <p className="text-[15px] font-medium text-foreground">{title}</p>
+      <p id={bodyId} className="mt-2 text-[13.5px] text-muted-foreground">
+        {body}
+      </p>
+      <div className="mt-5 flex justify-end gap-2">
+        {/* Cancel is the FIRST focusable element in the panel, so Dialog's open-focus lands here. */}
+        <button type="button" className={SECONDARY_BUTTON} onClick={onCancel}>
+          {cancelLabel}
+        </button>
+        <button
+          type="button"
+          className={destructive ? DESTRUCTIVE_BUTTON : PRIMARY_BUTTON}
+          onClick={onConfirm}
+        >
+          {confirmLabel}
+        </button>
+      </div>
+    </Dialog>
+  );
+}

package/src/components/DiffLines.tsx

@@ -0,0 +1,81 @@
+'use client';
+
+import React, { useState } from 'react';
+
+import type { IDiffLine } from '@robota-sdk/agent-interface-session';
+
+/**
+ * #3288: renders a unified diff already built server-side (the ONE diff builder, in
+ * `interactive-session-streaming.ts`) — a tool row's expanded result and the Edit/Write permission
+ * prompt both show the SAME diff through this, so approving a change and reviewing it afterwards
+ * look identical. This component never computes a diff itself, only displays one.
+ */
+
+const DIFF_LINE_STYLE: Record<IDiffLine['type'], string> = {
+  add: 'bg-accent/10 text-foreground',
+  remove: 'bg-destructive/10 text-foreground',
+  context: 'text-muted-foreground',
+  hunk: 'text-subtle',
+};
+const DIFF_LINE_PREFIX: Record<IDiffLine['type'], string> = {
+  add: '+ ',
+  remove: '- ',
+  context: '  ',
+  hunk: '',
+};
+
+// #3288 review SHOULD 3: the server already caps each diff side at 500 lines — this is a second,
+// independent fold so a diff that size never renders into the DOM at once either.
+const DIFF_FOLD_LINES = 40;
+const DIFF_EXPANDED_CAP_LINES = 500;
+
+function DiffLine({ line }: { line: IDiffLine }): React.ReactElement {
+  return (
+    <div className={`whitespace-pre ${DIFF_LINE_STYLE[line.type]}`}>
+      {`${DIFF_LINE_PREFIX[line.type]}${line.text}`}
+    </div>
+  );
+}
+
+export function DiffLines({ diffLines }: { diffLines: readonly IDiffLine[] }): React.ReactElement {
+  const [open, setOpen] = useState(false);
+  if (diffLines.length <= DIFF_FOLD_LINES) {
+    return (
+      <pre className="overflow-x-auto rounded-lg bg-sidebar px-3 py-2 font-mono text-[12.5px] leading-relaxed">
+        {diffLines.map((line, index) => (
+          // A diff's line order IS its identity — index is a stable, correct key here.
+          <DiffLine key={index} line={line} />
+        ))}
+      </pre>
+    );
+  }
+
+  const capped = diffLines.slice(0, DIFF_EXPANDED_CAP_LINES);
+  const shown = open ? capped : diffLines.slice(0, DIFF_FOLD_LINES);
+  // Expanding reveals up to DIFF_EXPANDED_CAP_LINES, not the whole diff — the label must promise
+  // only what "Show more" actually shows, or a capped Edit (each side capped at 500 on the server)
+  // can claim more lines than clicking through ever produces.
+  const revealedByExpanding = Math.min(diffLines.length, DIFF_EXPANDED_CAP_LINES) - DIFF_FOLD_LINES;
+  return (
+    <div className="flex flex-col gap-1">
+      <pre className="overflow-x-auto rounded-lg bg-sidebar px-3 py-2 font-mono text-[12.5px] leading-relaxed">
+        {shown.map((line, index) => (
+          // A diff's line order IS its identity — index is a stable, correct key here.
+          <DiffLine key={index} line={line} />
+        ))}
+      </pre>
+      {open && diffLines.length > DIFF_EXPANDED_CAP_LINES && (
+        <p className="text-[12px] text-subtle">
+          {diffLines.length - DIFF_EXPANDED_CAP_LINES} more lines not shown
+        </p>
+      )}
+      <button
+        type="button"
+        onClick={() => setOpen((value) => !value)}
+        className="self-start text-[12.5px] text-accent hover:underline"
+      >
+        {open ? 'Show less' : `Show more (${revealedByExpanding} more lines)`}
+      </button>
+    </div>
+  );
+}

package/src/components/ExecutionDetailSheet.tsx

@@ -0,0 +1,142 @@
+import { X } from 'lucide-react';
+import React from 'react';
+
+import { describeExecutionEntryStatus } from '../execution-entry-status.js';
+
+import type { TExecutionDetailStatus } from '../hooks/use-execution-detail.js';
+import type {
+  IExecutionDetailRecord,
+  IExecutionWorkspaceEntry,
+} from '@robota-sdk/agent-interface-execution';
+
+const STATUS_TAG_TONE: Record<string, string> = {
+  warning: 'bg-warning/15 text-warning',
+  destructive: 'bg-destructive/12 text-destructive',
+  muted: 'bg-subtle/15 text-subtle',
+};
+
+const RECORD_KIND_LABEL: Record<IExecutionDetailRecord['kind'], string> = {
+  message: '',
+  tool_activity: 'Tool',
+  process_output: 'Output',
+  progress: 'Progress',
+  result: 'Result',
+  error: 'Error',
+  group_summary: 'Summary',
+};
+
+/**
+ * #3288 §1: opening an Agents panel entry — status, what it was asked (one line, from its
+ * headline), its transcript so far (paginated via `onLoadMore`) and, once it has one, its result.
+ * `entry === null` renders nothing; the caller owns showing/hiding this over the panel.
+ */
+export function ExecutionDetailSheet({
+  entry,
+  status,
+  records,
+  error,
+  complete,
+  onClose,
+  onLoadMore,
+  onStop,
+}: {
+  entry: IExecutionWorkspaceEntry | null;
+  status: TExecutionDetailStatus;
+  records: readonly IExecutionDetailRecord[];
+  error: string | null;
+  complete: boolean;
+  onClose: () => void;
+  onLoadMore: () => void;
+  onStop?: () => void;
+}): React.ReactElement | null {
+  if (!entry) return null;
+  const described = describeExecutionEntryStatus(entry);
+  const canStop = onStop !== undefined && entry.controls.includes('cancel');
+  const askedLine = entry.headline?.text ?? entry.preview;
+
+  return (
+    <div
+      role="dialog"
+      aria-label={entry.title}
+      onKeyDown={(event) => {
+        if (event.key === 'Escape') {
+          event.preventDefault();
+          onClose();
+        }
+      }}
+      className="agent-ui absolute inset-y-0 right-0 z-30 flex w-96 flex-col overflow-hidden border-l border-subtle/20 bg-background shadow-2xl shadow-black/40"
+    >
+      <div className="flex flex-shrink-0 items-center gap-2 border-b border-subtle/15 px-4 py-3">
+        <span className="min-w-0 flex-1 truncate text-[14px] font-medium text-foreground">
+          {entry.title}
+        </span>
+        {described && (
+          <span
+            className={`flex-shrink-0 rounded-md px-1.5 py-px text-[12px] ${STATUS_TAG_TONE[described.tone]}`}
+          >
+            {described.label}
+          </span>
+        )}
+        {canStop && (
+          <button
+            type="button"
+            aria-label={`Stop ${entry.title}`}
+            onClick={onStop}
+            className="flex-shrink-0 rounded-md px-1.5 py-px text-[12px] text-subtle hover:bg-destructive/10 hover:text-destructive"
+          >
+            Stop
+          </button>
+        )}
+        <button
+          type="button"
+          aria-label="Close"
+          aria-keyshortcuts="Escape"
+          onClick={onClose}
+          className="flex-shrink-0 rounded-md p-1 text-subtle hover:bg-card hover:text-foreground"
+        >
+          <X size={16} strokeWidth={1.9} aria-hidden="true" />
+        </button>
+      </div>
+
+      {askedLine && (
+        <p className="flex-shrink-0 border-b border-subtle/15 px-4 py-2.5 text-[13px] leading-snug text-muted-foreground">
+          {askedLine}
+        </p>
+      )}
+      {entry.deniedToolCalls !== undefined && entry.deniedToolCalls > 0 && (
+        <p className="flex-shrink-0 px-4 pt-2 text-[12px] text-warning">
+          {entry.deniedToolCalls} tool {entry.deniedToolCalls === 1 ? 'call was' : 'calls were'} refused.
+        </p>
+      )}
+
+      <div className="flex-1 space-y-2 overflow-y-auto px-4 py-3">
+        {records.map((record) => (
+          <div key={record.id} className="text-[13px] leading-relaxed text-foreground">
+            {RECORD_KIND_LABEL[record.kind] && (
+              <span className="mr-1.5 text-[11px] font-medium uppercase tracking-wide text-subtle">
+                {RECORD_KIND_LABEL[record.kind]}
+              </span>
+            )}
+            <span className="whitespace-pre-wrap break-words">{record.text}</span>
+          </div>
+        ))}
+        {status === 'loading' && records.length === 0 && (
+          <p className="text-[13px] text-subtle">Loading…</p>
+        )}
+        {error && <p className="text-[13px] text-destructive">{error}</p>}
+        {!complete && status !== 'loading' && (
+          <button
+            type="button"
+            onClick={onLoadMore}
+            className="text-[12px] text-subtle underline hover:text-foreground"
+          >
+            Load more
+          </button>
+        )}
+        {!complete && status === 'loading' && records.length > 0 && (
+          <p className="text-[12px] text-subtle">Loading more…</p>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/components/HelpSheet.tsx

@@ -0,0 +1,104 @@
+'use client';
+
+import { X } from 'lucide-react';
+
+import { commandMenuFor } from '../hooks/command-menu.js';
+import { Dialog } from './Dialog.js';
+
+import type { TCommandCatalog } from '../hooks/session-client-types.js';
+
+/** One keyboard shortcut this surface answers — #3282 §4e. */
+interface IShortcut {
+  readonly keys: string;
+  readonly description: string;
+}
+
+const SHORTCUTS: readonly IShortcut[] = [
+  { keys: '⌘,', description: 'Open Settings' },
+  { keys: 'Esc', description: 'Close a dialog or menu, or stop the current run' },
+  { keys: 'Shift+Tab', description: 'Answer a pending question with the keyboard' },
+  { keys: 'Enter', description: 'Send the message' },
+  { keys: 'Shift+Enter', description: 'Start a new line' },
+];
+
+/**
+ * The GUI's Help sheet (#3282 §4e), a `Dialog` opened by `/help` — client-only: `useSessionClient.ts`'s
+ * `send` catches `/help` before it ever reaches the session and opens this instead, so there is no
+ * round trip and nothing terminal-style to replace it with. It lists the same commands and skills the
+ * `/` menu offers (`commandMenuFor`, unfiltered by any query — an excluded command has no row here
+ * either, exactly like the menu), grouped the same way, plus the keyboard shortcuts this surface
+ * answers. The TUI keeps its own text `/help` output; this sheet is the GUI's alone.
+ */
+export function HelpSheet({
+  open,
+  onClose,
+  catalog,
+}: {
+  open: boolean;
+  onClose: () => void;
+  catalog: TCommandCatalog | null;
+}): React.ReactElement | null {
+  const items = commandMenuFor(catalog, '/') ?? [];
+  const commands = items.filter((item) => item.kind === 'command');
+  const skills = items.filter((item) => item.kind === 'skill');
+
+  return (
+    <Dialog
+      open={open}
+      onClose={onClose}
+      title="Help"
+      panelClassName="flex h-[min(600px,85vh)] w-full max-w-lg flex-col overflow-hidden rounded-2xl bg-card text-card-foreground shadow-[0_8px_30px_-12px_rgb(0_0_0/0.45)] focus:outline-none"
+    >
+      <div className="flex h-12 flex-shrink-0 items-center gap-1 border-b border-border px-3">
+        <h2 className="px-1.5 text-[15px] font-semibold text-foreground">Help</h2>
+        <button
+          type="button"
+          aria-label="Close Help"
+          onClick={onClose}
+          className="ml-auto rounded-md p-1.5 text-muted-foreground hover:bg-hover hover:text-foreground"
+        >
+          <X size={17} strokeWidth={1.75} />
+        </button>
+      </div>
+
+      <div className="min-h-0 flex-1 overflow-y-auto px-5 py-4">
+        <section aria-label="Shortcuts">
+          <h3 className="text-[11px] font-semibold uppercase tracking-wide text-subtle">Shortcuts</h3>
+          <dl className="mt-2 mb-5 space-y-1.5">
+            {SHORTCUTS.map((shortcut) => (
+              <div key={shortcut.keys} className="flex items-baseline gap-3 text-[13.5px]">
+                <dt className="w-24 flex-shrink-0 font-mono text-foreground">{shortcut.keys}</dt>
+                <dd className="min-w-0 flex-1 text-muted-foreground">{shortcut.description}</dd>
+              </div>
+            ))}
+          </dl>
+        </section>
+
+        <CommandGroup label="Commands" items={commands} />
+        {skills.length > 0 && <CommandGroup label="Skills" items={skills} />}
+      </div>
+    </Dialog>
+  );
+}
+
+function CommandGroup({
+  label,
+  items,
+}: {
+  label: 'Commands' | 'Skills';
+  items: readonly { name: string; description: string }[];
+}): React.ReactElement {
+  return (
+    <section aria-label={label} className="mb-5 last:mb-0">
+      <h3 className="text-[11px] font-semibold uppercase tracking-wide text-subtle">{label}</h3>
+      <ul className="mt-2 space-y-1.5">
+        {items.map((item) => (
+          <li key={item.name} className="flex items-baseline gap-3 text-[13.5px]">
+            <span className="w-24 flex-shrink-0 truncate font-mono text-foreground">/{item.name}</span>
+            <span className="min-w-0 flex-1 text-muted-foreground">{item.description}</span>
+          </li>
+        ))}
+      </ul>
+    </section>
+  );
+}