@tai42/studio-sdk 16.0.0 → 17.0.0

package/src/components/tool-picker.tsx

@@ -33,15 +33,10 @@
  */
 import { useState } from 'react';
 
-import { toolDisplayLabel } from '../hooks/useToolDisplayNames';
-import { Badge } from './badge';
 import { Field } from './field';
-import { Select, type SelectGroup } from './select';
-import { Tooltip } from './tooltip';
+import { ALL_TAGS, SelectedToolBadges, TagFilterField, ToolSelect } from './tool-picker-parts';
 
-/** The shared informational note every badge surface carries: declared, never enforced. */
-export const BADGES_NOTE =
-  'Declared capability labels — informational only. They describe what the tool touches; the server never enforces them.';
+export { BADGES_NOTE } from './tool-picker-parts';
 
 export interface ToolPickerProps {
   readonly toolNames: readonly string[];
@@ -79,61 +74,6 @@ export interface ToolPickerProps {
   readonly badgesByTool?: Readonly<Record<string, readonly string[]>>;
 }
 
-const NO_DISPLAY_NAMES: Readonly<Record<string, string>> = {};
-const UNTAGGED = 'Untagged';
-// Radix `Select.Item` forbids an empty-string value, so the "no filter" choice
-// uses a sentinel rather than ''. A tool literally tagged this string would just
-// never be filtered out — harmless for a UI convenience whose authority is the server.
-const ALL_TAGS = '__all_tags__';
-
-/** The group a tool sorts into: its alphabetically-first tag, else "Untagged". */
-function groupFor(name: string, tagsByTool: Readonly<Record<string, readonly string[]>>): string {
-  const tags = [...(tagsByTool[name] ?? [])].sort((a, b) => a.localeCompare(b));
-  return tags[0] ?? UNTAGGED;
-}
-
-/**
- * The option label: `Display Name (raw)` when a distinct non-empty display name maps
- * the name, else the bare name; either way suffixed " (agent)" for an agent run tool.
- */
-function optionLabel(
-  name: string,
-  displayNames: Readonly<Record<string, string>> | undefined,
-  agentToolNames: ReadonlySet<string> | undefined,
-): string {
-  const base = toolDisplayLabel(displayNames ?? NO_DISPLAY_NAMES, name);
-  return agentToolNames?.has(name) === true ? `${base} (agent)` : base;
-}
-
-/** Build the grouped option clusters (sorted group labels, "Untagged" last). */
-function buildGroups(
-  names: readonly string[],
-  tagsByTool: Readonly<Record<string, readonly string[]>>,
-  displayNames: Readonly<Record<string, string>> | undefined,
-  agentToolNames: ReadonlySet<string> | undefined,
-): SelectGroup[] {
-  const byGroup = new Map<string, string[]>();
-  for (const name of names) {
-    const group = groupFor(name, tagsByTool);
-    const bucket = byGroup.get(group) ?? [];
-    bucket.push(name);
-    byGroup.set(group, bucket);
-  }
-  return [...byGroup.entries()]
-    .sort(([a], [b]) => {
-      if (a === UNTAGGED) return 1;
-      if (b === UNTAGGED) return -1;
-      return a.localeCompare(b);
-    })
-    .map(([label, groupNames]) => ({
-      label,
-      options: groupNames.map((name) => ({
-        value: name,
-        label: optionLabel(name, displayNames, agentToolNames),
-      })),
-    }));
-}
-
 export function ToolPicker({
   toolNames,
   value,
@@ -167,64 +107,32 @@ export function ToolPicker({
       ? available.filter((name) => (tagsByTool[name] ?? []).includes(tagFilter))
       : available;
 
-  const toolSelect =
-    tagsByTool !== undefined ? (
-      <Select
-        groups={buildGroups(filtered, tagsByTool, displayNames, agentToolNames)}
-        value={value ?? ''}
-        onValueChange={onChange}
-        placeholder={placeholder}
-        aria-label={ariaLabel}
-        disabled={disabled}
-      />
-    ) : (
-      <Select
-        // Keep Radix controlled even when the caller's value is null: `''` matches no
-        // item (placeholder still shows) and avoids the uncontrolled→controlled warning
-        // a subsequent selection would otherwise trigger.
-        options={filtered.map((name) => ({
-          value: name,
-          label: optionLabel(name, displayNames, agentToolNames),
-        }))}
-        value={value ?? ''}
-        onValueChange={onChange}
-        placeholder={placeholder}
-        aria-label={ariaLabel}
-        disabled={disabled}
-      />
-    );
+  const toolSelect = (
+    <ToolSelect
+      tagsByTool={tagsByTool}
+      filtered={filtered}
+      value={value}
+      onChange={onChange}
+      placeholder={placeholder}
+      ariaLabel={ariaLabel}
+      disabled={disabled}
+      displayNames={displayNames}
+      agentToolNames={agentToolNames}
+    />
+  );
 
   return (
     <div data-testid={idPrefix} className="tai-stack tai-stack-2">
       {tagsByTool !== undefined && allTags.length > 0 ? (
-        <Field label="Filter by tag">
-          <Select
-            options={[
-              { value: ALL_TAGS, label: 'All tags' },
-              ...allTags.map((tag) => ({ value: tag, label: tag })),
-            ]}
-            value={tagFilter}
-            onValueChange={setTagFilter}
-            disabled={disabled}
-          />
-        </Field>
+        <TagFilterField
+          allTags={allTags}
+          tagFilter={tagFilter}
+          onTagFilterChange={setTagFilter}
+          disabled={disabled}
+        />
       ) : null}
       {label !== undefined ? <Field label={label}>{toolSelect}</Field> : toolSelect}
-      {value !== null && badgesByTool !== undefined && (badgesByTool[value]?.length ?? 0) > 0 ? (
-        <Tooltip content={BADGES_NOTE}>
-          <span
-            className="tai-row"
-            data-testid={`${idPrefix}-badges`}
-            style={{ gap: 'var(--tai-space-1)' }}
-          >
-            {(badgesByTool[value] ?? []).map((badge) => (
-              <Badge key={badge} variant="neutral">
-                {badge}
-              </Badge>
-            ))}
-          </span>
-        </Tooltip>
-      ) : null}
+      <SelectedToolBadges value={value} badgesByTool={badgesByTool} idPrefix={idPrefix} />
     </div>
   );
 }

package/src/components/version-history-panel.tsx

@@ -25,18 +25,21 @@
  * machine voice (`tai-table-id` / `tai-mono`). The table itself sits in a
  * `ScrollRegion` so a narrow viewport scrolls it instead of the page.
  */
-import { useEffect, useRef, useState, type ReactNode } from 'react';
+import { type ReactNode, useEffect, useRef, useState } from 'react';
 
 import { errorMessage } from '../errors';
 import { Dialog } from './dialog';
 import { Field } from './field';
-import { CheckCircleIcon, PendingIcon } from './icons';
-import { JsonDiff } from './json-diff';
-import { JsonTree } from './json-tree';
 import { Button, Card, ErrorState, Spinner } from './primitives';
 import { ScrollRegion } from './scroll-region';
-import { Table, TBody, TD, TH, THead, TR } from './table';
-import { TagChips, TagsInput } from './tags';
+import { Table, TBody, TH, THead, TR } from './table';
+import { TagsInput } from './tags';
+import {
+  CompareDialog,
+  RollbackConfirmDialog,
+  SelectedVersionBody,
+  VersionRow,
+} from './version-history-rows';
 
 /** One version row — the kind-agnostic shape every consumer projects into. */
 export interface VersionHistoryEntry {
@@ -235,85 +238,19 @@ export function VersionHistoryPanel({
             </THead>
             <TBody>
               {versions.map((entry) => (
-                <TR key={entry.version} data-testid={`version-row-${String(entry.version)}`}>
-                  <TD className="tai-table-id" numeric>
-                    {entry.version}
-                  </TD>
-                  <TD className="tai-mono">{entry.created_at}</TD>
-                  <TD>
-                    {entry.is_current ? (
-                      <span className="tai-status tai-status-ok">
-                        <CheckCircleIcon />
-                        Current
-                      </span>
-                    ) : (
-                      <span className="tai-status tai-status-pending">
-                        <PendingIcon />
-                        Historical
-                      </span>
-                    )}
-                  </TD>
-                  {showTags ? (
-                    <TD>
-                      {(entry.tags ?? []).length > 0 ? (
-                        <TagChips tags={entry.tags ?? []} />
-                      ) : (
-                        <span className="tai-muted">—</span>
-                      )}
-                    </TD>
-                  ) : null}
-                  <TD>
-                    <div className="tai-row">
-                      <Button
-                        aria-label={`View version ${String(entry.version)}`}
-                        onClick={() => {
-                          view(entry.version);
-                        }}
-                      >
-                        View
-                      </Button>
-                      {canCompare ? (
-                        <Button
-                          // The name starts with the word the button is SHOWING,
-                          // which is what WCAG 2.5.3 (Label in Name) asks: a constant
-                          // "Compare …" would leave a button reading "Comparing…"
-                          // named "Compare", and a voice-control user naming a control
-                          // they cannot see. The button stays ENABLED while armed —
-                          // unlike an Edit action, a second click on the armed row is
-                          // the disarm, so there is nothing to take away.
-                          aria-label={`${compareFrom === entry.version ? 'Comparing' : 'Compare'} version ${String(entry.version)}`}
-                          onClick={() => {
-                            compare(entry.version);
-                          }}
-                        >
-                          {compareFrom === entry.version ? 'Comparing…' : 'Compare'}
-                        </Button>
-                      ) : null}
-                      {onEditTags !== undefined && !readOnly ? (
-                        <Button
-                          aria-label={`Edit tags for version ${String(entry.version)}`}
-                          onClick={() => {
-                            setEditingTags(entry.version);
-                          }}
-                        >
-                          Edit tags
-                        </Button>
-                      ) : null}
-                      {readOnly ? null : (
-                        <Button
-                          variant="secondary"
-                          aria-label={`Roll back to version ${String(entry.version)}`}
-                          disabled={entry.is_current}
-                          onClick={() => {
-                            setConfirming(entry.version);
-                          }}
-                        >
-                          Roll back
-                        </Button>
-                      )}
-                    </div>
-                  </TD>
-                </TR>
+                <VersionRow
+                  key={entry.version}
+                  entry={entry}
+                  showTags={showTags}
+                  canCompare={canCompare}
+                  compareArmed={compareFrom === entry.version}
+                  readOnly={readOnly}
+                  canEditTags={onEditTags !== undefined}
+                  onView={view}
+                  onCompare={compare}
+                  onEditTags={setEditingTags}
+                  onRollback={setConfirming}
+                />
               ))}
             </TBody>
           </Table>
@@ -326,35 +263,16 @@ export function VersionHistoryPanel({
         </p>
       ) : null}
 
-      {selectedEntry !== undefined ? (
-        <section className="tai-stack tai-stack-2">
-          <h3 className="tai-section-title">Version {selectedEntry.version} body</h3>
-          <Card>
-            <JsonTree
-              data={selectedEntry.body}
-              label={`Version ${String(selectedEntry.version)} body`}
-            />
-          </Card>
-        </section>
-      ) : null}
+      {selectedEntry !== undefined ? <SelectedVersionBody entry={selectedEntry} /> : null}
 
       {comparePair !== null ? (
-        <Dialog
-          title={`v${String(comparePair.from)} compared with v${String(comparePair.to)}`}
-          description="A structural diff of the two version bodies. Arrays compare whole."
-          open
-          onOpenChange={(next) => {
-            if (!next) closeCompare();
-          }}
-        >
-          {/* A deep diff row can run wider than the dialog; it scrolls in place. */}
-          <ScrollRegion label="Version diff">
-            <JsonDiff before={fromBody} after={toBody} />
-          </ScrollRegion>
-          <div className="tai-dialog-actions">
-            <Button onClick={closeCompare}>Close</Button>
-          </div>
-        </Dialog>
+        <CompareDialog
+          from={comparePair.from}
+          to={comparePair.to}
+          fromBody={fromBody}
+          toBody={toBody}
+          onClose={closeCompare}
+        />
       ) : null}
 
       {editingEntry !== undefined && onEditTags !== undefined ? (
@@ -369,38 +287,16 @@ export function VersionHistoryPanel({
       ) : null}
 
       {confirming !== null ? (
-        <Dialog
-          title="Roll back version"
-          description={
-            `Make version ${String(confirming)} the active version? The version history is preserved.` +
-            (rollbackConfirmDescription !== undefined ? ` ${rollbackConfirmDescription}` : '')
-          }
-          open
-          onOpenChange={(next) => {
-            if (!next) setConfirming(null);
+        <RollbackConfirmDialog
+          version={confirming}
+          rollbackPending={rollbackPending}
+          rollbackError={rollbackError}
+          extraDescription={rollbackConfirmDescription}
+          onCancel={() => {
+            setConfirming(null);
           }}
-        >
-          {rollbackError !== undefined ? <ErrorState message={rollbackError} /> : null}
-          <div className="tai-dialog-actions">
-            <Button
-              onClick={() => {
-                setConfirming(null);
-              }}
-            >
-              Cancel
-            </Button>
-            <Button
-              variant="primary"
-              disabled={rollbackPending}
-              onClick={() => {
-                onRollback(confirming);
-              }}
-            >
-              {rollbackPending ? <Spinner label="Rolling back" /> : null}
-              Roll back
-            </Button>
-          </div>
-        </Dialog>
+          onConfirm={onRollback}
+        />
       ) : null}
     </div>
   );

package/src/components/version-history-rows.tsx

@@ -0,0 +1,220 @@
+/**
+ * The row and dialog pieces of `VersionHistoryPanel`: one version's table row and
+ * action cluster (`VersionRow`), the selected version's body (`SelectedVersionBody`),
+ * the two-version compare dialog (`CompareDialog`), and the rollback confirm
+ * dialog (`RollbackConfirmDialog`). All generic and kind-agnostic.
+ */
+import type { ReactNode } from 'react';
+
+import { Dialog } from './dialog';
+import { CheckCircleIcon, PendingIcon } from './icons';
+import { JsonDiff } from './json-diff';
+import { JsonTree } from './json-tree';
+import { Button, Card, ErrorState, Spinner } from './primitives';
+import { ScrollRegion } from './scroll-region';
+import { TD, TR } from './table';
+import { TagChips } from './tags';
+import type { VersionHistoryEntry } from './version-history-panel';
+
+interface VersionRowProps {
+  readonly entry: VersionHistoryEntry;
+  readonly showTags: boolean;
+  readonly canCompare: boolean;
+  /** This row is the armed Compare source. */
+  readonly compareArmed: boolean;
+  readonly readOnly: boolean;
+  /** An edit-tags affordance is available (the consumer supplied `onEditTags`). */
+  readonly canEditTags: boolean;
+  readonly onView: (version: number) => void;
+  readonly onCompare: (version: number) => void;
+  readonly onEditTags: (version: number) => void;
+  readonly onRollback: (version: number) => void;
+}
+
+/** One version's row: its number, timestamp, status mark, optional tags, and the
+ *  View / Compare / Edit tags / Roll back action cluster. */
+export function VersionRow({
+  entry,
+  showTags,
+  canCompare,
+  compareArmed,
+  readOnly,
+  canEditTags,
+  onView,
+  onCompare,
+  onEditTags,
+  onRollback,
+}: VersionRowProps): ReactNode {
+  return (
+    <TR data-testid={`version-row-${String(entry.version)}`}>
+      <TD className="tai-table-id" numeric>
+        {entry.version}
+      </TD>
+      <TD className="tai-mono">{entry.created_at}</TD>
+      <TD>
+        {entry.is_current ? (
+          <span className="tai-status tai-status-ok">
+            <CheckCircleIcon />
+            Current
+          </span>
+        ) : (
+          <span className="tai-status tai-status-pending">
+            <PendingIcon />
+            Historical
+          </span>
+        )}
+      </TD>
+      {showTags ? (
+        <TD>
+          {(entry.tags ?? []).length > 0 ? (
+            <TagChips tags={entry.tags ?? []} />
+          ) : (
+            <span className="tai-muted">—</span>
+          )}
+        </TD>
+      ) : null}
+      <TD>
+        <div className="tai-row">
+          <Button
+            aria-label={`View version ${String(entry.version)}`}
+            onClick={() => {
+              onView(entry.version);
+            }}
+          >
+            View
+          </Button>
+          {canCompare ? (
+            <Button
+              // The name starts with the word the button is SHOWING, which is what
+              // WCAG 2.5.3 (Label in Name) asks: a constant "Compare …" would leave a
+              // button reading "Comparing…" named "Compare", and a voice-control user
+              // naming a control they cannot see. The button stays ENABLED while armed
+              // — unlike an Edit action, a second click on the armed row is the disarm,
+              // so there is nothing to take away.
+              aria-label={`${compareArmed ? 'Comparing' : 'Compare'} version ${String(entry.version)}`}
+              onClick={() => {
+                onCompare(entry.version);
+              }}
+            >
+              {compareArmed ? 'Comparing…' : 'Compare'}
+            </Button>
+          ) : null}
+          {canEditTags && !readOnly ? (
+            <Button
+              aria-label={`Edit tags for version ${String(entry.version)}`}
+              onClick={() => {
+                onEditTags(entry.version);
+              }}
+            >
+              Edit tags
+            </Button>
+          ) : null}
+          {readOnly ? null : (
+            <Button
+              variant="secondary"
+              aria-label={`Roll back to version ${String(entry.version)}`}
+              disabled={entry.is_current}
+              onClick={() => {
+                onRollback(entry.version);
+              }}
+            >
+              Roll back
+            </Button>
+          )}
+        </div>
+      </TD>
+    </TR>
+  );
+}
+
+/** The selected version's opaque body, rendered through `JsonTree`. */
+export function SelectedVersionBody({ entry }: { readonly entry: VersionHistoryEntry }): ReactNode {
+  return (
+    <section className="tai-stack tai-stack-2">
+      <h3 className="tai-section-title">Version {entry.version} body</h3>
+      <Card>
+        <JsonTree data={entry.body} label={`Version ${String(entry.version)} body`} />
+      </Card>
+    </section>
+  );
+}
+
+/** A structural diff of two version bodies, in a dialog. */
+export function CompareDialog({
+  from,
+  to,
+  fromBody,
+  toBody,
+  onClose,
+}: {
+  readonly from: number;
+  readonly to: number;
+  readonly fromBody: unknown;
+  readonly toBody: unknown;
+  readonly onClose: () => void;
+}): ReactNode {
+  return (
+    <Dialog
+      title={`v${String(from)} compared with v${String(to)}`}
+      description="A structural diff of the two version bodies. Arrays compare whole."
+      open
+      onOpenChange={(next) => {
+        if (!next) onClose();
+      }}
+    >
+      {/* A deep diff row can run wider than the dialog; it scrolls in place. */}
+      <ScrollRegion label="Version diff">
+        <JsonDiff before={fromBody} after={toBody} />
+      </ScrollRegion>
+      <div className="tai-dialog-actions">
+        <Button onClick={onClose}>Close</Button>
+      </div>
+    </Dialog>
+  );
+}
+
+/** The rollback confirmation, surfacing any rollback failure verbatim. */
+export function RollbackConfirmDialog({
+  version,
+  rollbackPending,
+  rollbackError,
+  extraDescription,
+  onCancel,
+  onConfirm,
+}: {
+  readonly version: number;
+  readonly rollbackPending: boolean | undefined;
+  readonly rollbackError: string | undefined;
+  readonly extraDescription: string | undefined;
+  readonly onCancel: () => void;
+  readonly onConfirm: (version: number) => void;
+}): ReactNode {
+  return (
+    <Dialog
+      title="Roll back version"
+      description={
+        `Make version ${String(version)} the active version? The version history is preserved.` +
+        (extraDescription !== undefined ? ` ${extraDescription}` : '')
+      }
+      open
+      onOpenChange={(next) => {
+        if (!next) onCancel();
+      }}
+    >
+      {rollbackError !== undefined ? <ErrorState message={rollbackError} /> : null}
+      <div className="tai-dialog-actions">
+        <Button onClick={onCancel}>Cancel</Button>
+        <Button
+          variant="primary"
+          disabled={rollbackPending}
+          onClick={() => {
+            onConfirm(version);
+          }}
+        >
+          {rollbackPending ? <Spinner label="Rolling back" /> : null}
+          Roll back
+        </Button>
+      </div>
+    </Dialog>
+  );
+}

package/src/components/view-toggle.tsx

@@ -9,7 +9,7 @@
  * {@link useViewMode}. The two live in the SDK so every entity screen (and the
  * flows page) toggles identically; `EntityCardGrid` renders the card half.
  */
-import { useCallback, useState, type ReactNode } from 'react';
+import { type ReactNode, useCallback, useState } from 'react';
 
 import { GridIcon, MenuIcon } from './icons';
 import { RadioGroup } from './radio-group';

package/src/element-slot.ts

@@ -9,8 +9,8 @@
  * onto it: the opener renders, carries no `aria-haspopup`/`aria-expanded`/
  * `aria-controls` and no handler, and fails nothing.
  */
-import { Fragment } from 'react';
 import type { ReactElement } from 'react';
+import { Fragment } from 'react';
 
 /** Raises when an `asChild` slot is handed a fragment. `slot` names the prop. */
 export function assertSlotElement(element: ReactElement, slot: string): void {

package/src/guards.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared runtime type guards. Internal to studio-sdk — never re-exported from
+ * `index.ts` or any subpath, so it stays off the public plugin surface.
+ */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}