@tai42/studio-sdk 13.2.2 → 14.0.0

package/src/state-binding/BindingJqField.tsx

@@ -0,0 +1,134 @@
+/**
+ * The jq input every field a binding owns renders through — the Subject/Scope
+ * expressions, a custom injection or update jq, an adapter escape hatch, an op-id.
+ *
+ * It reuses the form door pattern: when a host has injected an expression editor
+ * through {@link ExpressionFieldContext} (the visual jq editor from
+ * `@tai42/jq-studio`), that door renders here; with no door it falls back to a
+ * plain multiline textarea, so this package keeps NO edge to the jq subgraph.
+ *
+ * The attached templates' template jq are offered as an autocomplete source: an
+ * `Insert` control per jq name appends the call `tjq_<name>({…})` to the
+ * expression — the attachment-qualified `tjq_<attachment>__<name>` form when a name is
+ * ambiguous across attachments.
+ */
+import { useContext, type ReactNode } from 'react';
+
+import { Button } from '../components/primitives';
+import { PlusIcon } from '../components/icons';
+import { Field } from '../components/field';
+import { Textarea } from '../components/inputs';
+import { ExpressionFieldContext } from '../schema-form/context';
+import { generateTemplateCall } from './adapter';
+
+/** One template jq offered as an insertable autocomplete entry. */
+export interface TemplateJqSuggestion {
+  /** The jq reference, e.g. `active` or the attachment-qualified `tally.bump`. */
+  readonly ref: string;
+  readonly purpose: 'input' | 'update';
+  readonly description?: string;
+}
+
+export interface BindingJqFieldProps {
+  readonly label: string;
+  readonly value: string;
+  readonly onChange: (value: string) => void;
+  readonly description?: ReactNode;
+  readonly error?: string;
+  readonly placeholder?: string;
+  /** Template jq offered as `tjq_<name>({…})` inserts under the field. */
+  readonly suggestions?: readonly TemplateJqSuggestion[];
+}
+
+/** Append a `tjq_<name>({…})` template call to the current expression (space-separated when non-empty). */
+export function appendTjq(current: string, ref: string): string {
+  const call = generateTemplateCall(ref, []);
+  const trimmed = current.trim();
+  return trimmed === '' ? call : `${trimmed} ${call}`;
+}
+
+export function BindingJqField({
+  label,
+  value,
+  onChange,
+  description,
+  error,
+  placeholder,
+  suggestions = [],
+}: BindingJqFieldProps): ReactNode {
+  const Door = useContext(ExpressionFieldContext);
+  // A stable hook for e2e: the injected jq editor owns its own DOM, so the wrapper
+  // carries the field's identity (`binding-jq-<label>`) for the driver to locate.
+  const testId = `binding-jq-${label.trim().replace(/\s+/g, '-').toLowerCase()}`;
+  // Only `input`-purpose jq are callable from an expression; an `update` jq returns an
+  // op batch and is picked solely by an update's own select — never offered as an insert.
+  const inputSuggestions = suggestions.filter((suggestion) => suggestion.purpose === 'input');
+
+  return (
+    <div
+      data-testid={testId}
+      style={{ display: 'flex', flexDirection: 'column', gap: 'var(--tai-space-1)' }}
+    >
+      {Door !== undefined ? (
+        <Door
+          label={label}
+          value={value}
+          onChange={onChange}
+          description={description}
+          error={error}
+          multiline
+        />
+      ) : (
+        <Field
+          label={label}
+          description={typeof description === 'string' ? description : undefined}
+          error={error}
+        >
+          <Textarea
+            value={value}
+            placeholder={placeholder}
+            onChange={(event) => {
+              onChange(event.target.value);
+            }}
+            aria-invalid={error !== undefined ? true : undefined}
+          />
+        </Field>
+      )}
+      {inputSuggestions.length > 0 ? (
+        <div
+          role="group"
+          aria-label={`Insert template jq into ${label}`}
+          style={{ display: 'flex', flexWrap: 'wrap', gap: 'var(--tai-space-1)' }}
+        >
+          {inputSuggestions.map((suggestion) => (
+            <Button
+              key={suggestion.ref}
+              type="button"
+              variant="secondary"
+              // A compact outlined pill: the leading plus reads it as an insert
+              // affordance so the monospace call text is a control, not stray code.
+              style={{
+                minHeight: 'auto',
+                padding: 'var(--tai-space-1) var(--tai-space-2)',
+                borderRadius: 'var(--tai-radius-full)',
+                fontFamily: 'var(--tai-font-mono)',
+                fontSize: 'var(--tai-text-sm)',
+              }}
+              title={
+                suggestion.description !== undefined && suggestion.description !== ''
+                  ? `${suggestion.purpose} — ${suggestion.description}`
+                  : suggestion.purpose
+              }
+              onClick={() => {
+                onChange(appendTjq(value, suggestion.ref));
+              }}
+            >
+              <PlusIcon />
+              {generateTemplateCall(suggestion.ref, [])}
+            </Button>
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/state-binding/InputInjectionRow.tsx

@@ -0,0 +1,148 @@
+/**
+ * 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 { BindingJqField, type TemplateJqSuggestion } from './BindingJqField';
+import type { ResolvedTemplateJq } from './catalog';
+import type { StateInjection } 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,
+  onChange,
+  onRemove,
+}: {
+  readonly injection: StateInjection;
+  readonly index: number;
+  readonly inputJq: readonly ResolvedTemplateJq[];
+  readonly suggestions?: readonly TemplateJqSuggestion[];
+  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: '', 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 ? (
+        <BindingJqField
+          label={`Custom injection jq ${String(index + 1)}`}
+          value={injection.jq ?? ''}
+          onChange={(next) => {
+            onChange({ template_jq: null, jq: next, into: injection.into });
+          }}
+          suggestions={suggestions}
+        />
+      ) : 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[];
+}
+
+export function InjectionList({
+  injections,
+  onChange,
+  inputJq,
+  suggestions,
+}: 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: '', 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}
+          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,281 @@
+/**
+ * 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 { 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,
+} 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: string;
+  readonly scope_expr: string | null;
+}
+
+/** The stored binding's raw jq, for the unresolved-catalog read-only fallback. */
+function rawBindingLines(attach: StateAttach): string {
+  const lines = [`subject: ${attach.subject_expr || '(unset)'}`];
+  if (attach.scope_expr !== null && attach.scope_expr !== '')
+    lines.push(`scope: ${attach.scope_expr}`);
+  for (const injection of attach.input_injections) {
+    lines.push(
+      `input ${injection.into || '(unset)'} <- ${injection.template_jq ?? injection.jq ?? ''}`,
+    );
+  }
+  for (const update of attach.updates) {
+    const ref = update.template_jq ?? update.jq ?? '';
+    lines.push(
+      `update ${ref}${update.adapter !== null && update.adapter !== '' ? ` adapter ${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;
+}
+
+export function StateAttachRow({
+  attach,
+  onChange,
+  onRemove,
+  statesCatalog,
+  templatesCatalog,
+  sources,
+  subjectError,
+  inherited,
+}: 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: ${inherited.subject_expr}`}
+                {inherited.scope_expr !== null && inherited.scope_expr !== ''
+                  ? `, scope: ${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}
+            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}
+              onChange={(next) => {
+                onChange({ ...attach, input_injections: [...next] });
+              }}
+            />
+          </Field>
+
+          <Field label="Updates" group>
+            <UpdateList
+              updates={attach.updates}
+              updateJq={updateJq}
+              sources={sources}
+              suggestions={suggestions}
+              onChange={(next) => {
+                onChange({ ...attach, updates: [...next] });
+              }}
+            />
+          </Field>
+        </>
+      ) : null}
+    </div>
+  );
+}