@tai42/studio-sdk 16.0.0 → 17.0.0

package/src/components/templated-text-kwargs-editor.tsx

@@ -0,0 +1,147 @@
+/**
+ * The render-parameters UI for `TemplatedTextField`: the add/remove editor
+ * (`KwargsEditor`) for editable values, and the read-only listing
+ * (`ReadOnlyKwargs`) shown beside a read-only stored id.
+ */
+import { type ReactNode, useState } from 'react';
+
+import { CloseIcon } from './icons';
+import { TextInput } from './inputs';
+import { Button } from './primitives';
+import type { KwargRow } from './templated-text-kwargs';
+
+/** The add/remove kwargs editor, revealed on demand and open when kwargs already exist. */
+export function KwargsEditor({
+  label,
+  rows,
+  disabled,
+  onChange,
+}: {
+  readonly label: string;
+  readonly rows: readonly KwargRow[];
+  readonly disabled: boolean;
+  readonly onChange: (rows: KwargRow[]) => void;
+}): ReactNode {
+  const [open, setOpen] = useState(rows.length > 0);
+  const groupLabel = `${label} render parameters`;
+
+  if (!open) {
+    // Wrapped so the ghost button keeps its content width and stays left-aligned
+    // in the field's column, marking it as this field's own disclosure rather than
+    // a full-width control floating between two fields.
+    return (
+      <div>
+        <Button
+          type="button"
+          variant="ghost"
+          disabled={disabled}
+          onClick={() => {
+            setOpen(true);
+            onChange([...rows, { key: '', value: '' }]);
+          }}
+        >
+          Add render parameters
+        </Button>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      role="group"
+      aria-label={groupLabel}
+      style={{ display: 'flex', flexDirection: 'column', gap: 'var(--tai-space-2)' }}
+    >
+      <span style={{ fontSize: 'var(--tai-text-sm)', color: 'var(--tai-color-text-muted)' }}>
+        Render parameters
+      </span>
+      {rows.map((row, index) => (
+        <div
+          key={index}
+          style={{ display: 'flex', gap: 'var(--tai-space-2)', alignItems: 'center' }}
+        >
+          <TextInput
+            aria-label={`${groupLabel} key ${String(index + 1)}`}
+            placeholder="name"
+            value={row.key}
+            autoComplete="off"
+            disabled={disabled}
+            onChange={(event) => {
+              const next = [...rows];
+              next[index] = { ...row, key: event.target.value };
+              onChange(next);
+            }}
+          />
+          <TextInput
+            aria-label={`${groupLabel} value ${String(index + 1)}`}
+            placeholder="value"
+            value={row.value}
+            autoComplete="off"
+            disabled={disabled}
+            onChange={(event) => {
+              const next = [...rows];
+              next[index] = { ...row, value: event.target.value };
+              onChange(next);
+            }}
+          />
+          <Button
+            type="button"
+            variant="ghost"
+            aria-label={`Remove ${groupLabel} ${String(index + 1)}`}
+            disabled={disabled}
+            onClick={() => {
+              onChange(rows.filter((_, position) => position !== index));
+            }}
+          >
+            <CloseIcon aria-hidden="true" />
+          </Button>
+        </div>
+      ))}
+      <div>
+        <Button
+          type="button"
+          variant="ghost"
+          disabled={disabled}
+          onClick={() => {
+            onChange([...rows, { key: '', value: '' }]);
+          }}
+        >
+          Add parameter
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * The render parameters of a read-only stored value, as read-only text — the
+ * values in normal weight, NOT the muted disabled inputs a reader could mistake
+ * for empty placeholders. Renders nothing when there are no kwargs.
+ */
+export function ReadOnlyKwargs({
+  label,
+  rows,
+}: {
+  readonly label: string;
+  readonly rows: readonly KwargRow[];
+}): ReactNode {
+  if (rows.length === 0) return null;
+  return (
+    <div
+      role="group"
+      aria-label={`${label} render parameters`}
+      style={{ display: 'flex', flexDirection: 'column', gap: 'var(--tai-space-1)' }}
+    >
+      <span style={{ fontSize: 'var(--tai-text-sm)', color: 'var(--tai-color-text-muted)' }}>
+        Render parameters
+      </span>
+      {rows.map((row) => (
+        <div key={row.key} style={{ fontFamily: 'var(--tai-font-mono)', wordBreak: 'break-all' }}>
+          <code>{row.key}</code>
+          <span style={{ color: 'var(--tai-color-text-muted)' }}>: </span>
+          <code>{row.value}</code>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/templated-text-kwargs.ts

@@ -0,0 +1,92 @@
+/**
+ * The render-kwargs model behind `TemplatedTextField`: the row shape, the
+ * round-trip between stored kwargs and editable rows, and the normalized
+ * `TemplatedText` value the field emits. Pure — no React.
+ */
+import type { TemplatedText } from '@tai42/api-client';
+
+/** Whether the value's source is inline authored text or a stored template id. */
+export type Mode = 'inline' | 'stored';
+
+export interface KwargRow {
+  readonly key: string;
+  readonly value: string;
+  /**
+   * The stored value this row was seeded from, kept so an UNTOUCHED row re-emits it
+   * BYTE-FOR-BYTE: the row form cannot tell a stored string `"7"` from the number `7`,
+   * so re-parsing an untouched row would silently coerce the stored type. `undefined`
+   * for a row the author added.
+   */
+  readonly original?: unknown;
+}
+
+/** The row's canonical string form, matched against `value` to detect an untouched row. */
+export function stringifyRowValue(raw: unknown): string {
+  return typeof raw === 'string' ? raw : JSON.stringify(raw);
+}
+
+/** Parse a cell as JSON when it can be (numbers/bools/objects), else keep the string. */
+export function parseCellValue(raw: string): unknown {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return '';
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return raw;
+  }
+}
+
+/** Collapse the kwargs rows into an object, dropping rows with a blank key. */
+export function rowsToObject(rows: readonly KwargRow[]): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const row of rows) {
+    const key = row.key.trim();
+    if (key.length === 0) continue;
+    // An untouched seeded row re-emits its stored value verbatim (no JSON-type coerce);
+    // an edited or added row is parsed from the cell text.
+    out[key] =
+      row.original !== undefined && stringifyRowValue(row.original) === row.value
+        ? row.original
+        : parseCellValue(row.value);
+  }
+  return out;
+}
+
+/** Seed rows from a stored kwargs object (stringifying non-string values). */
+export function objectToRows(kwargs: Record<string, unknown> | undefined): KwargRow[] {
+  if (kwargs === undefined) return [];
+  return Object.entries(kwargs).map(([key, raw]) => ({
+    key,
+    value: stringifyRowValue(raw),
+    original: raw,
+  }));
+}
+
+/** The initial mode: stored when the seed carries an `id`, inline otherwise. */
+export function initialMode(value: TemplatedText | null): Mode {
+  return value?.id !== undefined ? 'stored' : 'inline';
+}
+
+/**
+ * The normalized value for a given source/mode and kwargs. The two sources are
+ * mutually exclusive by construction (`content` XOR `id`); an empty source emits
+ * `null` unless `required`, in which case an empty source is emitted so the
+ * schema guard refuses the save.
+ */
+export function templatedValueFrom(
+  mode: Mode,
+  inline: string,
+  stored: string,
+  rows: readonly KwargRow[],
+  required: boolean,
+): TemplatedText | null {
+  const kwargs = rowsToObject(rows);
+  const kw = Object.keys(kwargs).length > 0 ? { kwargs } : {};
+  if (mode === 'stored') {
+    const id = stored.trim();
+    if (id === '') return required ? { id: '', ...kw } : null;
+    return { id, ...kw };
+  }
+  if (inline.trim() === '') return required ? { content: '', ...kw } : null;
+  return { content: inline, ...kw };
+}

package/src/components/templated-text-source.tsx

@@ -0,0 +1,226 @@
+/**
+ * The source region of `TemplatedTextField`: the inline/stored toggle and its
+ * editors while storage is present, a stand-in while presence is unknown, and the
+ * read-only stored reference (never converted, dropped, or blanked) when storage
+ * is absent.
+ */
+import type { ReactNode } from 'react';
+
+import { Field } from './field';
+import { Textarea } from './inputs';
+import { ErrorState, Skeleton } from './primitives';
+import { RadioGroup } from './radio-group';
+import { Select } from './select';
+import type { TemplatedTextInlineProps, TemplatedTextTemplateOption } from './templated-text-field';
+import type { Mode } from './templated-text-kwargs';
+
+/** A labeled read-only reference to a stored template id, plus the note that
+ *  stored templates are unavailable here — NOT an editable field. */
+function ReadOnlyStoredReference({ id }: { readonly id: string }): ReactNode {
+  return (
+    <>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--tai-space-1)' }}>
+        <span style={{ fontSize: 'var(--tai-text-sm)', color: 'var(--tai-color-text-muted)' }}>
+          Stored template
+        </span>
+        <code style={{ fontFamily: 'var(--tai-font-mono)', wordBreak: 'break-all' }}>{id}</code>
+      </div>
+      <p
+        style={{ margin: 0, fontSize: 'var(--tai-text-sm)', color: 'var(--tai-color-text-muted)' }}
+      >
+        Stored templates are unavailable — this deployment has no storage backend.
+      </p>
+    </>
+  );
+}
+
+interface PresentStorageSourceProps {
+  readonly label: string;
+  readonly mode: Mode;
+  readonly disabled: boolean;
+  readonly inlineEditor: ReactNode;
+  readonly error?: string;
+  readonly storedDraft: string;
+  readonly templates: readonly TemplatedTextTemplateOption[];
+  readonly templateOptions: readonly { value: string; label: string }[];
+  readonly templatesLoading: boolean;
+  readonly templatesError?: string;
+  readonly onTemplatesRetry?: () => void;
+  readonly unresolvedId?: string;
+  readonly resolveError?: string;
+  readonly onModeChange: (mode: Mode) => void;
+  readonly onStoredChange: (stored: string) => void;
+}
+
+/** The inline/stored toggle, the mode's editor, and the unresolved-id note, for
+ *  the storage-present configuration. */
+function PresentStorageSource({
+  label,
+  mode,
+  disabled,
+  inlineEditor,
+  error,
+  storedDraft,
+  templates,
+  templateOptions,
+  templatesLoading,
+  templatesError,
+  onTemplatesRetry,
+  unresolvedId,
+  resolveError,
+  onModeChange,
+  onStoredChange,
+}: PresentStorageSourceProps): ReactNode {
+  return (
+    <>
+      <RadioGroup
+        aria-label={`${label} source`}
+        variant="segmented"
+        value={mode}
+        disabled={disabled}
+        options={[
+          { value: 'inline', label: 'Inline text' },
+          { value: 'stored', label: 'Stored template' },
+        ]}
+        onValueChange={(next) => {
+          onModeChange(next as Mode);
+        }}
+      />
+
+      {mode === 'inline' ? (
+        inlineEditor
+      ) : templatesError !== undefined ? (
+        <ErrorState message={templatesError} onRetry={onTemplatesRetry} />
+      ) : templatesLoading ? (
+        <Skeleton height={36} />
+      ) : (
+        <Field label={label} hideLabel error={error}>
+          <Select
+            placeholder={templates.length === 0 ? 'No templates available' : 'Select a template'}
+            value={storedDraft}
+            disabled={disabled || templates.length === 0}
+            options={templateOptions}
+            onValueChange={onStoredChange}
+          />
+        </Field>
+      )}
+
+      {unresolvedId !== undefined ? (
+        <p role="alert" style={{ margin: 0, color: 'var(--tai-color-err-text)' }}>
+          {resolveError ?? `The stored template "${unresolvedId}" is not available.`}
+        </p>
+      ) : null}
+    </>
+  );
+}
+
+export interface TemplatedTextSourceProps {
+  readonly label: string;
+  readonly mode: Mode;
+  readonly inlineDraft: string;
+  readonly storedDraft: string;
+  readonly error?: string;
+  readonly disabled: boolean;
+  readonly placeholder?: string;
+  readonly renderInline?: (props: TemplatedTextInlineProps) => ReactNode;
+  readonly templates: readonly TemplatedTextTemplateOption[];
+  readonly templatesLoading: boolean;
+  readonly templatesError?: string;
+  readonly onTemplatesRetry?: () => void;
+  readonly resolveError?: string;
+  readonly storageAbsent: boolean;
+  readonly storagePresenceLoading: boolean;
+  /** The `id` already authored on the value, shown read-only when storage is absent. */
+  readonly authoredStoredId?: string;
+  readonly onModeChange: (mode: Mode) => void;
+  readonly onInlineChange: (value: string) => void;
+  readonly onStoredChange: (stored: string) => void;
+}
+
+export function TemplatedTextSource({
+  label,
+  mode,
+  inlineDraft,
+  storedDraft,
+  error,
+  disabled,
+  placeholder,
+  renderInline,
+  templates,
+  templatesLoading,
+  templatesError,
+  onTemplatesRetry,
+  resolveError,
+  storageAbsent,
+  storagePresenceLoading,
+  authoredStoredId,
+  onModeChange,
+  onInlineChange,
+  onStoredChange,
+}: TemplatedTextSourceProps): ReactNode {
+  const templateOptions = templates.map((template) => ({
+    value: template.id,
+    label: template.label ?? template.id,
+  }));
+  // A stored id the catalog does not offer cannot be picked from the list; it is
+  // shown as an unresolved note rather than silently blanked.
+  const unresolvedId =
+    mode === 'stored' &&
+    storedDraft.trim() !== '' &&
+    !templatesLoading &&
+    templatesError === undefined &&
+    !templates.some((template) => template.id === storedDraft.trim())
+      ? storedDraft.trim()
+      : undefined;
+
+  // The inline editor, shared by the present-storage inline mode and the
+  // absent-storage inline-only rendering: the caller's rich editor when supplied,
+  // else a plain textarea.
+  const inlineEditor =
+    renderInline !== undefined ? (
+      renderInline({ label, value: inlineDraft, onChange: onInlineChange, error, hideLabel: true })
+    ) : (
+      <Field label={label} hideLabel error={error}>
+        <Textarea
+          value={inlineDraft}
+          placeholder={placeholder}
+          disabled={disabled}
+          onChange={(event) => {
+            onInlineChange(event.target.value);
+          }}
+        />
+      </Field>
+    );
+
+  // While presence is unknown a placeholder stands in, so the toggle is never
+  // shown and then removed. With storage absent the stored source cannot work and
+  // is not offered: an inline or empty value edits inline; a value carrying an
+  // `id` is shown read-only. With storage present the full toggle and picker render.
+  if (storagePresenceLoading) return <Skeleton height={36} />;
+  if (storageAbsent) {
+    return authoredStoredId !== undefined ? (
+      <ReadOnlyStoredReference id={authoredStoredId} />
+    ) : (
+      inlineEditor
+    );
+  }
+  return (
+    <PresentStorageSource
+      label={label}
+      mode={mode}
+      disabled={disabled}
+      inlineEditor={inlineEditor}
+      error={error}
+      storedDraft={storedDraft}
+      templates={templates}
+      templateOptions={templateOptions}
+      templatesLoading={templatesLoading}
+      templatesError={templatesError}
+      onTemplatesRetry={onTemplatesRetry}
+      unresolvedId={unresolvedId}
+      resolveError={resolveError}
+      onModeChange={onModeChange}
+      onStoredChange={onStoredChange}
+    />
+  );
+}

package/src/components/tool-picker-parts.tsx

@@ -0,0 +1,184 @@
+/**
+ * The pieces of `ToolPicker`: the tool `Select` itself (grouped or flat), the tag
+ * filter field, and the selected tool's capability badges. The picker owns the
+ * state and composes these; the option-label and grouping helpers live here too.
+ */
+import type { ReactNode } 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';
+
+/** 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.';
+
+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.
+export 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),
+      })),
+    }));
+}
+
+interface ToolSelectProps {
+  readonly tagsByTool: Readonly<Record<string, readonly string[]>> | undefined;
+  readonly filtered: readonly string[];
+  readonly value: string | null;
+  readonly onChange: (toolName: string) => void;
+  readonly placeholder: string;
+  readonly ariaLabel: string | undefined;
+  readonly disabled: boolean | undefined;
+  readonly displayNames: Readonly<Record<string, string>> | undefined;
+  readonly agentToolNames: ReadonlySet<string> | undefined;
+}
+
+/** The tool select: grouped by tag when `tagsByTool` is present, else a flat list.
+ *  Either branch is a `Select`, which claims the enclosing `Field`'s control id. */
+export function ToolSelect({
+  tagsByTool,
+  filtered,
+  value,
+  onChange,
+  placeholder,
+  ariaLabel,
+  disabled,
+  displayNames,
+  agentToolNames,
+}: ToolSelectProps): ReactNode {
+  if (tagsByTool !== undefined) {
+    return (
+      <Select
+        groups={buildGroups(filtered, tagsByTool, displayNames, agentToolNames)}
+        value={value ?? ''}
+        onValueChange={onChange}
+        placeholder={placeholder}
+        aria-label={ariaLabel}
+        disabled={disabled}
+      />
+    );
+  }
+  return (
+    <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}
+    />
+  );
+}
+
+/** The tag filter: an "All tags" sentinel plus one option per distinct tag. */
+export function TagFilterField({
+  allTags,
+  tagFilter,
+  onTagFilterChange,
+  disabled,
+}: {
+  readonly allTags: readonly string[];
+  readonly tagFilter: string;
+  readonly onTagFilterChange: (value: string) => void;
+  readonly disabled: boolean | undefined;
+}): ReactNode {
+  return (
+    <Field label="Filter by tag">
+      <Select
+        options={[
+          { value: ALL_TAGS, label: 'All tags' },
+          ...allTags.map((tag) => ({ value: tag, label: tag })),
+        ]}
+        value={tagFilter}
+        onValueChange={onTagFilterChange}
+        disabled={disabled}
+      />
+    </Field>
+  );
+}
+
+/** The selected tool's DECLARED capability badges, read-only and informational.
+ *  Renders nothing unless the selected tool carries badges. */
+export function SelectedToolBadges({
+  value,
+  badgesByTool,
+  idPrefix,
+}: {
+  readonly value: string | null;
+  readonly badgesByTool: Readonly<Record<string, readonly string[]>> | undefined;
+  readonly idPrefix: string;
+}): ReactNode {
+  if (value === null || badgesByTool === undefined || (badgesByTool[value]?.length ?? 0) === 0) {
+    return null;
+  }
+  return (
+    <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>
+  );
+}