@tai42/studio-sdk 25.0.1 → 26.0.0

package/src/components/holder-list.tsx

@@ -0,0 +1,163 @@
+/**
+ * `HolderList` — the things that still use a name, each a link to where it lives.
+ * A core holder kind links to its Studio screen; a plugin kind links to the page its
+ * plugin registered for it; a kind nobody resolves shows as text, so no holder is
+ * hidden.
+ */
+import type { ReferenceHolder } from '@tai42/api-client';
+import { type MouseEvent, type ReactNode, useCallback } from 'react';
+
+import { errorMessage } from '../errors';
+import { useNavigation } from '../navigation/context';
+import { coreHolderRoute } from './holder-kinds';
+import { Spinner } from './primitives';
+import { ScrollRegion } from './scroll-region';
+
+/** Where one holder links: its `href` and the client-side transition to it. */
+export interface HolderHref {
+  readonly href: string;
+  readonly navigate: () => void;
+}
+
+/**
+ * The resolver for holder links: `null` for a kind neither the core table nor any
+ * registered plugin resolves.
+ */
+export function useHolderHref(): (holder: ReferenceHolder) => HolderHref | null {
+  const { navigate, resolvePath, navigatePlugin, resolvePluginPath, resolveHolderLink } =
+    useNavigation();
+  return useCallback(
+    (holder: ReferenceHolder): HolderHref | null => {
+      const core = coreHolderRoute(holder);
+      if (core !== null) {
+        return {
+          href: resolvePath(core.token, core.search),
+          navigate: () => {
+            navigate(core.token, core.search);
+          },
+        };
+      }
+      const target = resolveHolderLink?.(holder) ?? null;
+      if (target === null) return null;
+      const { pluginId, pagePath, params, search } = target;
+      return {
+        href: resolvePluginPath(pluginId, pagePath, params, search),
+        navigate: () => {
+          navigatePlugin(pluginId, pagePath, params, search);
+        },
+      };
+    },
+    [navigate, resolvePath, navigatePlugin, resolvePluginPath, resolveHolderLink],
+  );
+}
+
+export interface HolderListProps {
+  readonly holders: readonly ReferenceHolder[];
+  /** The list's accessible name, e.g. `Holders of <name>`. */
+  readonly label: string;
+  /** The line above the list saying what to do about the holders. */
+  readonly lead: string;
+  /** Called before a holder link navigates (a dialog closes itself here). */
+  readonly onNavigate?: () => void;
+}
+
+function HolderLink({
+  link,
+  onNavigate,
+  children,
+}: {
+  link: HolderHref;
+  onNavigate: (() => void) | undefined;
+  children: ReactNode;
+}): ReactNode {
+  const onClick = useCallback(
+    (event: MouseEvent<HTMLAnchorElement>) => {
+      if (event.defaultPrevented) return;
+      if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+        return;
+      event.preventDefault();
+      onNavigate?.();
+      link.navigate();
+    },
+    [link, onNavigate],
+  );
+  return (
+    <a className="tai-link" href={link.href} onClick={onClick}>
+      {children}
+    </a>
+  );
+}
+
+/** The lead line, then one list item per holder: a link where one resolves, else text. */
+export function HolderList({ holders, label, lead, onNavigate }: HolderListProps): ReactNode {
+  const hrefOf = useHolderHref();
+  return (
+    <div>
+      <p className="tai-holder-lead">{lead}</p>
+      <ScrollRegion label={label} axis="vertical" className="tai-holder-list">
+        <ul aria-label={label}>
+          {holders.map((holder, index) => {
+            const link = hrefOf(holder);
+            return (
+              <li key={`${holder.kind}\u0000${holder.name}\u0000${String(index)}`}>
+                {link === null ? (
+                  holder.summary
+                ) : (
+                  <HolderLink link={link} onNavigate={onNavigate}>
+                    {holder.summary}
+                  </HolderLink>
+                )}
+              </li>
+            );
+          })}
+        </ul>
+      </ScrollRegion>
+    </div>
+  );
+}
+
+/**
+ * What a dialog knows about the holders of a name before it acts: still reading, the
+ * caller has no grant for the read, the read failed, or the holders it read (or the
+ * holders a refusal named).
+ */
+export type HolderPreviewState =
+  | { readonly status: 'loading' }
+  | { readonly status: 'no-grant'; readonly message: string }
+  | { readonly status: 'error'; readonly error: unknown }
+  | { readonly status: 'ready'; readonly holders: readonly ReferenceHolder[] };
+
+export interface HolderPreviewProps extends Omit<HolderListProps, 'holders'> {
+  readonly state: HolderPreviewState;
+}
+
+/**
+ * The holder region of a rename, delete or detach dialog. The preview is advisory:
+ * loading, no grant and a failed read leave the dialog's action enabled, and the
+ * server's refusal decides. An empty preview renders nothing.
+ */
+export function HolderPreview({ state, ...list }: HolderPreviewProps): ReactNode {
+  switch (state.status) {
+    case 'loading':
+      return <Spinner label="Checking what still uses this" />;
+    case 'no-grant':
+      return (
+        <p role="status" className="tai-muted" style={{ margin: 0 }}>
+          {state.message}
+        </p>
+      );
+    case 'error':
+      return (
+        <p role="status" className="tai-muted" style={{ margin: 0 }}>
+          Could not check what uses this: {errorMessage(state.error)}
+        </p>
+      );
+    case 'ready':
+      return state.holders.length === 0 ? null : <HolderList holders={state.holders} {...list} />;
+  }
+}
+
+/** The holders a preview state blocks on: a non-empty list disables the action. */
+export function previewHolders(state: HolderPreviewState): readonly ReferenceHolder[] {
+  return state.status === 'ready' ? state.holders : [];
+}

package/src/components/icons/index.ts

@@ -64,7 +64,6 @@ export {
   ConversationsIcon,
   DashboardIcon,
   DatabaseIcon,
-  ExtensionsIcon,
   HooksIcon,
   InteractionsIcon,
   ManifestIcon,
@@ -78,7 +77,6 @@ export {
   SettingsIcon,
   StorageIcon,
   SystemIcon,
-  TemplatesIcon,
   ToolsIcon,
 } from './nav-marks';
 export { AlertTriangleIcon, CheckCircleIcon, PendingIcon, XCircleIcon } from './status-marks';

package/src/components/icons/nav-map.ts

@@ -11,7 +11,6 @@ import {
   ConversationsIcon,
   DashboardIcon,
   DatabaseIcon,
-  ExtensionsIcon,
   HooksIcon,
   InteractionsIcon,
   ManifestIcon,
@@ -24,7 +23,6 @@ import {
   SettingsIcon,
   StorageIcon,
   SystemIcon,
-  TemplatesIcon,
   ToolsIcon,
 } from './nav-marks';
 
@@ -39,8 +37,6 @@ export const NAV_ICONS: Readonly<Record<Exclude<RouteToken, 'login'>, IconCompon
   agents: AgentsIcon,
   presets: PresetsIcon,
   states: DatabaseIcon,
-  extensions: ExtensionsIcon,
-  templates: TemplatesIcon,
   connectors: ConnectorsIcon,
   servedEndpoints: ServedEndpointsIcon,
   hooks: HooksIcon,

package/src/components/icons/nav-marks.tsx

@@ -47,21 +47,6 @@ export const PresetsIcon: IconComponent = (props) => (
   </Icon>
 );
 
-/** Extensions: a jigsaw piece — knob above, socket to the right. */
-export const ExtensionsIcon: IconComponent = (props) => (
-  <Icon {...props}>
-    <path d="M9.5 6.5a2.2 2.2 0 0 1 4.4 0v.7h4.3a1.3 1.3 0 0 1 1.3 1.3v3.4H18a2.2 2.2 0 0 0 0 4.4h1.5v2.8a1.3 1.3 0 0 1-1.3 1.3H5.8a1.3 1.3 0 0 1-1.3-1.3V8.5a1.3 1.3 0 0 1 1.3-1.3h3.7z" />
-  </Icon>
-);
-
-/** Templates: a stack of two sheets, the front one offset. */
-export const TemplatesIcon: IconComponent = (props) => (
-  <Icon {...props}>
-    <path d="M8 8V5a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v9a2 2 0 0 1-2 2h-3" />
-    <rect x="3" y="8" width="13" height="13" rx="2" />
-  </Icon>
-);
-
 /** Connectors: a two-pin power plug on its lead. */
 export const ConnectorsIcon: IconComponent = (props) => (
   <Icon {...props}>

package/src/components/named-list-picker.tsx

@@ -0,0 +1,182 @@
+/**
+ * The single-select both `AgentPicker` and `ChannelPicker` render: one list read of
+ * names, drawn in its own `Field` with the read's states (pending, error with Retry,
+ * refused on a 403, loaded and empty) and a stored value the loaded list does not
+ * hold flagged with the picker's unlisted label. Each picker hands in its own copy.
+ * The host's `error` shows, and the `Field` claims its control id, exactly while a
+ * `Select` renders.
+ */
+import { type ReactNode, useId } from 'react';
+
+import { errorMessage, isForbiddenError } from '../errors';
+import { Badge } from './badge';
+import { Field } from './field';
+import { ErrorState } from './primitives';
+import { Select, type SelectOption } from './select';
+
+const MUTED_LINE = { margin: 0, color: 'var(--tai-color-text-muted)' } as const;
+
+/** The flags of a list read; `data` is each picker's own. */
+export interface ListReadFlags {
+  readonly isPending: boolean;
+  readonly isError: boolean;
+  readonly isSuccess: boolean;
+  readonly error: unknown;
+  readonly refetch: () => void;
+}
+
+/** The picker's own copy. */
+export interface NamedListCopy {
+  readonly label: string;
+  readonly description?: string | undefined;
+  readonly loadingPlaceholder: string;
+  readonly placeholder: string;
+  readonly forbiddenNote: string;
+  readonly emptyNote: string;
+  readonly emptyAction: ReactNode;
+  readonly unlistedLabel: string;
+}
+
+export interface NamedListPickerProps {
+  readonly query: ListReadFlags;
+  /** The listed names once the read succeeded. */
+  readonly names: readonly string[];
+  readonly value: string;
+  readonly onValueChange: (value: string) => void;
+  readonly error?: string | undefined;
+  readonly copy: NamedListCopy;
+}
+
+function MutedLine({ text }: { readonly text: string }): ReactNode {
+  return (
+    <p role="status" style={MUTED_LINE}>
+      {text}
+    </p>
+  );
+}
+
+/** What the picker draws, derived from the read, the listed names and the value. */
+interface NamedListView {
+  readonly refused: boolean;
+  readonly failed: boolean;
+  readonly pending: boolean;
+  readonly unlisted: boolean;
+  readonly empty: boolean;
+  readonly options: readonly SelectOption[];
+  readonly selectRenders: boolean;
+}
+
+/** The stored value's own option: flagged when the loaded list does not hold it, and kept
+ * unflagged under a 403, where without the list the form claims nothing about it. */
+function storedOptions(
+  stored: string,
+  unlisted: boolean,
+  refused: boolean,
+  unlistedLabel: string,
+): SelectOption[] {
+  if (unlisted) return [{ value: stored, label: `${stored} (${unlistedLabel})` }];
+  return refused ? [{ value: stored, label: stored }] : [];
+}
+
+function listedOptions(loaded: boolean, names: readonly string[]): SelectOption[] {
+  return loaded ? names.map((name) => ({ value: name, label: name })) : [];
+}
+
+function namedListView(
+  query: ListReadFlags,
+  names: readonly string[],
+  value: string,
+  unlistedLabel: string,
+): NamedListView {
+  const refused = query.isError && isForbiddenError(query.error);
+  const failed = query.isError && !refused;
+  const loaded = query.isSuccess && !query.isError;
+  const pending = !loaded && !query.isError;
+  const stored = value !== '' ? value : null;
+  const unlisted = loaded && stored !== null && !names.includes(stored);
+  const empty = loaded && names.length === 0;
+
+  const options =
+    stored === null
+      ? listedOptions(loaded, names)
+      : [
+          ...storedOptions(stored, unlisted, refused, unlistedLabel),
+          ...listedOptions(loaded, names),
+        ];
+  const selectRenders = pending || (refused ? stored !== null : !failed && (!empty || unlisted));
+  return { refused, failed, pending, unlisted, empty, options, selectRenders };
+}
+
+/** The loaded, pending or refused body: the `Select` while one renders, then its notes. */
+function NamedListBody({
+  view,
+  value,
+  onValueChange,
+  copy,
+}: {
+  readonly view: NamedListView;
+  readonly value: string;
+  readonly onValueChange: (value: string) => void;
+  readonly copy: NamedListCopy;
+}): ReactNode {
+  const unlistedId = useId();
+  return (
+    <>
+      {view.selectRenders ? (
+        <Select
+          options={view.options}
+          value={value}
+          placeholder={view.pending ? copy.loadingPlaceholder : copy.placeholder}
+          disabled={view.pending}
+          onValueChange={onValueChange}
+          aria-describedby={view.unlisted ? unlistedId : undefined}
+        />
+      ) : null}
+      {view.refused ? <MutedLine text={copy.forbiddenNote} /> : null}
+      {view.empty && !view.refused ? (
+        <>
+          <MutedLine text={copy.emptyNote} />
+          {copy.emptyAction}
+        </>
+      ) : null}
+      {view.unlisted ? (
+        <p id={unlistedId} className="tai-field-hint" style={{ margin: 0 }}>
+          <Badge variant="warning">{copy.unlistedLabel}</Badge>{' '}
+          {`${value} is ${copy.unlistedLabel}. Pick another, or saving is refused.`}
+        </p>
+      ) : null}
+    </>
+  );
+}
+
+export function NamedListPicker({
+  query,
+  names,
+  value,
+  onValueChange,
+  error,
+  copy,
+}: NamedListPickerProps): ReactNode {
+  const view = namedListView(query, names, value, copy.unlistedLabel);
+  return (
+    <Field
+      label={copy.label}
+      description={copy.description}
+      error={view.selectRenders ? error : undefined}
+      // Only the Select claims the field's control id; with nothing to hold no
+      // labelable element renders, so `for` would dangle.
+      group={!view.selectRenders}
+    >
+      {view.failed ? (
+        <ErrorState
+          message={errorMessage(query.error)}
+          onRetry={() => {
+            query.refetch();
+          }}
+        />
+      ) : (
+        <NamedListBody view={view} value={value} onValueChange={onValueChange} copy={copy} />
+      )}
+    </Field>
+  );
+}

package/src/components/named-list-test-utils.tsx

@@ -0,0 +1,47 @@
+/** The stub query and navigation harness the agent and channel picker tests share. */
+import { render } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { vi } from 'vitest';
+
+import { NavigationProvider } from '../navigation/context';
+import type { NavigationContextValue, RouteSearch, RouteToken } from '../navigation/types';
+
+export interface StubQuery<T> {
+  readonly data: T | undefined;
+  readonly isPending: boolean;
+  readonly isError: boolean;
+  readonly isSuccess: boolean;
+  readonly error: unknown;
+  readonly refetch: () => void;
+}
+
+export function stubQuery<T>(overrides: Partial<StubQuery<T>>): StubQuery<T> {
+  return {
+    data: undefined,
+    isPending: false,
+    isError: false,
+    isSuccess: false,
+    error: null,
+    refetch: vi.fn(),
+    ...overrides,
+  };
+}
+
+export const pendingRead = { isPending: true } as const;
+export const forbiddenRead = { isError: true, error: { status: 403 } } as const;
+
+function navigation(): NavigationContextValue {
+  return {
+    navigate: vi.fn(),
+    resolvePath: <T extends RouteToken>(token: T, search?: RouteSearch<T>) => {
+      const qs = search ? new URLSearchParams(search as Record<string, string>).toString() : '';
+      return `/${token}${qs ? `?${qs}` : ''}`;
+    },
+    navigatePlugin: vi.fn(),
+    resolvePluginPath: vi.fn(() => '/plugins'),
+  };
+}
+
+export function renderWithNavigation(ui: ReactNode): ReturnType<typeof render> {
+  return render(<NavigationProvider value={navigation()}>{ui}</NavigationProvider>);
+}

package/src/components/recycle-roll.tsx

@@ -0,0 +1,120 @@
+/**
+ * The report of one fleet recycle roll — shared by the profile apply report and the
+ * Environment tab's save report, so both read the same rows the same way.
+ *
+ * One row per worker the roll reached: its name, kind, status and life (joined onto a
+ * fresh life sharing its name). `recycled` reads as done, the writer's own
+ * `self-deferred` line as a warning with its note, and the target the roll stopped at
+ * (`timed-out` / `failed`) as a failure with the reason the server gave. When the roll
+ * stopped, a warning panel says where and why and that the workers after it still run
+ * the old value. Names only — the report carries no env value. Every server string
+ * renders as escaped React text.
+ */
+import type { FreshLife, RecycleEntry, RecycleStop } from '@tai42/api-client';
+import type { CSSProperties, ReactNode } from 'react';
+
+import { Badge } from './badge';
+import { AlertTriangleIcon } from './icons';
+
+const labelStyle: CSSProperties = {
+  fontSize: 'var(--tai-text-sm)',
+  color: 'var(--tai-color-text-muted)',
+};
+
+const rowListStyle: CSSProperties = {
+  listStyle: 'none',
+  margin: 0,
+  padding: 0,
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 'var(--tai-space-3)',
+};
+
+const noteStyle: CSSProperties = {
+  margin: '0 0 var(--tai-space-3)',
+  color: 'var(--tai-color-text-muted)',
+  fontSize: 'var(--tai-text-sm)',
+};
+
+/** The badge tone a row's status takes: done, the writer's deferred exit, or the stop. */
+function statusVariant(status: string): string {
+  if (status === 'recycled') return 'success';
+  if (status === 'self-deferred') return 'warning';
+  return 'danger';
+}
+
+/** Where the roll stopped and why: the workers after it were not recycled. */
+function StoppedPanel({ stopped }: { readonly stopped: RecycleStop }): ReactNode {
+  const where =
+    stopped.name !== null
+      ? `The recycle stopped at ${stopped.name} (${stopped.kind} workers)`
+      : `The recycle stopped before it reached a worker (${stopped.kind} workers)`;
+  return (
+    <div
+      role="alert"
+      className="tai-warn-state tai-stack tai-stack-2"
+      data-testid="recycle-stopped"
+    >
+      <strong className="tai-status tai-status-warn">
+        <AlertTriangleIcon />
+        {where}
+      </strong>
+      <p>{stopped.detail}</p>
+      <p>
+        The change is saved and every worker reloaded, but the workers after this point were not
+        recycled and still run the old value, and this worker was not recycled. Restart them through
+        your deployment&rsquo;s supervisor.
+      </p>
+    </div>
+  );
+}
+
+export interface RecycleRollSectionProps {
+  readonly recycle: readonly RecycleEntry[];
+  readonly fresh: readonly FreshLife[];
+  readonly stopped: RecycleStop | null;
+  /** The note beside the worker that took the change, on its `self-deferred` row. */
+  readonly writerNote: string;
+}
+
+export function RecycleRollSection({
+  recycle,
+  fresh,
+  stopped,
+  writerNote,
+}: RecycleRollSectionProps): ReactNode {
+  if (recycle.length === 0 && stopped === null) {
+    return <p style={noteStyle}>No process recycle was needed.</p>;
+  }
+  return (
+    <div className="tai-stack">
+      {recycle.length > 0 ? (
+        <ul style={rowListStyle} data-testid="apply-recycle">
+          {recycle.map((entry) => {
+            const joined = fresh.find((life) => life.name === entry.name);
+            return (
+              <li
+                key={`${entry.name}-${entry.kind}-${String(entry.generation_before)}`}
+                className="tai-row"
+              >
+                <span className="tai-mono">{entry.name}</span>
+                <Badge variant="neutral">{entry.kind}</Badge>
+                <Badge variant={statusVariant(entry.status)}>{entry.status}</Badge>
+                <span style={labelStyle}>
+                  {joined !== undefined
+                    ? `life ${String(entry.generation_before)} to ${String(joined.generation)}`
+                    : `life ${String(entry.generation_before)}`}
+                </span>
+                {entry.status === 'self-deferred' ? (
+                  <span style={labelStyle}>{writerNote}</span>
+                ) : null}
+                {entry.detail !== null ? <span style={labelStyle}>{entry.detail}</span> : null}
+              </li>
+            );
+          })}
+        </ul>
+      ) : null}
+      {stopped !== null ? <StoppedPanel stopped={stopped} /> : null}
+    </div>
+  );
+}

package/src/components/stepper.tsx

@@ -0,0 +1,111 @@
+/**
+ * `Stepper` — the progress of a short multi-step flow: a named `<nav>` over an
+ * ordered list, one entry per step with a numbered (or marked) 24 px marker and
+ * its label. The `current` step carries `aria-current="step"`; every marker says
+ * its state in visually-hidden text, so a state is never told by colour alone.
+ *
+ * A `done` step is a button when `onStepSelect` is given (Tab reaches it,
+ * Enter/Space selects it); without it no step is interactive. The stepper holds
+ * no step content: the caller renders the current step's body.
+ *
+ * At the narrow breakpoint the list collapses to one line, "Step 2 of 3: Pick
+ * tools", with the other steps visually hidden (still in the list).
+ */
+import type { ReactNode } from 'react';
+
+import { AlertTriangleIcon, CheckIcon } from './icons';
+
+export type StepperStatus = 'done' | 'current' | 'upcoming' | 'error';
+
+export interface StepperStep {
+  readonly id: string;
+  readonly label: string;
+  readonly status: StepperStatus;
+}
+
+export interface StepperProps {
+  readonly steps: readonly StepperStep[];
+  readonly 'aria-label': string;
+  /** Called with a `done` step's id; when omitted no step is interactive. */
+  readonly onStepSelect?: (id: string) => void;
+}
+
+const STATUS_TEXT: Record<StepperStatus, string> = {
+  done: 'completed',
+  current: 'current step',
+  upcoming: 'not started',
+  error: 'failed',
+};
+
+const MARKER_CLASS: Record<StepperStatus, string> = {
+  done: 'tai-stepper-marker tai-stepper-marker-done',
+  current: 'tai-stepper-marker tai-stepper-marker-current',
+  upcoming: 'tai-stepper-marker tai-stepper-marker-upcoming',
+  error: 'tai-stepper-marker tai-stepper-marker-error',
+};
+
+const STEP_CLASS: Record<StepperStatus, string> = {
+  done: 'tai-stepper-step tai-stepper-step-done',
+  current: 'tai-stepper-step tai-stepper-step-current',
+  upcoming: 'tai-stepper-step tai-stepper-step-upcoming',
+  error: 'tai-stepper-step',
+};
+
+function Marker({ status, index }: { status: StepperStatus; index: number }): ReactNode {
+  return (
+    <span className={MARKER_CLASS[status]} aria-hidden="true">
+      {status === 'done' ? (
+        <CheckIcon />
+      ) : status === 'error' ? (
+        <AlertTriangleIcon />
+      ) : (
+        String(index + 1)
+      )}
+    </span>
+  );
+}
+
+export function Stepper({ steps, 'aria-label': label, onStepSelect }: StepperProps): ReactNode {
+  const currentIndex = steps.findIndex((step) => step.status === 'current');
+  return (
+    <nav aria-label={label}>
+      <ol className="tai-stepper">
+        {steps.map((step, index) => {
+          const body = (
+            <>
+              <Marker status={step.status} index={index} />
+              <span className="tai-stepper-label">
+                {currentIndex === index ? (
+                  <span className="tai-stepper-position">{`Step ${String(index + 1)} of ${String(steps.length)}: `}</span>
+                ) : null}
+                {step.label}
+              </span>
+              <span className="tai-visually-hidden">{`, ${STATUS_TEXT[step.status]}`}</span>
+            </>
+          );
+          return (
+            <li
+              key={step.id}
+              className={STEP_CLASS[step.status]}
+              aria-current={step.status === 'current' ? 'step' : undefined}
+            >
+              {step.status === 'done' && onStepSelect !== undefined ? (
+                <button
+                  type="button"
+                  className="tai-stepper-button"
+                  onClick={() => {
+                    onStepSelect(step.id);
+                  }}
+                >
+                  {body}
+                </button>
+              ) : (
+                <span className="tai-stepper-button">{body}</span>
+              )}
+            </li>
+          );
+        })}
+      </ol>
+    </nav>
+  );
+}