@tai42/studio-sdk 0.2.0

package/src/components/confirm-dialog.tsx

@@ -0,0 +1,77 @@
+/**
+ * `ConfirmDialog` — a modal that asks the operator to confirm an action and then
+ * runs it. It owns the scaffolding every confirm shares: a Cancel button, the
+ * confirm button (showing a pending Spinner while the action runs and disabled
+ * meanwhile), and a loud `ErrorState` when the action fails. The caller supplies
+ * the prompt as `children` and drives the action through `onConfirm` /
+ * `isPending` / `error`.
+ *
+ * Mount it only while the confirmation is active; any close gesture — Cancel,
+ * Escape, the overlay — calls `onClose`. The confirm button is destructive
+ * (`danger`) by default; pass `confirmVariant` for a non-destructive confirm.
+ *
+ * The footer is the design system's `tai-dialog-actions` row, so every confirm
+ * across Studio lands its buttons in the same place.
+ */
+import type { ReactNode } from 'react';
+
+import { Dialog } from './dialog';
+import { Button, ErrorState, Spinner } from './primitives';
+import { errorMessage } from '../errors';
+
+export interface ConfirmDialogProps {
+  readonly title: string;
+  /** The confirm button's resting label (e.g. `Delete scope`). */
+  readonly confirmLabel: string;
+  /** The Spinner's accessible label while the action runs (e.g. `Deleting`). */
+  readonly pendingLabel: string;
+  readonly onConfirm: () => void;
+  readonly onClose: () => void;
+  readonly isPending: boolean;
+  /**
+   * The failed action's error, rendered loudly; omit/`null` while there is none.
+   *
+   * A thrown `Error` or the message on its own — `Field`'s `error` is a plain
+   * string, and the two props sit side by side on a form, so this one accepts
+   * that spelling too rather than making one surface's `error` unassignable to
+   * the other's.
+   */
+  readonly error?: Error | string | null;
+  readonly confirmVariant?: 'primary' | 'danger';
+  /** The prompt body — what the operator is confirming. */
+  readonly children: ReactNode;
+}
+
+export function ConfirmDialog({
+  title,
+  confirmLabel,
+  pendingLabel,
+  onConfirm,
+  onClose,
+  isPending,
+  error,
+  confirmVariant = 'danger',
+  children,
+}: ConfirmDialogProps): ReactNode {
+  return (
+    <Dialog
+      title={title}
+      open
+      onOpenChange={(next) => {
+        if (!next) onClose();
+      }}
+    >
+      {children}
+      {error != null ? <ErrorState message={errorMessage(error)} /> : null}
+      <div className="tai-dialog-actions">
+        <Button type="button" onClick={onClose}>
+          Cancel
+        </Button>
+        <Button type="button" variant={confirmVariant} disabled={isPending} onClick={onConfirm}>
+          {isPending ? <Spinner label={pendingLabel} /> : null}
+          {confirmLabel}
+        </Button>
+      </div>
+    </Dialog>
+  );
+}

package/src/components/control-styles.ts

@@ -0,0 +1,14 @@
+/**
+ * The design-system class each form control wears. The 36 px geometry, the
+ * boundary, the placeholder, and the hover/disabled/invalid states all live in
+ * `components.css` under these names — this module is the single place a
+ * control names the class, so no control re-derives that geometry inline.
+ */
+export const INPUT_CLASS = 'tai-input';
+export const TEXTAREA_CLASS = 'tai-textarea';
+export const SELECT_TRIGGER_CLASS = 'tai-select-trigger';
+
+/** A control's class plus the caller's, which sorts last so it can override. */
+export function controlClassName(base: string, className: string | undefined): string {
+  return className === undefined ? base : `${base} ${className}`;
+}

package/src/components/copy-field.tsx

@@ -0,0 +1,178 @@
+/**
+ * `CopyField` — a show-once box for a freshly-minted secret (an API key or a
+ * minted backup key). It renders the value in a monospace, break-all,
+ * select-all box beside a copy button that writes the value to the clipboard and
+ * shows a transient "Copied" affordance. It is PRESENTATIONAL: the caller owns
+ * the value; this component fetches nothing and never re-reads the secret.
+ *
+ * The button holds BOTH states stacked in one grid cell, so the widest of them
+ * sets the width once and the flip never reflows the row. Only the active state
+ * is exposed to assistive tech, and that state's own words are the button's
+ * accessible name: a constant `aria-label` would leave a button reading "Copied"
+ * named "Copy", which fails WCAG 2.5.3 (Label in Name) and leaves a voice-control
+ * user naming a control they cannot see. The polite live region beside the button
+ * is what actually announces the flip.
+ *
+ * A clipboard write can FAIL — a permissions policy blocks it, or the page is
+ * not in a secure context, where `navigator.clipboard` does not exist at all.
+ * Either way the value is a secret shown once, so the failure is rendered as a
+ * visible `role="alert"` telling the reader to copy it by hand: throwing it at
+ * the console would leave the button looking inert and the secret unrecoverable.
+ *
+ * SAFETY: the value and caption render as TEXT (React escapes them) — never an
+ * HTML sink. The value is never logged, and neither is a failure — the alert
+ * names the reason, never the value. Pinned by a test.
+ */
+import { useEffect, useRef, useState } from 'react';
+import type { CSSProperties } from 'react';
+
+import { CheckIcon, CopyIcon, XCircleIcon } from './icons';
+
+export interface CopyFieldProps {
+  readonly value: string;
+  readonly caption?: string;
+  readonly idPrefix?: string;
+  readonly label?: string;
+}
+
+const COPIED_RESET_MS = 2000;
+
+/** The button's two faces. Whichever is exposed is also its accessible name. */
+const COPY_LABEL = 'Copy';
+const COPIED_LABEL = 'Copied';
+
+/** Announced once, and worded so it is never mistaken for the visible label. */
+const COPIED_ANNOUNCEMENT = 'Copied to clipboard';
+
+/**
+ * `lib.dom` declares `navigator.clipboard` as always present, but the platform
+ * exposes it only in a SECURE CONTEXT — over plain http it is not there at all.
+ * Reading the navigator through this shape admits the absence the DOM types deny,
+ * so the guard below is a real check rather than a cast around one.
+ */
+interface MaybeClipboard {
+  readonly clipboard?: Clipboard;
+}
+
+/** The clipboard this browser actually offers, or `undefined` when it offers none. */
+function clipboardOf(host: MaybeClipboard): Clipboard | undefined {
+  return host.clipboard;
+}
+
+/** Shown when the browser offers no clipboard at all (any non-secure context). */
+const NO_CLIPBOARD =
+  'This browser will not write to the clipboard here. Select the value above and copy it.';
+
+/** Shown when the write is offered and refused. */
+function writeFailed(reason: unknown): string {
+  const detail = reason instanceof Error ? reason.message : String(reason);
+  return `Copy failed: ${detail}. Select the value above and copy it.`;
+}
+
+const valueStyle: CSSProperties = {
+  flex: 1,
+  padding: 'var(--tai-space-2) var(--tai-space-3)',
+  wordBreak: 'break-all',
+  userSelect: 'all',
+};
+
+/** Both states share one grid cell, so the button is as wide as the wider one. */
+const statesStyle: CSSProperties = {
+  display: 'grid',
+  alignItems: 'center',
+  justifyItems: 'center',
+};
+
+const stateStyle: CSSProperties = {
+  gridArea: '1 / 1',
+  display: 'inline-flex',
+  alignItems: 'center',
+  gap: 'var(--tai-space-2)',
+};
+
+export function CopyField({ value, caption, idPrefix = 'copy-field', label }: CopyFieldProps) {
+  const [copied, setCopied] = useState(false);
+  const [copyError, setCopyError] = useState<string | undefined>(undefined);
+  const resetTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // The clipboard write is async, so a copy can still be in flight when the
+  // component goes away — the caller's dialog closes on the same click. Clearing
+  // the timer alone would not cover that: at unmount there is no timer yet, and
+  // the resolution that follows would start one nothing is left to clear. This
+  // flag is what the resolution checks before it touches state at all.
+  const mounted = useRef(true);
+
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+      if (resetTimer.current !== null) clearTimeout(resetTimer.current);
+    };
+  }, []);
+
+  const handleCopy = (): void => {
+    const clipboard = clipboardOf(navigator);
+    if (clipboard === undefined) {
+      setCopyError(NO_CLIPBOARD);
+      return;
+    }
+    setCopyError(undefined);
+    void clipboard.writeText(value).then(
+      () => {
+        if (!mounted.current) return;
+        setCopied(true);
+        if (resetTimer.current !== null) clearTimeout(resetTimer.current);
+        resetTimer.current = setTimeout(() => {
+          setCopied(false);
+        }, COPIED_RESET_MS);
+      },
+      (error: unknown) => {
+        if (!mounted.current) return;
+        setCopyError(writeFailed(error));
+      },
+    );
+  };
+
+  return (
+    <div data-testid={idPrefix} className="tai-stack tai-stack-2">
+      {label !== undefined ? <span className="tai-field-label">{label}</span> : null}
+      <div className="tai-row">
+        <code className="tai-code" style={valueStyle}>
+          {value}
+        </code>
+        <button
+          type="button"
+          className="tai-btn tai-btn-secondary"
+          data-testid={`${idPrefix}-copy`}
+          onClick={handleCopy}
+        >
+          <span style={statesStyle}>
+            <span
+              aria-hidden={copied}
+              style={{ ...stateStyle, visibility: copied ? 'hidden' : 'visible' }}
+            >
+              <CopyIcon />
+              {COPY_LABEL}
+            </span>
+            <span
+              aria-hidden={!copied}
+              style={{ ...stateStyle, visibility: copied ? 'visible' : 'hidden' }}
+            >
+              <CheckIcon />
+              {COPIED_LABEL}
+            </span>
+          </span>
+        </button>
+        <span aria-live="polite" className="tai-visually-hidden">
+          {copied ? COPIED_ANNOUNCEMENT : ''}
+        </span>
+      </div>
+      {copyError !== undefined ? (
+        <span role="alert" className="tai-field-error">
+          <XCircleIcon />
+          {copyError}
+        </span>
+      ) : null}
+      {caption !== undefined ? <span className="tai-field-hint">{caption}</span> : null}
+    </div>
+  );
+}

package/src/components/dialog.tsx

@@ -0,0 +1,76 @@
+/**
+ * `Dialog` — a design-system wrapper over Radix Dialog: an accessible modal (role
+ * `dialog`, focus trap, Escape to close) labelled by its title. Modality is
+ * enforced by the focus trap and by Radix marking the rest of the page inert, not
+ * by an `aria-modal` attribute — the panel ships none.
+ *
+ * Radix owns every modal behaviour — the focus trap, the background scroll lock,
+ * Escape, and focus return to the trigger — so this component adds no second
+ * mechanism. It contributes only the design-system surface: `tai-overlay` paints
+ * the scrim from `--tai-color-scrim`, and `tai-dialog` sizes the panel with a
+ * `min()` so it still fits a 320 px viewport. The one gap Radix leaves — focus
+ * return for a dialog that renders no trigger — is filled by
+ * `useModalFocusReturn`, which stands down whenever a trigger IS rendered.
+ */
+import * as RadixDialog from '@radix-ui/react-dialog';
+import type { ReactElement, ReactNode } from 'react';
+
+import { assertSlotElement } from '../element-slot';
+import { useModalFocusReturn } from './modal-focus';
+
+export interface DialogProps {
+  readonly title: string;
+  readonly description?: string;
+  readonly children?: ReactNode;
+  /**
+   * A trigger element; when omitted, control the dialog via `open`/`onOpenChange`.
+   *
+   * It is a single ELEMENT, not any node: Radix clones its props onto it, so a
+   * string throws. The type admits a FRAGMENT — `<></>` is a `ReactElement` —
+   * which would render openers carrying neither the
+   * `aria-haspopup`/`aria-expanded`/`aria-controls` wiring nor a click handler,
+   * so {@link assertSlotElement} rejects that one at runtime.
+   */
+  readonly trigger?: ReactElement;
+  readonly open?: boolean;
+  readonly defaultOpen?: boolean;
+  readonly onOpenChange?: (open: boolean) => void;
+}
+
+export function Dialog({
+  title,
+  description,
+  children,
+  trigger,
+  open,
+  defaultOpen,
+  onOpenChange,
+}: DialogProps) {
+  const focusReturn = useModalFocusReturn(trigger !== undefined);
+  if (trigger !== undefined) assertSlotElement(trigger, 'Dialog `trigger`');
+  return (
+    <RadixDialog.Root open={open} defaultOpen={defaultOpen} onOpenChange={onOpenChange}>
+      {trigger !== undefined ? <RadixDialog.Trigger asChild>{trigger}</RadixDialog.Trigger> : null}
+      <RadixDialog.Portal>
+        <RadixDialog.Overlay className="tai-overlay" />
+        {/* Radix wires `aria-describedby` to its Description's id unconditionally,
+            so a dialog that renders no Description would ship a dangling IDREF.
+            Passing the prop as `undefined` is Radix's opt-out — it has to be
+            ABSENT when a description IS rendered, or it would clear the wiring. */}
+        <RadixDialog.Content
+          className="tai-dialog"
+          {...focusReturn}
+          {...(description === undefined ? { 'aria-describedby': undefined } : {})}
+        >
+          <RadixDialog.Title className="tai-dialog-title">{title}</RadixDialog.Title>
+          <div className="tai-stack">
+            {description !== undefined ? (
+              <RadixDialog.Description className="tai-muted">{description}</RadixDialog.Description>
+            ) : null}
+            {children}
+          </div>
+        </RadixDialog.Content>
+      </RadixDialog.Portal>
+    </RadixDialog.Root>
+  );
+}

package/src/components/drawer.tsx

@@ -0,0 +1,83 @@
+/**
+ * `Drawer` — a side-anchored, full-height modal panel, published for a screen
+ * that wants a modal it can anchor to an edge rather than centre. Nothing in
+ * Studio renders one today; it is SDK surface a plugin can reach for. It is the
+ * same Radix Dialog machinery `Dialog` uses, so
+ * the focus trap, the scroll lock, Escape and overlay dismissal, the inert
+ * background, and focus return to the opener all come from the primitive; only
+ * the anchoring differs, and that lives entirely in `.tai-drawer`.
+ *
+ * Pass the opener as `trigger` where there is one (as `Dialog` does): Radix's own
+ * trigger is what carries `aria-haspopup`/`aria-expanded`/`aria-controls` and
+ * what its close sequence hands focus back to. A drawer opened purely by flipping
+ * `open` renders no trigger, so `useModalFocusReturn` returns focus to the opener
+ * in that case alone — with a trigger present it stands down and Radix's own
+ * restore is the only mechanism.
+ *
+ * Open state takes either form, the same three props `Dialog` publishes:
+ * `open`/`onOpenChange` to drive it from the caller's state, `defaultOpen` (or
+ * nothing at all) to let Radix own it behind a `trigger`.
+ */
+import * as RadixDialog from '@radix-ui/react-dialog';
+import type { ReactElement, ReactNode } from 'react';
+
+import { assertSlotElement } from '../element-slot';
+import { CloseIcon } from './icons';
+import { useModalFocusReturn } from './modal-focus';
+
+export interface DrawerProps {
+  /** The dialog's accessible name. */
+  readonly title: string;
+  readonly children: ReactNode;
+  readonly side?: 'left' | 'right';
+  /**
+   * The opener. Radix labels it and returns focus to it when the drawer closes.
+   *
+   * It is a single ELEMENT, not any node: Radix clones its props onto it, so a
+   * string throws. The type admits a FRAGMENT — `<></>` is a `ReactElement` —
+   * which would render openers carrying neither the
+   * `aria-haspopup`/`aria-expanded`/`aria-controls` wiring nor a click handler,
+   * so {@link assertSlotElement} rejects that one at runtime.
+   */
+  readonly trigger?: ReactElement;
+  readonly open?: boolean;
+  readonly defaultOpen?: boolean;
+  readonly onOpenChange?: (open: boolean) => void;
+}
+
+export function Drawer({
+  title,
+  children,
+  side = 'left',
+  trigger,
+  open,
+  defaultOpen,
+  onOpenChange,
+}: DrawerProps) {
+  const focusReturn = useModalFocusReturn(trigger !== undefined);
+  if (trigger !== undefined) assertSlotElement(trigger, 'Drawer `trigger`');
+  return (
+    <RadixDialog.Root open={open} defaultOpen={defaultOpen} onOpenChange={onOpenChange}>
+      {trigger === undefined ? null : <RadixDialog.Trigger asChild>{trigger}</RadixDialog.Trigger>}
+      <RadixDialog.Portal>
+        <RadixDialog.Overlay className="tai-overlay" />
+        {/* The panel is named by its title alone; `aria-describedby={undefined}`
+            is Radix's opt-out for a dialog that carries no description. */}
+        <RadixDialog.Content
+          className="tai-drawer"
+          data-side={side}
+          aria-describedby={undefined}
+          {...focusReturn}
+        >
+          <div className="tai-drawer-header">
+            <RadixDialog.Title className="tai-section-title">{title}</RadixDialog.Title>
+            <RadixDialog.Close className="tai-icon-btn" aria-label="Close">
+              <CloseIcon />
+            </RadixDialog.Close>
+          </div>
+          {children}
+        </RadixDialog.Content>
+      </RadixDialog.Portal>
+    </RadixDialog.Root>
+  );
+}

package/src/components/error-boundary.tsx

@@ -0,0 +1,56 @@
+/**
+ * A generic render-error boundary: it contains a throw from its subtree and shows
+ * a loud `role="alert"` panel in its place, so one failing region never blanks the
+ * page around it. `label` prefixes the caught message to name the contained region
+ * (e.g. the plugin whose content threw); `onError` observes the error for logging.
+ * There is no in-place retry — the boundary resets by remounting, so callers that
+ * want a reset give it a fresh `key`.
+ *
+ * The fallback is the design system's `ErrorState`, so a contained render error
+ * looks exactly like a failed fetch: one `role="alert"` surface headed by a mark
+ * and words, never color alone. It is rendered without a retry, since the
+ * boundary resets by remounting.
+ */
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+
+import { errorMessage } from '../errors';
+import { ErrorState } from './primitives';
+
+export interface ErrorBoundaryProps {
+  readonly children: ReactNode;
+  /** Prefixed to the caught error message, naming the contained region. */
+  readonly label?: string;
+  /** Called with the caught error and React's component stack, for logging. */
+  readonly onError?: (error: unknown, info: ErrorInfo) => void;
+}
+
+// React passes whatever the subtree threw — an `Error`, but also a bare string
+// or any object a plugin chose to throw — so the caught value is `unknown` and
+// coerced to a readable string only for display. `hasError` is the caught flag
+// (not a sentinel on `error`), so even a falsy throw such as `null` is contained.
+interface ErrorBoundaryState {
+  readonly hasError: boolean;
+  readonly error: unknown;
+}
+
+export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  override state: ErrorBoundaryState = { hasError: false, error: null };
+
+  static getDerivedStateFromError(error: unknown): ErrorBoundaryState {
+    return { hasError: true, error };
+  }
+
+  override componentDidCatch(error: unknown, info: ErrorInfo): void {
+    this.props.onError?.(error, info);
+  }
+
+  override render(): ReactNode {
+    if (this.state.hasError) {
+      const { label } = this.props;
+      const text = errorMessage(this.state.error);
+      const message = label !== undefined ? `${label}: ${text}` : text;
+      return <ErrorState message={message} />;
+    }
+    return this.props.children;
+  }
+}