@tai42/studio-sdk 13.3.0 → 15.0.0

package/src/state-binding/InputInjectionRow.tsx

@@ -0,0 +1,157 @@
+/**
+ * The input-injection list of one attached state. Each row injects a value into the
+ * run input BEFORE the run: either a template `input` jq (picked by name) or a
+ * custom jq over the record, placed under the `into` run-input field.
+ */
+import type { ReactNode } from 'react';
+
+import { Button } from '../components/primitives';
+import { Field } from '../components/field';
+import { Select } from '../components/select';
+import { TextInput } from '../components/inputs';
+import { CloseIcon } from '../components/icons';
+import { BindingTemplatedJqField } from './BindingTemplatedJqField';
+import type { TemplateJqSuggestion } from './BindingJqField';
+import type { ResolvedTemplateJq } from './catalog';
+import type { StateInjection, TemplatedTextCatalog } from './types';
+
+function optionLabel(entry: ResolvedTemplateJq): string {
+  return entry.description !== undefined && entry.description !== ''
+    ? `${entry.ref} — ${entry.description}`
+    : entry.ref;
+}
+
+const CUSTOM = '__custom__';
+
+function InjectionRow({
+  injection,
+  index,
+  inputJq,
+  suggestions,
+  templates,
+  onChange,
+  onRemove,
+}: {
+  readonly injection: StateInjection;
+  readonly index: number;
+  readonly inputJq: readonly ResolvedTemplateJq[];
+  readonly suggestions?: readonly TemplateJqSuggestion[];
+  readonly templates?: TemplatedTextCatalog;
+  readonly onChange: (injection: StateInjection) => void;
+  readonly onRemove: () => void;
+}): ReactNode {
+  const isCustom = injection.jq !== null;
+  const selectValue = isCustom ? CUSTOM : (injection.template_jq ?? '');
+
+  return (
+    <div
+      data-testid={`injection-row-${String(index)}`}
+      style={{
+        display: 'flex',
+        gap: 'var(--tai-space-2)',
+        alignItems: 'flex-start',
+        flexWrap: 'wrap',
+      }}
+    >
+      <Field label={`Injection source ${String(index + 1)}`} hideLabel>
+        <Select
+          placeholder="Choose a template jq"
+          value={selectValue}
+          onValueChange={(next) => {
+            if (next === CUSTOM)
+              onChange({ template_jq: null, jq: { content: '' }, into: injection.into });
+            else onChange({ template_jq: next, jq: null, into: injection.into });
+          }}
+          groups={[
+            {
+              label: 'Template jq',
+              options: inputJq.map((entry) => ({ value: entry.ref, label: optionLabel(entry) })),
+            },
+            { label: 'Custom', options: [{ value: CUSTOM, label: 'Custom jq' }] },
+          ]}
+        />
+      </Field>
+      {isCustom ? (
+        <BindingTemplatedJqField
+          label={`Custom injection jq ${String(index + 1)}`}
+          required
+          value={injection.jq}
+          onChange={(next) => {
+            onChange({ template_jq: null, jq: next ?? { content: '' }, into: injection.into });
+          }}
+          suggestions={suggestions}
+          templates={templates}
+        />
+      ) : null}
+      <Field label={`Into field ${String(index + 1)}`} hideLabel>
+        <TextInput
+          placeholder="Input field"
+          value={injection.into}
+          onChange={(event) => {
+            onChange({ ...injection, into: event.target.value });
+          }}
+        />
+      </Field>
+      <Button
+        type="button"
+        variant="ghost"
+        aria-label={`Remove input ${String(index + 1)}`}
+        onClick={onRemove}
+      >
+        <CloseIcon aria-hidden="true" />
+      </Button>
+    </div>
+  );
+}
+
+export interface InjectionListProps {
+  readonly injections: readonly StateInjection[];
+  readonly onChange: (injections: readonly StateInjection[]) => void;
+  readonly inputJq: readonly ResolvedTemplateJq[];
+  readonly suggestions?: readonly TemplateJqSuggestion[];
+  readonly templates?: TemplatedTextCatalog;
+}
+
+export function InjectionList({
+  injections,
+  onChange,
+  inputJq,
+  suggestions,
+  templates,
+}: InjectionListProps): ReactNode {
+  const add = (): void => {
+    const first = inputJq[0];
+    const next: StateInjection =
+      first !== undefined
+        ? { template_jq: first.ref, jq: null, into: '' }
+        : { template_jq: null, jq: { content: '' }, into: '' };
+    onChange([...injections, next]);
+  };
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--tai-space-2)' }}>
+      {injections.map((injection, index) => (
+        <InjectionRow
+          // Rows are positional; the index is their stable identity within a save.
+          key={index}
+          injection={injection}
+          index={index}
+          inputJq={inputJq}
+          suggestions={suggestions}
+          templates={templates}
+          onChange={(next) => {
+            onChange(injections.map((current, position) => (position === index ? next : current)));
+          }}
+          onRemove={() => {
+            onChange(injections.filter((_, position) => position !== index));
+          }}
+        />
+      ))}
+      <div>
+        <Button type="button" variant="ghost" onClick={add}>
+          Add input
+        </Button>
+      </div>
+    </div>
+  );
+}

package/src/state-binding/README.md

@@ -0,0 +1,46 @@
+# State-binding editor
+
+The one binding shape every door (preset, channel route, schedule, hook) and every
+flow node authors, plus its pure helpers. Lives in the SDK so any plugin door reuses
+it; holds no edge to jq (the jq fields render through the host's ambient
+`ExpressionFieldContext`, else a plain textarea) and paints from SDK tokens only.
+
+## The canonical jq contracts
+
+- **template `input` jq** — input is the record (`.`), declared params bound as
+  `$params`; returns the injected value.
+- **custom injection jq** — over `{ record, input }`; returns the value placed at `into`.
+- **adapter** — over `{ output, input }`; CONSTRUCTS the update jq's declared input
+  object.
+- **template `update` jq** — over `{ record, input }` where `input` is the adapter's
+  output; returns a template-relative op batch.
+- **custom `update` jq** — over `{ record, output, input }`; returns `[{op, path, value}]`.
+- **`subject_expr`** — a jq yielding the record KEY: a bare key string, or a full subject object.
+- **`scope_expr`** — optional; a boolean jq predicate. When it is false, the state is skipped for the run.
+
+## The adapter's parseable shape (round-trip)
+
+Every form is rebuilt from STORED data, never UI-only state. `compileAdapter` emits a
+canonical, parseable object so a stored adapter reopens as the form it was authored in:
+
+```
+{ <key>: (<value>), … }
+```
+
+- `<key>` — a bare identifier, or a JSON string when it is not one.
+- `<value>` — one of: a field path (`.output…` / `.input…`), a JSON literal, or a raw
+  jq expression, each wrapped in `(…)`.
+
+`parseAdapter` inverts it: `parseAdapter(compileAdapter(rows).jq) === rows` for every
+row kind whose literal is already canonical JSON. A shape it does not recognise returns
+`null`, and the editor opens the raw-jq escape hatch instead.
+
+A template update that must ride inside ONE jq field is written as the call
+`tjq_<name>(<adapter object>)` (`generateTemplateCall` / `parseTemplateCall`); a field
+whose expression is exactly that call reopens as the mapping form, anything else as raw
+jq.
+
+A bound state or template absent on the server renders the raw jq read-only under a
+`template not attached` error, never a blank form. When the edited binding names a
+state the target's own (`inherited`) binding also names, the state card warns
+`Overrides the preset's subject` and shows the inherited subject/scope.

package/src/state-binding/StateAttachRow.tsx

@@ -0,0 +1,289 @@
+/**
+ * One attached state of a binding: the state selector, the templates it attaches
+ * (attach-on-use — a not-yet-attached pick shows the "attached on save" hint), the subject
+ * and scope expressions, the input injections, and the updates.
+ */
+import { useMemo, type ReactNode } from 'react';
+
+import { Button } from '../components/primitives';
+import { CodeBlock } from '../components/code-block';
+import { Checkbox } from '../components/checkbox';
+import { Field } from '../components/field';
+import { Select } from '../components/select';
+import { templatedTextSummary } from '../components/templated-text-field';
+import { AlertTriangleIcon, CloseIcon } from '../components/icons';
+import { InjectionList } from './InputInjectionRow';
+import { UpdateList } from './UpdateRow';
+import { SubjectScopeFields } from './SubjectScopeFields';
+import type { TemplateJqSuggestion } from './BindingJqField';
+import { resolveTemplateJq } from './catalog';
+import type {
+  BindingSourceSchemas,
+  BindingStateOption,
+  BindingTemplateOption,
+  StateAttach,
+  TemplatedText,
+  TemplatedTextCatalog,
+} from './types';
+
+const ATTACH_ON_USE_HINT = 'This template will be attached to the state when you save.';
+
+/** The subject/scope of the target's own (inherited) binding for a state this one also names. */
+export interface InheritedSubject {
+  readonly subject_expr: TemplatedText;
+  readonly scope_expr: TemplatedText | null;
+}
+
+/** The stored binding's raw jq, for the unresolved-catalog read-only fallback. */
+function rawBindingLines(attach: StateAttach): string {
+  const lines = [`subject: ${templatedTextSummary(attach.subject_expr)}`];
+  if (attach.scope_expr !== null) lines.push(`scope: ${templatedTextSummary(attach.scope_expr)}`);
+  for (const injection of attach.input_injections) {
+    lines.push(
+      `input ${injection.into || '(unset)'} <- ${injection.template_jq ?? templatedTextSummary(injection.jq)}`,
+    );
+  }
+  for (const update of attach.updates) {
+    const ref = update.template_jq ?? templatedTextSummary(update.jq);
+    lines.push(
+      `update ${ref}${update.adapter !== null ? ` adapter ${templatedTextSummary(update.adapter)}` : ''}`,
+    );
+  }
+  return lines.join('\n');
+}
+
+export interface StateAttachRowProps {
+  readonly attach: StateAttach;
+  readonly onChange: (attach: StateAttach) => void;
+  readonly onRemove: () => void;
+  readonly statesCatalog: readonly BindingStateOption[];
+  readonly templatesCatalog: readonly BindingTemplateOption[];
+  readonly sources?: BindingSourceSchemas;
+  readonly subjectError?: string;
+  /** The target's own binding subject for this state, when it also binds it (precedence). */
+  readonly inherited?: InheritedSubject;
+  /** The stored templates a templated-text field's id picker offers. */
+  readonly templates?: TemplatedTextCatalog;
+}
+
+export function StateAttachRow({
+  attach,
+  onChange,
+  onRemove,
+  statesCatalog,
+  templatesCatalog,
+  sources,
+  subjectError,
+  inherited,
+  templates,
+}: StateAttachRowProps): ReactNode {
+  const stateOption = statesCatalog.find((option) => option.name === attach.state);
+  const attachedTemplates = stateOption?.attachedTemplates ?? [];
+  // A bound state or template absent on the server cannot resolve its pickers: show
+  // the raw jq read-only rather than a blank form.
+  const stateMissing = attach.state !== '' && stateOption === undefined;
+  const missingTemplates = attach.templates.filter(
+    (name) => !templatesCatalog.some((template) => template.name === name),
+  );
+  const unresolved = stateMissing || missingTemplates.length > 0;
+
+  const inputJq = useMemo(
+    () => resolveTemplateJq(attach.templates, templatesCatalog, 'input'),
+    [attach.templates, templatesCatalog],
+  );
+  const updateJq = useMemo(
+    () => resolveTemplateJq(attach.templates, templatesCatalog, 'update'),
+    [attach.templates, templatesCatalog],
+  );
+  // An `update` jq returns an op batch and is never callable from an expression (it is
+  // picked only by an update's own select), so the `tjq_…` insert suggestions offered to
+  // EVERY jq field are the attached templates' `input`-purpose jq only.
+  const suggestions: TemplateJqSuggestion[] = useMemo(
+    () =>
+      inputJq.map((entry) => ({
+        ref: entry.ref,
+        purpose: entry.purpose,
+        description: entry.description,
+      })),
+    [inputJq],
+  );
+
+  const toggleTemplate = (name: string, checked: boolean): void => {
+    const next = checked
+      ? [...attach.templates, name]
+      : attach.templates.filter((template) => template !== name);
+    onChange({ ...attach, templates: next });
+  };
+
+  return (
+    <div
+      data-testid={`state-attach-${attach.state}`}
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--tai-space-3)',
+        padding: 'var(--tai-space-3)',
+        border: '1px solid var(--tai-color-border)',
+        borderRadius: 'var(--tai-radius-md)',
+      }}
+    >
+      <div
+        style={{
+          display: 'flex',
+          gap: 'var(--tai-space-2)',
+          alignItems: 'flex-end',
+          flexWrap: 'wrap',
+        }}
+      >
+        <Field label="State">
+          <Select
+            aria-label="State"
+            placeholder="Choose a state"
+            value={attach.state}
+            onValueChange={(next) => {
+              // A new state resets the template picks (its attachments differ).
+              onChange({ ...attach, state: next, templates: [] });
+            }}
+            options={statesCatalog.map((option) => ({ value: option.name, label: option.name }))}
+          />
+        </Field>
+        <Button
+          type="button"
+          variant="ghost"
+          aria-label={`Remove state ${attach.state === '' ? '(unset)' : attach.state}`}
+          onClick={onRemove}
+        >
+          <CloseIcon aria-hidden="true" />
+        </Button>
+      </div>
+
+      {inherited !== undefined && attach.state !== '' ? (
+        <div
+          role="status"
+          style={{
+            display: 'flex',
+            gap: 'var(--tai-space-2)',
+            alignItems: 'flex-start',
+            padding: 'var(--tai-space-2)',
+            borderRadius: 'var(--tai-radius-md)',
+            background: 'var(--tai-color-warn-tint)',
+            color: 'var(--tai-color-warn-text)',
+          }}
+        >
+          <AlertTriangleIcon aria-hidden="true" />
+          <div>
+            <strong>Overrides the preset&rsquo;s subject</strong>
+            <div style={{ display: 'flex', gap: 'var(--tai-space-2)', flexWrap: 'wrap' }}>
+              <span
+                style={{ color: 'var(--tai-color-text-muted)', fontSize: 'var(--tai-text-sm)' }}
+              >
+                Preset default:
+              </span>
+              <span style={{ fontFamily: 'var(--tai-font-mono)', fontSize: 'var(--tai-text-sm)' }}>
+                {`subject: ${templatedTextSummary(inherited.subject_expr)}`}
+                {inherited.scope_expr !== null
+                  ? `, scope: ${templatedTextSummary(inherited.scope_expr)}`
+                  : ''}
+              </span>
+            </div>
+          </div>
+        </div>
+      ) : null}
+
+      {attach.state !== '' && unresolved ? (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--tai-space-2)' }}>
+          <p role="alert" style={{ margin: 0, color: 'var(--tai-color-err-text)' }}>
+            Template not attached.
+          </p>
+          <CodeBlock code={rawBindingLines(attach)} language="text" />
+        </div>
+      ) : null}
+
+      {attach.state !== '' && !unresolved ? (
+        <>
+          <Field
+            label="Templates"
+            group
+            description="One or more templates this binding attaches to the state."
+          >
+            <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--tai-space-1)' }}>
+              {templatesCatalog.length === 0 ? (
+                <p style={{ margin: 0, color: 'var(--tai-color-text-muted)' }}>
+                  No templates available.
+                </p>
+              ) : (
+                templatesCatalog.map((template) => {
+                  const checked = attach.templates.includes(template.name);
+                  const willAttach = checked && !attachedTemplates.includes(template.name);
+                  return (
+                    <div
+                      key={template.name}
+                      style={{ display: 'flex', flexDirection: 'column', gap: '2px' }}
+                    >
+                      <Checkbox
+                        checked={checked}
+                        label={template.name}
+                        onCheckedChange={(next) => {
+                          toggleTemplate(template.name, next);
+                        }}
+                      />
+                      {willAttach ? (
+                        <span
+                          style={{
+                            color: 'var(--tai-color-text-muted)',
+                            fontSize: 'var(--tai-text-sm)',
+                          }}
+                        >
+                          {ATTACH_ON_USE_HINT}
+                        </span>
+                      ) : null}
+                    </div>
+                  );
+                })
+              )}
+            </div>
+          </Field>
+
+          <SubjectScopeFields
+            subjectExpr={attach.subject_expr}
+            scopeExpr={attach.scope_expr}
+            subjectError={subjectError}
+            suggestions={suggestions}
+            templates={templates}
+            onSubjectChange={(next) => {
+              onChange({ ...attach, subject_expr: next });
+            }}
+            onScopeChange={(next) => {
+              onChange({ ...attach, scope_expr: next });
+            }}
+          />
+
+          <Field label="Inputs" group>
+            <InjectionList
+              injections={attach.input_injections}
+              inputJq={inputJq}
+              suggestions={suggestions}
+              templates={templates}
+              onChange={(next) => {
+                onChange({ ...attach, input_injections: [...next] });
+              }}
+            />
+          </Field>
+
+          <Field label="Updates" group>
+            <UpdateList
+              updates={attach.updates}
+              updateJq={updateJq}
+              sources={sources}
+              suggestions={suggestions}
+              templates={templates}
+              onChange={(next) => {
+                onChange({ ...attach, updates: [...next] });
+              }}
+            />
+          </Field>
+        </>
+      ) : null}
+    </div>
+  );
+}

package/src/state-binding/StateBindingEditor.tsx

@@ -0,0 +1,166 @@
+/**
+ * The optional state-binding editor — one shape on every door (a preset, a channel
+ * route, a schedule, a hook) and, in the flow engine, per node. It attaches one or
+ * more states, each with the templates it attaches on save, a subject/scope, input
+ * injections evaluated before the run, and updates applied after it.
+ *
+ * It lives in the Studio SDK so every plugin door reuses it; it holds NO edge to jq
+ * (the jq fields render through the host's ambient expression door, else a plain
+ * textarea) and paints from SDK tokens only.
+ */
+import type { ReactNode } from 'react';
+
+import { Button, EmptyState, ErrorState, Skeleton } from '../components/primitives';
+import { StateAttachRow } from './StateAttachRow';
+import type {
+  BindingSourceSchemas,
+  BindingStateOption,
+  BindingTemplateOption,
+  StateAttach,
+  StateBinding,
+  TemplatedTextCatalog,
+} from './types';
+
+export interface StateBindingEditorProps {
+  /** The binding, or `null` when the door binds no state. */
+  readonly value: StateBinding | null;
+  readonly onChange: (value: StateBinding | null) => void;
+  /** The states this door may bind, each with its attached templates and fields. */
+  readonly statesCatalog: readonly BindingStateOption[];
+  /** The templates the editor may attach (attach-on-use), each with its template jq. */
+  readonly templatesCatalog: readonly BindingTemplateOption[];
+  /** The run's output/input field paths a picker offers when a schema is known. */
+  readonly sources?: BindingSourceSchemas;
+  /**
+   * The TARGET's own binding (e.g. the preset a route dispatches), passed by the door
+   * screen — never fetched here. A state this binding names that the inherited one
+   * also names shows a precedence warning on its card.
+   */
+  readonly inherited?: StateBinding | null;
+  /** The catalog fetch is in flight. */
+  readonly loading?: boolean;
+  /** The catalog fetch failed. */
+  readonly error?: string;
+  /** The stored templates a templated-text field's id picker offers, resolved by the door. */
+  readonly templatedTextTemplates?: TemplatedTextCatalog;
+}
+
+function blankAttach(): StateAttach {
+  return {
+    state: '',
+    templates: [],
+    subject_expr: { content: '' },
+    scope_expr: null,
+    input_injections: [],
+    updates: [],
+  };
+}
+
+export function StateBindingEditor({
+  value,
+  onChange,
+  statesCatalog,
+  templatesCatalog,
+  sources,
+  inherited,
+  loading = false,
+  error,
+  templatedTextTemplates,
+}: StateBindingEditorProps): ReactNode {
+  if (loading) {
+    return (
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--tai-space-2)' }}>
+        <Skeleton height={32} />
+        <Skeleton height={32} />
+      </div>
+    );
+  }
+  if (error !== undefined) {
+    return <ErrorState message="Couldn't load states and templates." />;
+  }
+
+  const states = value?.states ?? [];
+
+  const setStates = (next: readonly StateAttach[]): void => {
+    onChange(next.length === 0 ? null : { states: [...next] });
+  };
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--tai-space-3)' }}>
+      {states.length === 0 ? (
+        <EmptyState
+          title="No state bound"
+          description="Attach a state to inject a value into the run and update the record after it."
+          action={
+            <Button
+              type="button"
+              variant="primary"
+              onClick={() => {
+                setStates([blankAttach()]);
+              }}
+            >
+              Attach a state
+            </Button>
+          }
+        />
+      ) : (
+        <>
+          {states.map((attach, index) => {
+            const inheritedAttach =
+              attach.state === ''
+                ? undefined
+                : inherited?.states.find((entry) => entry.state === attach.state);
+            // The subject is a required authored value; an empty one (no stored id and
+            // no inline text) is caught inline once a state is chosen, never sent for
+            // the server to 422.
+            const subjectEmpty =
+              attach.subject_expr.id !== undefined
+                ? attach.subject_expr.id.trim() === ''
+                : (attach.subject_expr.content ?? '').trim() === '';
+            const subjectError =
+              attach.state !== '' && subjectEmpty ? 'Subject is required.' : undefined;
+            return (
+              <StateAttachRow
+                // Positional identity within a save; a state name may be blank while picking.
+                key={index}
+                attach={attach}
+                statesCatalog={statesCatalog}
+                templatesCatalog={templatesCatalog}
+                sources={sources}
+                subjectError={subjectError}
+                templates={templatedTextTemplates}
+                inherited={
+                  inheritedAttach === undefined
+                    ? undefined
+                    : {
+                        subject_expr: inheritedAttach.subject_expr,
+                        scope_expr: inheritedAttach.scope_expr,
+                      }
+                }
+                onChange={(next) => {
+                  setStates(
+                    states.map((current, position) => (position === index ? next : current)),
+                  );
+                }}
+                onRemove={() => {
+                  setStates(states.filter((_, position) => position !== index));
+                }}
+              />
+            );
+          })}
+          <div>
+            <Button
+              type="button"
+              variant="ghost"
+              onClick={() => {
+                setStates([...states, blankAttach()]);
+              }}
+            >
+              Attach a state
+            </Button>
+          </div>
+        </>
+      )}
+    </div>
+  );
+}

package/src/state-binding/StateBindingSection.tsx

@@ -0,0 +1,37 @@
+/**
+ * The collapsed "Bind state (optional)" section every platform door screen adds
+ * below its own fields. It is chrome only — the door fetches the catalogs (via its
+ * own api-client + query stack) and passes them in; this wraps `StateBindingEditor`
+ * in a keyboard-native disclosure that opens when a binding already exists.
+ */
+import { useState, type ReactNode } from 'react';
+
+import { Button } from '../components/primitives';
+import { StateBindingEditor, type StateBindingEditorProps } from './StateBindingEditor';
+
+export interface StateBindingSectionProps extends StateBindingEditorProps {
+  /** Copy on the disclosure toggle. */
+  readonly label?: string;
+}
+
+export function StateBindingSection({
+  label = 'Bind state (optional)',
+  ...editor
+}: StateBindingSectionProps): ReactNode {
+  const [open, setOpen] = useState((editor.value?.states.length ?? 0) > 0);
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--tai-space-2)' }}>
+      <Button
+        type="button"
+        variant="ghost"
+        aria-expanded={open}
+        onClick={() => {
+          setOpen((current) => !current);
+        }}
+      >
+        {label}
+      </Button>
+      {open ? <StateBindingEditor {...editor} /> : null}
+    </div>
+  );
+}