@tai42/studio-sdk 13.3.0 → 14.0.0

package/src/state-binding/StateBindingEditor.tsx

@@ -0,0 +1,158 @@
+/**
+ * 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,
+} 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;
+}
+
+function blankAttach(): StateAttach {
+  return {
+    state: '',
+    templates: [],
+    subject_expr: '',
+    scope_expr: null,
+    input_injections: [],
+    updates: [],
+  };
+}
+
+export function StateBindingEditor({
+  value,
+  onChange,
+  statesCatalog,
+  templatesCatalog,
+  sources,
+  inherited,
+  loading = false,
+  error,
+}: 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 jq (contract: min_length=1); an empty one is
+            // caught inline once a state is chosen, never sent for the server to 422.
+            const subjectError =
+              attach.state !== '' && attach.subject_expr.trim() === ''
+                ? '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}
+                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>
+  );
+}

package/src/state-binding/SubjectScopeFields.tsx

@@ -0,0 +1,49 @@
+/**
+ * The subject + scope jq of one attached state: the SUBJECT expression (required)
+ * yields either a bare record-key string or a full subject object; the optional SCOPE
+ * expression is a boolean jq predicate — when it is false the state is skipped for the run.
+ */
+import type { ReactNode } from 'react';
+
+import { BindingJqField, type TemplateJqSuggestion } from './BindingJqField';
+
+export interface SubjectScopeFieldsProps {
+  readonly subjectExpr: string;
+  readonly scopeExpr: string | null;
+  readonly onSubjectChange: (value: string) => void;
+  readonly onScopeChange: (value: string | null) => void;
+  readonly subjectError?: string;
+  readonly suggestions?: readonly TemplateJqSuggestion[];
+}
+
+export function SubjectScopeFields({
+  subjectExpr,
+  scopeExpr,
+  onSubjectChange,
+  onScopeChange,
+  subjectError,
+  suggestions,
+}: SubjectScopeFieldsProps): ReactNode {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--tai-space-2)' }}>
+      <BindingJqField
+        label="Subject"
+        description="The record key this binding reads and updates: a key string, or a full subject object."
+        value={subjectExpr}
+        onChange={onSubjectChange}
+        error={subjectError}
+        suggestions={suggestions}
+        placeholder=".subject_id"
+      />
+      <BindingJqField
+        label="Scope"
+        description="Optional. A jq condition; when it is false this state is skipped for the run."
+        value={scopeExpr ?? ''}
+        onChange={(next) => {
+          onScopeChange(next.trim() === '' ? null : next);
+        }}
+        suggestions={suggestions}
+      />
+    </div>
+  );
+}

package/src/state-binding/UpdateRow.tsx

@@ -0,0 +1,194 @@
+/**
+ * The update list of one attached state. Each update applies AFTER the run: either
+ * a template `update` jq (picked by name, whose declared input is authored through
+ * the adapter mapping) or a custom jq over `{ record, output, input }` that authors
+ * the whole op batch itself. An optional op-id expression carries idempotency.
+ */
+import type { ReactNode } from 'react';
+
+import { Badge } from '../components/badge';
+import { Button } from '../components/primitives';
+import { Field } from '../components/field';
+import { Select } from '../components/select';
+import { CloseIcon } from '../components/icons';
+import { AdapterMapping } from './AdapterMapping';
+import { BindingJqField, type TemplateJqSuggestion } from './BindingJqField';
+import { findByRef, type ResolvedTemplateJq } from './catalog';
+import type { BindingSourceSchemas, StateUpdate } from './types';
+
+const CUSTOM = '__custom__';
+
+function optionLabel(entry: ResolvedTemplateJq): string {
+  return entry.description !== undefined && entry.description !== ''
+    ? `${entry.ref} — ${entry.description}`
+    : entry.ref;
+}
+
+function writesLabel(entry: ResolvedTemplateJq | undefined): string | null {
+  if (entry?.writes === undefined || entry.writes.length === 0) return null;
+  return entry.writes.map((path) => path.join('.')).join(', ');
+}
+
+function UpdateRowEditor({
+  update,
+  index,
+  updateJq,
+  sources,
+  suggestions,
+  onChange,
+  onRemove,
+}: {
+  readonly update: StateUpdate;
+  readonly index: number;
+  readonly updateJq: readonly ResolvedTemplateJq[];
+  readonly sources?: BindingSourceSchemas;
+  readonly suggestions?: readonly TemplateJqSuggestion[];
+  readonly onChange: (update: StateUpdate) => void;
+  readonly onRemove: () => void;
+}): ReactNode {
+  const isCustom = update.jq !== null;
+  const selectValue = isCustom ? CUSTOM : (update.template_jq ?? '');
+  const resolved =
+    update.template_jq !== null ? findByRef(update.template_jq, updateJq) : undefined;
+  const writes = writesLabel(resolved);
+
+  return (
+    <div
+      data-testid={`update-row-${String(index)}`}
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--tai-space-2)',
+        padding: 'var(--tai-space-2)',
+        border: '1px solid var(--tai-color-border)',
+        borderRadius: 'var(--tai-radius-md)',
+      }}
+    >
+      <div
+        style={{
+          display: 'flex',
+          gap: 'var(--tai-space-2)',
+          alignItems: 'center',
+          flexWrap: 'wrap',
+        }}
+      >
+        <Field label={`Update source ${String(index + 1)}`} hideLabel>
+          <Select
+            placeholder="Choose a template jq"
+            value={selectValue}
+            onValueChange={(next) => {
+              if (next === CUSTOM)
+                onChange({ template_jq: null, jq: '', adapter: null, op_id: update.op_id });
+              else onChange({ template_jq: next, jq: null, adapter: null, op_id: update.op_id });
+            }}
+            groups={[
+              {
+                label: 'Template jq',
+                options: updateJq.map((entry) => ({ value: entry.ref, label: optionLabel(entry) })),
+              },
+              { label: 'Custom', options: [{ value: CUSTOM, label: 'Custom jq' }] },
+            ]}
+          />
+        </Field>
+        {writes !== null ? <Badge variant="neutral">{`writes: ${writes}`}</Badge> : null}
+        <Button
+          type="button"
+          variant="ghost"
+          aria-label={`Remove update ${String(index + 1)}`}
+          onClick={onRemove}
+        >
+          <CloseIcon aria-hidden="true" />
+        </Button>
+      </div>
+
+      {isCustom ? (
+        <BindingJqField
+          label={`Custom update jq ${String(index + 1)}`}
+          description="A jq over `{ record, output, input }` returning a template-relative op batch."
+          value={update.jq ?? ''}
+          onChange={(next) => {
+            onChange({ template_jq: null, jq: next, adapter: null, op_id: update.op_id });
+          }}
+          suggestions={suggestions}
+        />
+      ) : (
+        <Field label="Adapter" group>
+          <AdapterMapping
+            // Remount on a template change so the mapping rebuilds from the newly
+            // declared input (and re-seeds its shown default) instead of stale rows.
+            key={resolved?.ref ?? '__none__'}
+            declaredInput={resolved?.params ?? []}
+            value={update.adapter ?? ''}
+            sources={sources}
+            suggestions={suggestions}
+            onChange={(adapterJq) => {
+              onChange({ ...update, adapter: adapterJq });
+            }}
+          />
+        </Field>
+      )}
+
+      <BindingJqField
+        label="Op id"
+        description="Optional — an idempotency-key expression."
+        value={update.op_id ?? ''}
+        onChange={(next) => {
+          onChange({ ...update, op_id: next.trim() === '' ? null : next });
+        }}
+        suggestions={suggestions}
+      />
+    </div>
+  );
+}
+
+export interface UpdateListProps {
+  readonly updates: readonly StateUpdate[];
+  readonly onChange: (updates: readonly StateUpdate[]) => void;
+  readonly updateJq: readonly ResolvedTemplateJq[];
+  readonly sources?: BindingSourceSchemas;
+  readonly suggestions?: readonly TemplateJqSuggestion[];
+}
+
+export function UpdateList({
+  updates,
+  onChange,
+  updateJq,
+  sources,
+  suggestions,
+}: UpdateListProps): ReactNode {
+  const add = (): void => {
+    const first = updateJq[0];
+    const next: StateUpdate =
+      first !== undefined
+        ? { template_jq: first.ref, jq: null, adapter: null, op_id: null }
+        : { template_jq: null, jq: '', adapter: null, op_id: null };
+    onChange([...updates, next]);
+  };
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--tai-space-2)' }}>
+      {updates.map((update, index) => (
+        <UpdateRowEditor
+          // Rows are positional; the index is their stable identity within a save.
+          key={index}
+          update={update}
+          index={index}
+          updateJq={updateJq}
+          sources={sources}
+          suggestions={suggestions}
+          onChange={(next) => {
+            onChange(updates.map((current, position) => (position === index ? next : current)));
+          }}
+          onRemove={() => {
+            onChange(updates.filter((_, position) => position !== index));
+          }}
+        />
+      ))}
+      <div>
+        <Button type="button" variant="ghost" onClick={add}>
+          Add update
+        </Button>
+      </div>
+    </div>
+  );
+}