@tai42/studio-sdk 0.2.0

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

@@ -0,0 +1,305 @@
+/**
+ * `ExtensionComboBuilder` — a controlled editor for a preset/tool's LIST OF
+ * extension combos. A combo is an ordered list of extension ELEMENTS, each a bare
+ * extension NAME or a `{ name, config }` mapping carrying author config; the value
+ * is the list of combos (`PresetExtensionElement[][]`), the SAME shape the
+ * preset/tool extensions wire carries. It is PRESENTATIONAL: the caller fetches the
+ * extension catalog (`available`) and owns the `value`; this component fetches nothing.
+ *
+ * The surface has two parts:
+ *  - the current combos, each an ordered row of name `Badge`s with a per-combo Edit
+ *    (pull it back into the draft) and Remove;
+ *  - a combo UNDER CONSTRUCTION, authored with the shared `ExtensionPicker` (grouped
+ *    by kind, single-select for the non-stackable `backend` kind). When the draft
+ *    includes the `output_schema` extension, its config is authored inline with a
+ *    `SchemaEditor` (no title required); an "Add combo" / "Update combo" action
+ *    composes the elements — `output_schema` as `{ name, config: { schema } }`, every
+ *    other extension as a bare name — and writes it into the value.
+ *
+ * The builder only blocks the client-trivial invalids: an EMPTY combo (Add is
+ * disabled until the draft has ≥1 member), a DUPLICATE of a combo already in the
+ * value (by name sequence; flagged inline, Add blocked), an INVALID `output_schema`
+ * config (the `SchemaEditor` shows the parse/lint error and Add is blocked), and an
+ * UNKNOWN extension name in an existing combo (a name absent from `available`, which
+ * happens when a plugin is removed after a preset was authored) — flagged inline on
+ * that combo row and reported through `onValidityChange` so the caller can block
+ * submit. Every deeper rule — the registry's one-per-non-stackable-kind constraint,
+ * meta-schema validity, kind/ordering — is SERVER-AUTHORITATIVE: the write route
+ * validates each combo and its 400 message is surfaced verbatim by the caller.
+ *
+ * Loading is signaled by `availableReady`: while the catalog is still loading the
+ * builder reports VALID and suppresses the unknown-name notes (no danger-note flash
+ * while submit stays enabled — the server backstops), so a stale-seeded combo does
+ * not flicker invalid before the catalog resolves.
+ *
+ * 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 { 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';
+
+export interface ExtensionComboBuilderProps {
+  /** The extension catalog the combos are drawn from (caller-fetched). */
+  readonly available: readonly Extension[];
+  /** The current list of combos, each an ordered list of extension elements. */
+  readonly value: readonly PresetExtensionElement[][];
+  /** Fired with the next list of combos on every add/update/remove. */
+  readonly onChange: (next: PresetExtensionElement[][]) => void;
+  readonly disabled?: boolean;
+  readonly idPrefix?: string;
+  /**
+   * Fired (effect-driven) on mount and whenever `value`, `available`, or
+   * `availableReady` changes with whether every combo's names are known. A caller
+   * blocks submit while this is `false`. The `onChange` payload shape is unchanged;
+   * this is a SECOND callback so the prop surface stays backward-compatible.
+   */
+  readonly onValidityChange?: (valid: boolean) => void;
+  /**
+   * Whether the `available` catalog has finished loading. Default `true` (existing
+   * consumers keep today's behavior). While `false` the builder reports VALID and
+   * suppresses the unknown-name notes, so a stale-seeded combo does not flash invalid
+   * before the catalog resolves.
+   */
+  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,
+  onChange,
+  disabled,
+  idPrefix = 'extension-combo-builder',
+  onValidityChange,
+  availableReady = true,
+}: ExtensionComboBuilderProps): ReactNode {
+  const [draft, setDraft] = useState<string[]>([]);
+  const [draftConfig, setDraftConfig] = useState<SchemaEditorChange>({ schema: null, valid: true });
+  // The index of the combo being edited (pulled into the draft), or `null` for a new one.
+  const [editing, setEditing] = useState<number | null>(null);
+
+  const draftHasOutputSchema = draft.includes(OUTPUT_SCHEMA);
+  const isDuplicate =
+    draft.length > 0 &&
+    value.some((combo, index) => index !== editing && sameNames(comboElementNames(combo), draft));
+  const configInvalid = draftHasOutputSchema && !draftConfig.valid;
+  const canAdd = !disabled && draft.length > 0 && !isDuplicate && !configInvalid;
+
+  // Unknown-name validation over the EXISTING combos. Until the catalog is ready the
+  // builder reports VALID and suppresses the notes (no flash on a stale-seeded combo).
+  const availableNames = new Set(available.map((extension) => extension.name));
+  const hasUnknownName =
+    availableReady && value.some((combo) => unknownNames(combo, availableNames).length > 0);
+  const valid = !hasUnknownName;
+
+  useEffect(() => {
+    onValidityChange?.(valid);
+  }, [onValidityChange, valid]);
+
+  const resetDraft = (): void => {
+    setDraft([]);
+    setDraftConfig({ schema: null, valid: true });
+    setEditing(null);
+  };
+
+  /**
+   * Compose the draft names into config-bearing elements. `output_schema` takes the
+   * inline-authored config; every other name keeps the edited combo's existing
+   * element verbatim when it survives — preserving any author `config` (e.g. an
+   * `ask_external` verifier) the builder does not itself author — and a newly-added
+   * name becomes a bare-name element.
+   */
+  const composeCombo = (): PresetExtensionElement[] => {
+    const source = editing === null ? undefined : value[editing];
+    const byName = new Map<string, PresetExtensionElement>();
+    if (source !== undefined) {
+      for (const element of source) byName.set(extensionElementName(element), element);
+    }
+    return draft.map((name) =>
+      name === OUTPUT_SCHEMA
+        ? { name, config: { schema: draftConfig.schema ?? {} } }
+        : (byName.get(name) ?? name),
+    );
+  };
+
+  const commitCombo = (): void => {
+    if (!canAdd) return;
+    const composed = composeCombo();
+    if (editing === null) {
+      onChange([...value.map((combo) => [...combo]), composed]);
+    } else {
+      onChange(value.map((combo, index) => (index === editing ? composed : [...combo])));
+    }
+    resetDraft();
+  };
+
+  const startEdit = (index: number): void => {
+    const combo = value[index];
+    if (combo === undefined) return;
+    setDraft(comboElementNames(combo));
+    setDraftConfig({ schema: outputSchemaConfig(combo), valid: true });
+    setEditing(index);
+  };
+
+  const removeCombo = (index: number): void => {
+    onChange(value.filter((_, i) => i !== index).map((combo) => [...combo]));
+    // Removing the row under edit (or one before it) invalidates the draft target.
+    if (editing !== null && (editing === index || editing > index)) resetDraft();
+  };
+
+  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">
+                  <span className="tai-row">
+                    {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'} combo ${names.join('+')}`}
+                    disabled={disabled === true || editing === index}
+                    onClick={() => {
+                      startEdit(index);
+                    }}
+                  >
+                    {editing === index ? 'Editing' : 'Edit'}
+                  </Button>
+                  <Button
+                    type="button"
+                    aria-label={`Remove combo ${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 combos.</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 combo'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 combo is already added.
+          </p>
+        ) : null}
+
+        <div className="tai-row">
+          <Button type="button" variant="primary" onClick={commitCombo} disabled={!canAdd}>
+            {editing === null ? 'Add combo' : 'Update combo'}
+          </Button>
+          {editing !== null ? (
+            <Button type="button" onClick={resetDraft} disabled={disabled}>
+              Cancel edit
+            </Button>
+          ) : null}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/extension-grouping.ts

@@ -0,0 +1,116 @@
+/**
+ * Pure catalog-shaping helpers for the extensions surface — the SHARED grouping
+ * source for both the read-only extensions catalog (`features/extensions`) and the
+ * `ExtensionPicker`. Kept free of React so the grouping logic is unit-tested
+ * directly.
+ *
+ * The `/api/extensions` catalog is a flat list of `{ name, kind }` entries. Two
+ * independent groupings live here:
+ *  - `groupIntoFamilies` groups a tool's composed branch VARIANTS (which share a
+ *    base tool name and append underscore suffixes — `tool`, `tool_a`, `tool_a_b`)
+ *    back into one FAMILY keyed by that base name (the catalog view);
+ *  - `groupByKind` groups the catalog by extension KIND (the picker view), where
+ *    the `backend` kind is the single non-stackable one.
+ * `kindVariant` maps each serialized `kind` value to a design-system Badge variant.
+ */
+import type { Extension } from '@tai42/api-client';
+
+import type { BadgeProps } from './badge';
+
+/**
+ * The single non-stackable extension kind: at most one `backend` extension may
+ * appear in a combo (the `backend` kind is declared non-stackable, `multiple=False`).
+ * The `ExtensionPicker` enforces single-select for this kind.
+ */
+export const NON_STACKABLE_KIND = 'backend';
+
+/** One base tool and every extension entry that branches from it. */
+export interface ExtensionFamily {
+  /** The base tool name (the segment before the first underscore). */
+  readonly base: string;
+  /** The family's entries, ordered by full name. */
+  readonly members: readonly Extension[];
+}
+
+/** One extension `kind` and every catalog entry of that kind. */
+export interface ExtensionKindGroup {
+  /** The serialized kind value (`wrapper` / `transformer` / `backend`). */
+  readonly kind: string;
+  /** Whether this kind is non-stackable (single-select in the picker). */
+  readonly nonStackable: boolean;
+  /** The kind's entries, ordered by name. */
+  readonly members: readonly Extension[];
+}
+
+/**
+ * The base tool name a variant belongs to: the substring before the first
+ * underscore, or the whole name when it has none. `tool`, `tool_a`, `tool_a_b`
+ * all resolve to `tool`; `x_chain` and `x_batch` both resolve to `x`.
+ */
+export function baseNameOf(name: string): string {
+  const separator = name.indexOf('_');
+  return separator === -1 ? name : name.slice(0, separator);
+}
+
+/**
+ * Group a flat extension list into families keyed by base tool name. Families
+ * are ordered by base name and each family's members by full name, so the render
+ * order is stable regardless of the server's list order.
+ */
+export function groupIntoFamilies(extensions: readonly Extension[]): ExtensionFamily[] {
+  const byBase = new Map<string, Extension[]>();
+  for (const extension of extensions) {
+    const base = baseNameOf(extension.name);
+    const members = byBase.get(base);
+    if (members) {
+      members.push(extension);
+    } else {
+      byBase.set(base, [extension]);
+    }
+  }
+  return [...byBase.entries()]
+    .map(([base, members]) => ({
+      base,
+      members: [...members].sort((a, b) => a.name.localeCompare(b.name)),
+    }))
+    .sort((a, b) => a.base.localeCompare(b.base));
+}
+
+/**
+ * Group a flat extension list by `kind`, for the picker. Groups are ordered by
+ * kind and each group's members by name, so the render order is stable regardless
+ * of the server's list order. The `backend` group is flagged non-stackable.
+ */
+export function groupByKind(extensions: readonly Extension[]): ExtensionKindGroup[] {
+  const byKind = new Map<string, Extension[]>();
+  for (const extension of extensions) {
+    const members = byKind.get(extension.kind);
+    if (members) {
+      members.push(extension);
+    } else {
+      byKind.set(extension.kind, [extension]);
+    }
+  }
+  return [...byKind.entries()]
+    .map(([kind, members]) => ({
+      kind,
+      nonStackable: kind === NON_STACKABLE_KIND,
+      members: [...members].sort((a, b) => a.name.localeCompare(b.name)),
+    }))
+    .sort((a, b) => a.kind.localeCompare(b.kind));
+}
+
+/**
+ * Map a serialized extension `kind` to a Badge variant. Known skeleton kinds get
+ * a themed color; any unrecognized kind falls back to the neutral variant (the
+ * Badge itself also neutral-fallbacks, but choosing here keeps the mapping
+ * explicit and testable).
+ */
+export function kindVariant(kind: string): NonNullable<BadgeProps['variant']> {
+  const known: Record<string, NonNullable<BadgeProps['variant']>> = {
+    wrapper: 'primary',
+    transformer: 'success',
+    backend: 'warning',
+  };
+  return known[kind] ?? 'neutral';
+}

package/src/components/extension-picker.tsx

@@ -0,0 +1,97 @@
+/**
+ * `ExtensionPicker` — a controlled multi-select over the extension catalog
+ * (`GET /api/extensions`), authoring ONE extension combo (an ordered list of
+ * extension names). Built on the DS `Checkbox` so features share one picker
+ * instead of re-implementing a checklist (the same reason `SchemaForm`/`ToolPicker`
+ * live in the SDK). It is PRESENTATIONAL: the caller fetches `available` and owns
+ * the selected `value`; this component fetches nothing.
+ *
+ * The catalog is GROUPED by `kind`. The `backend` kind is the single NON-STACKABLE
+ * one (`multiple=False`), so it is SINGLE-SELECT — checking a backend
+ * extension replaces any other backend already in the combo; every other kind is
+ * freely multi-select. Selection order is preserved (the combo is ordered — the
+ * stacking order that produces the branch tool name), so a newly-checked extension
+ * appends to the end and unchecking removes in place.
+ *
+ * SAFETY: an extension name AND its kind are server-supplied, so every name/kind
+ * renders as TEXT through the DS `Checkbox`/`Badge` (React escapes it) — never an
+ * HTML sink. Pinned by a test.
+ *
+ * Geometry and ink come from the design-system layout classes (`tai-stack`,
+ * `tai-row`, `tai-muted`); the component carries no palette of its own.
+ */
+import type { Extension } from '@tai42/api-client';
+
+import { Badge } from './badge';
+import { Checkbox } from './checkbox';
+import { groupByKind, kindVariant } from './extension-grouping';
+
+export interface ExtensionPickerProps {
+  /** The extension catalog (`GET /api/extensions`) the checklist is drawn from. */
+  readonly available: readonly Extension[];
+  /** The currently-selected extension names, in combo (stacking) order. */
+  readonly value: readonly string[];
+  /** Fired with the next ordered selection whenever a box toggles. */
+  readonly onChange: (names: string[]) => void;
+  readonly disabled?: boolean;
+  readonly idPrefix?: string;
+}
+
+export function ExtensionPicker({
+  available,
+  value,
+  onChange,
+  disabled,
+  idPrefix = 'extension-picker',
+}: ExtensionPickerProps) {
+  const groups = groupByKind(available);
+  const selected = new Set(value);
+
+  /**
+   * Toggle a single extension. For a NON-STACKABLE kind (`backend`), checking one
+   * first strips any other selected member of that kind before appending, so the
+   * combo carries at most one backend; unchecking just removes it. Order is
+   * preserved: a newly-checked name lands at the end.
+   */
+  const toggle = (extension: Extension, nonStackable: boolean, checked: boolean): void => {
+    if (!checked) {
+      onChange(value.filter((name) => name !== extension.name));
+      return;
+    }
+    if (selected.has(extension.name)) return;
+    const siblingNames = nonStackable
+      ? new Set(available.filter((e) => e.kind === extension.kind).map((e) => e.name))
+      : undefined;
+    const kept =
+      siblingNames === undefined ? [...value] : value.filter((name) => !siblingNames.has(name));
+    onChange([...kept, extension.name]);
+  };
+
+  return (
+    <div data-testid={idPrefix} className="tai-stack">
+      {groups.map((group) => (
+        <div key={group.kind} className="tai-stack tai-stack-2">
+          {/* The kind heading is a layout row, not prose: its badge names the kind
+              and the single-select qualifier rides beside it as secondary text. */}
+          <div className="tai-row">
+            <Badge variant={kindVariant(group.kind)}>{group.kind}</Badge>
+            {group.nonStackable ? <span className="tai-muted">(single-select)</span> : null}
+          </div>
+          <div className="tai-row">
+            {group.members.map((extension) => (
+              <Checkbox
+                key={extension.name}
+                label={extension.name}
+                checked={selected.has(extension.name)}
+                disabled={disabled}
+                onCheckedChange={(checked) => {
+                  toggle(extension, group.nonStackable, checked);
+                }}
+              />
+            ))}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/external-link.tsx

@@ -0,0 +1,40 @@
+/**
+ * `ExternalLinkButton` — an open-link action for a URL the Studio did not author
+ * (a registry homepage, an interaction payload's link). Only an ABSOLUTE
+ * `http(s)` URL is navigable here: every other spelling — another scheme, and a
+ * relative reference, which would be a same-origin in-app navigation the caller
+ * never intended — is NEUTRALIZED into plain text with no anchor and no href.
+ * This is an XSS pin.
+ *
+ * The check and the neutralized rendering are `Button`'s; this module chooses the
+ * stricter of the two link policies rather than re-implementing either.
+ */
+import type { ReactNode } from 'react';
+
+import {
+  Button,
+  buttonClass,
+  DEFAULT_BUTTON_VARIANT,
+  isSafeHttpUrl,
+  NeutralizedLink,
+} from './primitives';
+
+export { isSafeHttpUrl } from './primitives';
+
+export interface ExternalLinkButtonProps {
+  readonly url: string;
+  readonly children?: ReactNode;
+}
+
+export function ExternalLinkButton({ url, children }: ExternalLinkButtonProps) {
+  const label = children ?? url;
+  if (!isSafeHttpUrl(url)) {
+    // The same classes the navigable form wears, so the two never drift apart.
+    return (
+      <NeutralizedLink className={buttonClass(DEFAULT_BUTTON_VARIANT, undefined)}>
+        {label}
+      </NeutralizedLink>
+    );
+  }
+  return <Button href={url}>{label}</Button>;
+}