@tai42/studio-sdk 16.0.0 → 17.0.0

package/src/components/extension-combo-builder.tsx

@@ -34,25 +34,20 @@
  *
  * SAFETY: an extension name is server-supplied, so every name renders as TEXT through
  * the DS `Badge`/`Checkbox` (React escapes it) — never an HTML sink.
- *
- * Geometry and ink come from the design-system classes: each committed combo is a
- * `tai-card` row, the invalid notes are `tai-field-error` (icon + message, never
- * color alone), and Remove is a labelled `Button` carrying `CloseIcon` beside the
- * word, under an accessible name that names the combo it removes.
  */
-import { Fragment, useEffect, useState, type ReactNode } from 'react';
-
 import type { Extension, PresetExtensionElement } from '@tai42/api-client';
+import { type ReactNode, useEffect, useState } from 'react';
 
 import { comboElementNames, extensionElementName } from '../extension-combos';
-import { SchemaEditor, type SchemaEditorChange } from '../schema-editor';
-import { Badge } from './badge';
-import { ExtensionPicker } from './extension-picker';
-import { CloseIcon, XCircleIcon } from './icons';
-import { Button } from './primitives';
-
-/** The one config-taking extension this builder authors inline. */
-const OUTPUT_SCHEMA = 'output_schema';
+import { type SchemaEditorChange } from '../schema-editor';
+import {
+  ComboDraftEditor,
+  CommittedComboList,
+  OUTPUT_SCHEMA,
+  outputSchemaConfig,
+  sameNames,
+  unknownNames,
+} from './extension-combo-parts';
 
 export interface ExtensionComboBuilderProps {
   /** The extension catalog the combos are drawn from (caller-fetched). */
@@ -79,34 +74,6 @@ export interface ExtensionComboBuilderProps {
   readonly availableReady?: boolean;
 }
 
-/** Two combos are equal when their NAME sequences match (config is not part of identity). */
-function sameNames(a: readonly string[], b: readonly string[]): boolean {
-  return a.length === b.length && a.every((name, index) => name === b[index]);
-}
-
-/** The stored `output_schema` config schema for a combo, if it carries one. */
-function outputSchemaConfig(
-  combo: readonly PresetExtensionElement[],
-): Record<string, unknown> | null {
-  for (const element of combo) {
-    if (typeof element !== 'string' && element.name === OUTPUT_SCHEMA) {
-      const schema = element.config.schema;
-      return typeof schema === 'object' && schema !== null && !Array.isArray(schema)
-        ? (schema as Record<string, unknown>)
-        : {};
-    }
-  }
-  return null;
-}
-
-/** The element names in a combo that are absent from the known catalog. */
-function unknownNames(
-  combo: readonly PresetExtensionElement[],
-  availableNames: ReadonlySet<string>,
-): string[] {
-  return comboElementNames(combo).filter((name) => !availableNames.has(name));
-}
-
 export function ExtensionComboBuilder({
   available,
   value,
@@ -192,116 +159,31 @@ export function ExtensionComboBuilder({
 
   return (
     <div data-testid={idPrefix} className="tai-stack">
-      {value.length > 0 ? (
-        <ul className="tai-stack tai-stack-2">
-          {value.map((combo, index) => {
-            const names = comboElementNames(combo);
-            const unknown = availableReady ? unknownNames(combo, availableNames) : [];
-            return (
-              // The index IS the identity here: the list mutates by append, in-place
-              // update, and remove-by-index (no reorder), and a combo has no stable id
-              // of its own — so an index key is stable and cannot collide.
-              <li key={index} className="tai-card tai-stack tai-stack-2">
-                <div className="tai-row">
-                  {/* The badges take the row's spare width so the Edit/Remove pair
-                      pins to a stable trailing edge across combos of varied length. */}
-                  <span className="tai-row" style={{ flex: 1 }}>
-                    {names.map((name, position) => (
-                      <Fragment key={`${name}-${String(position)}`}>
-                        {position > 0 ? (
-                          <span aria-hidden className="tai-muted">
-                            +
-                          </span>
-                        ) : null}
-                        <Badge variant={unknown.includes(name) ? 'danger' : 'primary'}>
-                          {name}
-                        </Badge>
-                      </Fragment>
-                    ))}
-                  </span>
-                  <Button
-                    type="button"
-                    // The name starts with the words the button is SHOWING, which
-                    // is what WCAG 2.5.3 (Label in Name) asks: a constant "Edit …"
-                    // would leave a button reading "Editing" named "Edit", and a
-                    // voice-control user naming a control they cannot see.
-                    aria-label={`${editing === index ? 'Editing' : 'Edit'} extension set ${names.join('+')}`}
-                    disabled={disabled === true || editing === index}
-                    onClick={() => {
-                      startEdit(index);
-                    }}
-                  >
-                    {editing === index ? 'Editing' : 'Edit'}
-                  </Button>
-                  <Button
-                    type="button"
-                    aria-label={`Remove extension set ${names.join('+')}`}
-                    disabled={disabled}
-                    onClick={() => {
-                      removeCombo(index);
-                    }}
-                  >
-                    <CloseIcon />
-                    Remove
-                  </Button>
-                </div>
-                {unknown.length > 0 ? (
-                  <p role="alert" className="tai-field-error">
-                    <XCircleIcon />
-                    {unknown.length === 1 ? 'Unknown extension: ' : 'Unknown extensions: '}
-                    {unknown.join(', ')}.
-                  </p>
-                ) : null}
-              </li>
-            );
-          })}
-        </ul>
-      ) : (
-        <p className="tai-muted">No extension sets.</p>
-      )}
-
-      <div className="tai-stack tai-stack-2">
-        <ExtensionPicker
-          available={available}
-          value={draft}
-          onChange={setDraft}
-          disabled={disabled}
-          idPrefix={`${idPrefix}-draft`}
-        />
-
-        {draftHasOutputSchema ? (
-          <SchemaEditor
-            value={draftConfig.schema}
-            onChange={setDraftConfig}
-            requireTitle={false}
-            label="Output schema"
-            description="The JSON Schema the output_schema extension enforces on this extension set's result."
-            disabled={disabled}
-            idPrefix={`${idPrefix}-output-schema`}
-            // Re-seed the editor when the draft target changes (a new draft vs a
-            // specific combo pulled in for edit).
-            key={editing === null ? 'new' : `edit-${String(editing)}`}
-          />
-        ) : null}
-
-        {isDuplicate ? (
-          <p role="alert" className="tai-field-error">
-            <XCircleIcon />
-            This extension set is already added.
-          </p>
-        ) : null}
-
-        <div className="tai-row">
-          <Button type="button" variant="primary" onClick={commitCombo} disabled={!canAdd}>
-            {editing === null ? 'Add extension set' : 'Update extension set'}
-          </Button>
-          {editing !== null ? (
-            <Button type="button" onClick={resetDraft} disabled={disabled}>
-              Cancel edit
-            </Button>
-          ) : null}
-        </div>
-      </div>
+      <CommittedComboList
+        value={value}
+        availableReady={availableReady}
+        availableNames={availableNames}
+        editing={editing}
+        disabled={disabled}
+        onEdit={startEdit}
+        onRemove={removeCombo}
+      />
+
+      <ComboDraftEditor
+        available={available}
+        draft={draft}
+        onDraftChange={setDraft}
+        draftHasOutputSchema={draftHasOutputSchema}
+        draftConfig={draftConfig}
+        onDraftConfigChange={setDraftConfig}
+        isDuplicate={isDuplicate}
+        canAdd={canAdd}
+        editing={editing}
+        disabled={disabled}
+        idPrefix={idPrefix}
+        onCommit={commitCombo}
+        onReset={resetDraft}
+      />
     </div>
   );
 }

package/src/components/extension-combo-parts.tsx

@@ -0,0 +1,236 @@
+/**
+ * The pieces of `ExtensionComboBuilder`: the committed-combo list
+ * (`CommittedComboList`), the under-construction combo editor (`ComboDraftEditor`),
+ * and the shared combo helpers. The builder owns the state and composes these.
+ */
+import type { Extension, PresetExtensionElement } from '@tai42/api-client';
+import { Fragment, type ReactNode } from 'react';
+
+import { comboElementNames } from '../extension-combos';
+import { SchemaEditor, type SchemaEditorChange } from '../schema-editor';
+import { Badge } from './badge';
+import { ExtensionPicker } from './extension-picker';
+import { CloseIcon, XCircleIcon } from './icons';
+import { Button } from './primitives';
+
+/** The one config-taking extension this builder authors inline. */
+export const OUTPUT_SCHEMA = 'output_schema';
+
+/** Two combos are equal when their NAME sequences match (config is not part of identity). */
+export function sameNames(a: readonly string[], b: readonly string[]): boolean {
+  return a.length === b.length && a.every((name, index) => name === b[index]);
+}
+
+/** The stored `output_schema` config schema for a combo, if it carries one. */
+export function outputSchemaConfig(
+  combo: readonly PresetExtensionElement[],
+): Record<string, unknown> | null {
+  for (const element of combo) {
+    if (typeof element !== 'string' && element.name === OUTPUT_SCHEMA) {
+      const schema = element.config.schema;
+      return typeof schema === 'object' && schema !== null && !Array.isArray(schema)
+        ? (schema as Record<string, unknown>)
+        : {};
+    }
+  }
+  return null;
+}
+
+/** The element names in a combo that are absent from the known catalog. */
+export function unknownNames(
+  combo: readonly PresetExtensionElement[],
+  availableNames: ReadonlySet<string>,
+): string[] {
+  return comboElementNames(combo).filter((name) => !availableNames.has(name));
+}
+
+/** One committed combo's row: its name badges and the Edit / Remove pair, with an
+ *  inline unknown-name note. */
+function CommittedComboRow({
+  combo,
+  index,
+  editing,
+  disabled,
+  unknown,
+  onEdit,
+  onRemove,
+}: {
+  readonly combo: readonly PresetExtensionElement[];
+  readonly index: number;
+  readonly editing: number | null;
+  readonly disabled: boolean | undefined;
+  readonly unknown: readonly string[];
+  readonly onEdit: (index: number) => void;
+  readonly onRemove: (index: number) => void;
+}): ReactNode {
+  const names = comboElementNames(combo);
+  return (
+    <li className="tai-card tai-stack tai-stack-2">
+      <div className="tai-row">
+        {/* The badges take the row's spare width so the Edit/Remove pair pins to a
+            stable trailing edge across combos of varied length. */}
+        <span className="tai-row" style={{ flex: 1 }}>
+          {names.map((name, position) => (
+            <Fragment key={`${name}-${String(position)}`}>
+              {position > 0 ? (
+                <span aria-hidden className="tai-muted">
+                  +
+                </span>
+              ) : null}
+              <Badge variant={unknown.includes(name) ? 'danger' : 'primary'}>{name}</Badge>
+            </Fragment>
+          ))}
+        </span>
+        <Button
+          type="button"
+          // The name starts with the words the button is SHOWING, which is what WCAG
+          // 2.5.3 (Label in Name) asks: a constant "Edit …" would leave a button
+          // reading "Editing" named "Edit", and a voice-control user naming a control
+          // they cannot see.
+          aria-label={`${editing === index ? 'Editing' : 'Edit'} extension set ${names.join('+')}`}
+          disabled={disabled === true || editing === index}
+          onClick={() => {
+            onEdit(index);
+          }}
+        >
+          {editing === index ? 'Editing' : 'Edit'}
+        </Button>
+        <Button
+          type="button"
+          aria-label={`Remove extension set ${names.join('+')}`}
+          disabled={disabled}
+          onClick={() => {
+            onRemove(index);
+          }}
+        >
+          <CloseIcon />
+          Remove
+        </Button>
+      </div>
+      {unknown.length > 0 ? (
+        <p role="alert" className="tai-field-error">
+          <XCircleIcon />
+          {unknown.length === 1 ? 'Unknown extension: ' : 'Unknown extensions: '}
+          {unknown.join(', ')}.
+        </p>
+      ) : null}
+    </li>
+  );
+}
+
+/** The current combos, each a row of name badges with per-combo Edit and Remove. */
+export function CommittedComboList({
+  value,
+  availableReady,
+  availableNames,
+  editing,
+  disabled,
+  onEdit,
+  onRemove,
+}: {
+  readonly value: readonly PresetExtensionElement[][];
+  readonly availableReady: boolean;
+  readonly availableNames: ReadonlySet<string>;
+  readonly editing: number | null;
+  readonly disabled: boolean | undefined;
+  readonly onEdit: (index: number) => void;
+  readonly onRemove: (index: number) => void;
+}): ReactNode {
+  if (value.length === 0) return <p className="tai-muted">No extension sets.</p>;
+  return (
+    <ul className="tai-stack tai-stack-2">
+      {value.map((combo, index) => (
+        // The index IS the identity here: the list mutates by append, in-place update,
+        // and remove-by-index (no reorder), and a combo has no stable id of its own —
+        // so an index key is stable and cannot collide.
+        <CommittedComboRow
+          key={index}
+          combo={combo}
+          index={index}
+          editing={editing}
+          disabled={disabled}
+          unknown={availableReady ? unknownNames(combo, availableNames) : []}
+          onEdit={onEdit}
+          onRemove={onRemove}
+        />
+      ))}
+    </ul>
+  );
+}
+
+/** The combo under construction: the extension picker, the inline output-schema
+ *  editor when present, the duplicate note, and the Add/Update + Cancel actions. */
+export function ComboDraftEditor({
+  available,
+  draft,
+  onDraftChange,
+  draftHasOutputSchema,
+  draftConfig,
+  onDraftConfigChange,
+  isDuplicate,
+  canAdd,
+  editing,
+  disabled,
+  idPrefix,
+  onCommit,
+  onReset,
+}: {
+  readonly available: readonly Extension[];
+  readonly draft: string[];
+  readonly onDraftChange: (draft: string[]) => void;
+  readonly draftHasOutputSchema: boolean;
+  readonly draftConfig: SchemaEditorChange;
+  readonly onDraftConfigChange: (change: SchemaEditorChange) => void;
+  readonly isDuplicate: boolean;
+  readonly canAdd: boolean;
+  readonly editing: number | null;
+  readonly disabled: boolean | undefined;
+  readonly idPrefix: string;
+  readonly onCommit: () => void;
+  readonly onReset: () => void;
+}): ReactNode {
+  return (
+    <div className="tai-stack tai-stack-2">
+      <ExtensionPicker
+        available={available}
+        value={draft}
+        onChange={onDraftChange}
+        disabled={disabled}
+        idPrefix={`${idPrefix}-draft`}
+      />
+
+      {draftHasOutputSchema ? (
+        <SchemaEditor
+          value={draftConfig.schema}
+          onChange={onDraftConfigChange}
+          requireTitle={false}
+          label="Output schema"
+          description="The JSON Schema the output_schema extension enforces on this extension set's result."
+          disabled={disabled}
+          idPrefix={`${idPrefix}-output-schema`}
+          // Re-seed the editor when the draft target changes (a new draft vs a
+          // specific combo pulled in for edit).
+          key={editing === null ? 'new' : `edit-${String(editing)}`}
+        />
+      ) : null}
+
+      {isDuplicate ? (
+        <p role="alert" className="tai-field-error">
+          <XCircleIcon />
+          This extension set is already added.
+        </p>
+      ) : null}
+
+      <div className="tai-row">
+        <Button type="button" variant="primary" onClick={onCommit} disabled={!canAdd}>
+          {editing === null ? 'Add extension set' : 'Update extension set'}
+        </Button>
+        {editing !== null ? (
+          <Button type="button" onClick={onReset} disabled={disabled}>
+            Cancel edit
+          </Button>
+        ) : null}
+      </div>
+    </div>
+  );
+}

package/src/components/field.tsx

@@ -6,8 +6,8 @@
  * `aria-describedby`, and its `aria-invalid` stay wired without the caller
  * threading ids by hand.
  */
-import { createContext, useContext, useId } from 'react';
 import type { CSSProperties, ReactNode } from 'react';
+import { createContext, useContext, useId } from 'react';
 
 import { XCircleIcon } from './icons';
 

package/src/components/fleet-report.tsx

@@ -27,10 +27,14 @@
  * icon MARK plus a word LABEL, with the tone color only reinforcing them, so the
  * report is readable without color perception.
  */
+import type {
+  FleetFailureOutcome,
+  FleetReportSummary,
+  FleetWorkerFailure,
+} from '@tai42/api-client';
 import type { ReactNode } from 'react';
-import type { FleetReportSummary, FleetFailureOutcome } from '@tai42/api-client';
 
-import { AlertTriangleIcon, PendingIcon, XCircleIcon, type IconComponent } from './icons';
+import { AlertTriangleIcon, type IconComponent, PendingIcon, XCircleIcon } from './icons';
 
 /** Human labels for the per-worker non-applied outcomes. */
 const OUTCOME_LABEL: Record<FleetFailureOutcome, string> = {
@@ -86,62 +90,75 @@ export interface FleetReportProps {
   readonly action?: 'save' | 'reload' | 'deregister' | 'remove';
 }
 
-export function FleetReport({ summary, action = 'save' }: FleetReportProps): ReactNode {
-  if (summary === null || summary.status === 'converged') return null;
-
-  // Only a saved config change carries the "Change saved" framing; a reload or a
-  // deregister saved nothing.
-  const savedFraming = action === 'save';
+type FleetAction = NonNullable<FleetReportProps['action']>;
 
-  if (summary.status === 'unreachable') {
-    // Where to send the operator once the bus is back: re-run the same op, except a
-    // saved change reloads from the System page.
-    const unreachableRemediation =
-      action === 'deregister'
-        ? 'Re-run the deregister once the bus is back.'
-        : action === 'remove'
-          ? 'Re-run the remove once the bus is back.'
-          : action === 'reload'
-            ? 'Re-run the reload once the bus is back.'
-            : 'Re-run the reload from the System page once the bus is back.';
-    return (
-      <div role="alert" className="tai-error-state tai-stack tai-stack-2">
-        <strong className="tai-status tai-status-err">
-          <XCircleIcon />
-          {savedFraming
-            ? 'Change saved, but the worker fleet was not reached'
-            : 'The worker fleet was not reached'}
-        </strong>
-        <p>
-          {`The worker bus was unreachable, so other workers may still be running the old config. ${unreachableRemediation}`}
-        </p>
-        {/* The bus error is a message, not a listing: it wraps rather than scrolls. */}
-        {summary.error !== null ? (
-          <p className="tai-code-block tai-code-block-wrap">{summary.error}</p>
-        ) : null}
-      </div>
-    );
+/**
+ * Where to send the operator, per action and phase. On `unreachable` the copy
+ * is a full sentence ending "once the bus is back."; on `degraded` it is the
+ * verb phrase spliced into the sentence the panel builds. A saved change reloads
+ * from the System page; a detach re-runs itself, since a reload would re-attach.
+ */
+function remediationText(action: FleetAction, phase: FleetReportStatusPhase): string {
+  if (phase === 'unreachable') {
+    if (action === 'deregister') return 'Re-run the deregister once the bus is back.';
+    if (action === 'remove') return 'Re-run the remove once the bus is back.';
+    if (action === 'reload') return 'Re-run the reload once the bus is back.';
+    return 'Re-run the reload from the System page once the bus is back.';
   }
+  if (action === 'deregister') return 're-run the deregister';
+  if (action === 'remove') return 're-run the remove';
+  if (action === 'reload') return 're-run the reload';
+  return 'reload the fleet from the System page';
+}
+
+type FleetReportStatusPhase = 'unreachable' | 'degraded';
+
+/** The loud panel for a bus that could not be reached: no sibling was told. */
+function UnreachableReport({
+  error,
+  savedFraming,
+  remediation,
+}: {
+  readonly error: string | null;
+  readonly savedFraming: boolean;
+  readonly remediation: string;
+}): ReactNode {
+  return (
+    <div role="alert" className="tai-error-state tai-stack tai-stack-2">
+      <strong className="tai-status tai-status-err">
+        <XCircleIcon />
+        {savedFraming
+          ? 'Change saved, but the worker fleet was not reached'
+          : 'The worker fleet was not reached'}
+      </strong>
+      <p>
+        {`The worker bus was unreachable, so other workers may still be running the old config. ${remediation}`}
+      </p>
+      {/* The bus error is a message, not a listing: it wraps rather than scrolls. */}
+      {error !== null ? <p className="tai-code-block tai-code-block-wrap">{error}</p> : null}
+    </div>
+  );
+}
 
-  // degraded — the bus was reached but named workers did not converge. That is a
-  // warning, not a failure, so it takes the warning surface: a warn-toned
-  // headline inside an error-toned panel would state two different severities.
-  //
-  // A count and its noun agree. `worker(s)` is machine output at the one moment
-  // an operator is being told something went wrong, and a single unconverged
-  // worker is the commonest degraded fleet there is.
-  const count = summary.failures.length;
+/**
+ * The loud panel for a reachable bus whose named workers did not converge. A
+ * warning, not a failure, so it takes the warning surface: a warn-toned headline
+ * inside an error-toned panel would state two different severities.
+ */
+function DegradedReport({
+  failures,
+  savedFraming,
+  remediation,
+}: {
+  readonly failures: readonly FleetWorkerFailure[];
+  readonly savedFraming: boolean;
+  readonly remediation: string;
+}): ReactNode {
+  // A count and its noun agree. `worker(s)` is machine output at the one moment an
+  // operator is being told something went wrong, and a single unconverged worker
+  // is the commonest degraded fleet there is.
+  const count = failures.length;
   const workers = `${String(count)} worker${count === 1 ? '' : 's'}`;
-  // How the operator converges the stranded workers: re-run the same op, except a
-  // saved change reloads the fleet from the System page.
-  const remediation =
-    action === 'deregister'
-      ? 're-run the deregister'
-      : action === 'remove'
-        ? 're-run the remove'
-        : action === 'reload'
-          ? 're-run the reload'
-          : 'reload the fleet from the System page';
   return (
     <div role="alert" className="tai-warn-state tai-stack tai-stack-2">
       <strong className="tai-status tai-status-warn">
@@ -156,7 +173,7 @@ export function FleetReport({ summary, action = 'save' }: FleetReportProps): Rea
           ` to converge ${count === 1 ? 'it' : 'them'}.`}
       </p>
       <ul className="tai-stack tai-stack-2">
-        {summary.failures.map((failure) => {
+        {failures.map((failure) => {
           const { tone, Icon } = OUTCOME_STATUS[failure.outcome];
           return (
             <li key={failure.name} className="tai-row">
@@ -175,3 +192,29 @@ export function FleetReport({ summary, action = 'save' }: FleetReportProps): Rea
     </div>
   );
 }
+
+export function FleetReport({ summary, action = 'save' }: FleetReportProps): ReactNode {
+  if (summary === null || summary.status === 'converged') return null;
+
+  // Only a saved config change carries the "Change saved" framing; a reload or a
+  // deregister saved nothing.
+  const savedFraming = action === 'save';
+
+  if (summary.status === 'unreachable') {
+    return (
+      <UnreachableReport
+        error={summary.error}
+        savedFraming={savedFraming}
+        remediation={remediationText(action, 'unreachable')}
+      />
+    );
+  }
+
+  return (
+    <DegradedReport
+      failures={summary.failures}
+      savedFraming={savedFraming}
+      remediation={remediationText(action, 'degraded')}
+    />
+  );
+}

package/src/components/folder-nav.tsx

@@ -13,12 +13,12 @@
  * BOTH consuming screens through this one component — never a flows-page-only
  * affordance.
  */
-import { useState, type ReactNode } from 'react';
+import { type ReactNode, useState } from 'react';
 
 import { ChevronRightIcon, FolderIcon } from './icons';
+import { TextInput } from './inputs';
 import { Button } from './primitives';
 import { Select } from './select';
-import { TextInput } from './inputs';
 
 /** A folder in the tree, in the SDK's camelCase UI shape (`parentId`, `null` = root). */
 export interface Folder {

package/src/components/form-dialog.tsx

@@ -12,11 +12,11 @@
  * (Cancel, Escape, overlay) calls `onClose`. `submitDisabled` blocks submission by
  * click AND by Enter — a disabled default button is not an implicit-submission target.
  */
-import { useEffect, useRef, useState, type ReactNode, type SyntheticEvent } from 'react';
+import { type ReactNode, type SyntheticEvent, useEffect, useRef, useState } from 'react';
 
+import { errorMessage } from '../errors';
 import { Dialog } from './dialog';
 import { Button, ErrorState, Spinner } from './primitives';
-import { errorMessage } from '../errors';
 
 export interface FormDialogProps {
   readonly title: string;