@tai42/studio-sdk 14.0.0 → 16.0.0

package/src/state-binding/InputInjectionRow.tsx

@@ -10,9 +10,10 @@ 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 { BindingTemplatedJqField } from './BindingTemplatedJqField';
+import type { TemplateJqSuggestion } from './BindingJqField';
 import type { ResolvedTemplateJq } from './catalog';
-import type { StateInjection } from './types';
+import type { StateInjection, TemplatedTextCatalog } from './types';
 
 function optionLabel(entry: ResolvedTemplateJq): string {
   return entry.description !== undefined && entry.description !== ''
@@ -27,6 +28,7 @@ function InjectionRow({
   index,
   inputJq,
   suggestions,
+  templates,
   onChange,
   onRemove,
 }: {
@@ -34,6 +36,7 @@ function InjectionRow({
   readonly index: number;
   readonly inputJq: readonly ResolvedTemplateJq[];
   readonly suggestions?: readonly TemplateJqSuggestion[];
+  readonly templates?: TemplatedTextCatalog;
   readonly onChange: (injection: StateInjection) => void;
   readonly onRemove: () => void;
 }): ReactNode {
@@ -55,7 +58,8 @@ function InjectionRow({
           placeholder="Choose a template jq"
           value={selectValue}
           onValueChange={(next) => {
-            if (next === CUSTOM) onChange({ template_jq: null, jq: '', into: injection.into });
+            if (next === CUSTOM)
+              onChange({ template_jq: null, jq: { content: '' }, into: injection.into });
             else onChange({ template_jq: next, jq: null, into: injection.into });
           }}
           groups={[
@@ -68,13 +72,15 @@ function InjectionRow({
         />
       </Field>
       {isCustom ? (
-        <BindingJqField
+        <BindingTemplatedJqField
           label={`Custom injection jq ${String(index + 1)}`}
-          value={injection.jq ?? ''}
+          required
+          value={injection.jq}
           onChange={(next) => {
-            onChange({ template_jq: null, jq: next, into: injection.into });
+            onChange({ template_jq: null, jq: next ?? { content: '' }, into: injection.into });
           }}
           suggestions={suggestions}
+          templates={templates}
         />
       ) : null}
       <Field label={`Into field ${String(index + 1)}`} hideLabel>
@@ -103,6 +109,7 @@ export interface InjectionListProps {
   readonly onChange: (injections: readonly StateInjection[]) => void;
   readonly inputJq: readonly ResolvedTemplateJq[];
   readonly suggestions?: readonly TemplateJqSuggestion[];
+  readonly templates?: TemplatedTextCatalog;
 }
 
 export function InjectionList({
@@ -110,13 +117,14 @@ export function InjectionList({
   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: '', into: '' };
+        : { template_jq: null, jq: { content: '' }, into: '' };
     onChange([...injections, next]);
   };
 
@@ -130,6 +138,7 @@ export function InjectionList({
           index={index}
           inputJq={inputJq}
           suggestions={suggestions}
+          templates={templates}
           onChange={(next) => {
             onChange(injections.map((current, position) => (position === index ? next : current)));
           }}

package/src/state-binding/StateAttachRow.tsx

@@ -10,6 +10,7 @@ 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';
@@ -21,30 +22,31 @@ import type {
   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: string;
-  readonly scope_expr: string | null;
+  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: ${attach.subject_expr || '(unset)'}`];
-  if (attach.scope_expr !== null && attach.scope_expr !== '')
-    lines.push(`scope: ${attach.scope_expr}`);
+  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 ?? injection.jq ?? ''}`,
+      `input ${injection.into || '(unset)'} <- ${injection.template_jq ?? templatedTextSummary(injection.jq)}`,
     );
   }
   for (const update of attach.updates) {
-    const ref = update.template_jq ?? update.jq ?? '';
+    const ref = update.template_jq ?? templatedTextSummary(update.jq);
     lines.push(
-      `update ${ref}${update.adapter !== null && update.adapter !== '' ? ` adapter ${update.adapter}` : ''}`,
+      `update ${ref}${update.adapter !== null ? ` adapter ${templatedTextSummary(update.adapter)}` : ''}`,
     );
   }
   return lines.join('\n');
@@ -60,6 +62,8 @@ export interface StateAttachRowProps {
   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({
@@ -71,6 +75,7 @@ export function StateAttachRow({
   sources,
   subjectError,
   inherited,
+  templates,
 }: StateAttachRowProps): ReactNode {
   const stateOption = statesCatalog.find((option) => option.name === attach.state);
   const attachedTemplates = stateOption?.attachedTemplates ?? [];
@@ -175,9 +180,9 @@ export function StateAttachRow({
                 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}`
+                {`subject: ${templatedTextSummary(inherited.subject_expr)}`}
+                {inherited.scope_expr !== null
+                  ? `, scope: ${templatedTextSummary(inherited.scope_expr)}`
                   : ''}
               </span>
             </div>
@@ -244,6 +249,7 @@ export function StateAttachRow({
             scopeExpr={attach.scope_expr}
             subjectError={subjectError}
             suggestions={suggestions}
+            templates={templates}
             onSubjectChange={(next) => {
               onChange({ ...attach, subject_expr: next });
             }}
@@ -257,6 +263,7 @@ export function StateAttachRow({
               injections={attach.input_injections}
               inputJq={inputJq}
               suggestions={suggestions}
+              templates={templates}
               onChange={(next) => {
                 onChange({ ...attach, input_injections: [...next] });
               }}
@@ -269,6 +276,7 @@ export function StateAttachRow({
               updateJq={updateJq}
               sources={sources}
               suggestions={suggestions}
+              templates={templates}
               onChange={(next) => {
                 onChange({ ...attach, updates: [...next] });
               }}

package/src/state-binding/StateBindingEditor.tsx

@@ -18,6 +18,7 @@ import type {
   BindingTemplateOption,
   StateAttach,
   StateBinding,
+  TemplatedTextCatalog,
 } from './types';
 
 export interface StateBindingEditorProps {
@@ -40,13 +41,15 @@ export interface StateBindingEditorProps {
   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: '',
+    subject_expr: { content: '' },
     scope_expr: null,
     input_injections: [],
     updates: [],
@@ -62,6 +65,7 @@ export function StateBindingEditor({
   inherited,
   loading = false,
   error,
+  templatedTextTemplates,
 }: StateBindingEditorProps): ReactNode {
   if (loading) {
     return (
@@ -106,12 +110,15 @@ export function StateBindingEditor({
               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.
+            // 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 !== '' && attach.subject_expr.trim() === ''
-                ? 'Subject is required.'
-                : undefined;
+              attach.state !== '' && subjectEmpty ? 'Subject is required.' : undefined;
             return (
               <StateAttachRow
                 // Positional identity within a save; a state name may be blank while picking.
@@ -121,6 +128,7 @@ export function StateBindingEditor({
                 templatesCatalog={templatesCatalog}
                 sources={sources}
                 subjectError={subjectError}
+                templates={templatedTextTemplates}
                 inherited={
                   inheritedAttach === undefined
                     ? undefined

package/src/state-binding/SubjectScopeFields.tsx

@@ -1,19 +1,23 @@
 /**
- * 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.
+ * The subject + scope of one attached state: the SUBJECT (required) yields either a
+ * bare record-key string or a full subject object; the optional SCOPE is a boolean
+ * jq predicate — when it is false the state is skipped for the run. Each is an
+ * authored templated-text value (inline jq or a stored template that renders to it).
  */
 import type { ReactNode } from 'react';
 
-import { BindingJqField, type TemplateJqSuggestion } from './BindingJqField';
+import { BindingTemplatedJqField } from './BindingTemplatedJqField';
+import type { TemplateJqSuggestion } from './BindingJqField';
+import type { TemplatedText, TemplatedTextCatalog } from './types';
 
 export interface SubjectScopeFieldsProps {
-  readonly subjectExpr: string;
-  readonly scopeExpr: string | null;
-  readonly onSubjectChange: (value: string) => void;
-  readonly onScopeChange: (value: string | null) => void;
+  readonly subjectExpr: TemplatedText;
+  readonly scopeExpr: TemplatedText | null;
+  readonly onSubjectChange: (value: TemplatedText) => void;
+  readonly onScopeChange: (value: TemplatedText | null) => void;
   readonly subjectError?: string;
   readonly suggestions?: readonly TemplateJqSuggestion[];
+  readonly templates?: TemplatedTextCatalog;
 }
 
 export function SubjectScopeFields({
@@ -23,26 +27,30 @@ export function SubjectScopeFields({
   onScopeChange,
   subjectError,
   suggestions,
+  templates,
 }: SubjectScopeFieldsProps): ReactNode {
   return (
     <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--tai-space-2)' }}>
-      <BindingJqField
+      <BindingTemplatedJqField
         label="Subject"
+        required
         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}
+        templates={templates}
         placeholder=".subject_id"
+        onChange={(next) => {
+          onSubjectChange(next ?? { content: '' });
+        }}
       />
-      <BindingJqField
+      <BindingTemplatedJqField
         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);
-        }}
+        value={scopeExpr}
         suggestions={suggestions}
+        templates={templates}
+        onChange={onScopeChange}
       />
     </div>
   );

package/src/state-binding/UpdateRow.tsx

@@ -10,11 +10,13 @@ import { Badge } from '../components/badge';
 import { Button } from '../components/primitives';
 import { Field } from '../components/field';
 import { Select } from '../components/select';
+import { TemplatedTextField } from '../components/templated-text-field';
 import { CloseIcon } from '../components/icons';
 import { AdapterMapping } from './AdapterMapping';
-import { BindingJqField, type TemplateJqSuggestion } from './BindingJqField';
+import { BindingTemplatedJqField } from './BindingTemplatedJqField';
+import type { TemplateJqSuggestion } from './BindingJqField';
 import { findByRef, type ResolvedTemplateJq } from './catalog';
-import type { BindingSourceSchemas, StateUpdate } from './types';
+import type { BindingSourceSchemas, StateUpdate, TemplatedTextCatalog } from './types';
 
 const CUSTOM = '__custom__';
 
@@ -35,6 +37,7 @@ function UpdateRowEditor({
   updateJq,
   sources,
   suggestions,
+  templates,
   onChange,
   onRemove,
 }: {
@@ -43,6 +46,7 @@ function UpdateRowEditor({
   readonly updateJq: readonly ResolvedTemplateJq[];
   readonly sources?: BindingSourceSchemas;
   readonly suggestions?: readonly TemplateJqSuggestion[];
+  readonly templates?: TemplatedTextCatalog;
   readonly onChange: (update: StateUpdate) => void;
   readonly onRemove: () => void;
 }): ReactNode {
@@ -78,7 +82,12 @@ function UpdateRowEditor({
             value={selectValue}
             onValueChange={(next) => {
               if (next === CUSTOM)
-                onChange({ template_jq: null, jq: '', adapter: null, op_id: update.op_id });
+                onChange({
+                  template_jq: null,
+                  jq: { content: '' },
+                  adapter: null,
+                  op_id: update.op_id,
+                });
               else onChange({ template_jq: next, jq: null, adapter: null, op_id: update.op_id });
             }}
             groups={[
@@ -102,40 +111,61 @@ function UpdateRowEditor({
       </div>
 
       {isCustom ? (
-        <BindingJqField
+        <BindingTemplatedJqField
           label={`Custom update jq ${String(index + 1)}`}
+          required
           description="A jq over `{ record, output, input }` returning a template-relative op batch."
-          value={update.jq ?? ''}
+          value={update.jq}
           onChange={(next) => {
-            onChange({ template_jq: null, jq: next, adapter: null, op_id: update.op_id });
+            onChange({
+              template_jq: null,
+              jq: next ?? { content: '' },
+              adapter: null,
+              op_id: update.op_id,
+            });
           }}
           suggestions={suggestions}
+          templates={templates}
         />
       ) : (
-        <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>
+        <TemplatedTextField
+          // 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__'}
+          label="Adapter"
+          value={update.adapter}
+          templates={templates?.templates}
+          templatesLoading={templates?.loading}
+          templatesError={templates?.error}
+          onTemplatesRetry={templates?.onRetry}
+          storageAbsent={templates?.storageAbsent}
+          storagePresenceLoading={templates?.storagePresenceLoading}
+          onChange={(next) => {
+            onChange({ ...update, adapter: next });
+          }}
+          renderInline={({ value: inlineValue, onChange: onInline }) => (
+            <AdapterMapping
+              declaredInput={resolved?.params ?? []}
+              value={inlineValue}
+              sources={sources}
+              suggestions={suggestions}
+              onChange={(adapterJq) => {
+                onInline(adapterJq ?? '');
+              }}
+            />
+          )}
+        />
       )}
 
-      <BindingJqField
+      <BindingTemplatedJqField
         label="Op id"
         description="Optional — an idempotency-key expression."
-        value={update.op_id ?? ''}
+        value={update.op_id}
         onChange={(next) => {
-          onChange({ ...update, op_id: next.trim() === '' ? null : next });
+          onChange({ ...update, op_id: next });
         }}
         suggestions={suggestions}
+        templates={templates}
       />
     </div>
   );
@@ -147,6 +177,7 @@ export interface UpdateListProps {
   readonly updateJq: readonly ResolvedTemplateJq[];
   readonly sources?: BindingSourceSchemas;
   readonly suggestions?: readonly TemplateJqSuggestion[];
+  readonly templates?: TemplatedTextCatalog;
 }
 
 export function UpdateList({
@@ -155,13 +186,14 @@ export function UpdateList({
   updateJq,
   sources,
   suggestions,
+  templates,
 }: 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 };
+        : { template_jq: null, jq: { content: '' }, adapter: null, op_id: null };
     onChange([...updates, next]);
   };
 
@@ -176,6 +208,7 @@ export function UpdateList({
           updateJq={updateJq}
           sources={sources}
           suggestions={suggestions}
+          templates={templates}
           onChange={(next) => {
             onChange(updates.map((current, position) => (position === index ? next : current)));
           }}

package/src/state-binding/index.ts

@@ -20,8 +20,12 @@ export { SubjectScopeFields } from './SubjectScopeFields';
 export type { SubjectScopeFieldsProps } from './SubjectScopeFields';
 export { BindingJqField, appendTjq } from './BindingJqField';
 export type { BindingJqFieldProps, TemplateJqSuggestion } from './BindingJqField';
+export { BindingTemplatedJqField } from './BindingTemplatedJqField';
+export type { BindingTemplatedJqFieldProps } from './BindingTemplatedJqField';
 export { resolveTemplateJq, findByRef, resolveCallName } from './catalog';
 export type { ResolvedTemplateJq } from './catalog';
+export { templatedTextCatalog } from './templated-text-catalog';
+export type { StoragePresenceQueryLike, TemplateNamesQueryLike } from './templated-text-catalog';
 export {
   templatesCatalogFromList,
   statesCatalogFromList,
@@ -58,4 +62,6 @@ export type {
   StateAttach,
   StateInjection,
   StateUpdate,
+  TemplatedText,
+  TemplatedTextCatalog,
 } from './types';

package/src/state-binding/templated-text-catalog.ts

@@ -0,0 +1,69 @@
+/**
+ * Builds the {@link TemplatedTextCatalog} a door form feeds its templated-text
+ * fields, from the two queries every such form already runs: the storage-presence
+ * signal (`GET /api/storage`) and the stored-template name list (`GET /api/templates`).
+ *
+ * Storage is dead by default — a deployment with no storage backend is supported —
+ * and the template list door cannot answer without one. So the CALLER gates its
+ * template-names query on presence (`enabled: storage.data?.present === true`), and
+ * this helper maps the two query states onto the catalog the field reads: when
+ * storage is absent it exposes no templates and marks the field absent (the field
+ * then offers no stored source); when present it exposes the fetched names. A
+ * presence-fetch failure surfaces ahead of a template-fetch failure, since presence
+ * is the prerequisite.
+ *
+ * It takes the query RESULTS structurally (the fields it reads), so this module adds
+ * no data-layer dependency to the SDK.
+ */
+import { errorMessage } from '../errors';
+
+import type { TemplatedTextCatalog } from './types';
+
+/** The storage-presence query result (`GET /api/storage`) fields this helper reads. */
+export interface StoragePresenceQueryLike {
+  readonly data?: { readonly present: boolean };
+  readonly isPending: boolean;
+  readonly isError: boolean;
+  readonly error: unknown;
+  readonly refetch: () => unknown;
+}
+
+/** The stored-template-names query result (`GET /api/templates`) fields this helper reads. */
+export interface TemplateNamesQueryLike {
+  readonly data?: readonly string[];
+  readonly isPending: boolean;
+  readonly isError: boolean;
+  readonly error: unknown;
+  readonly refetch: () => unknown;
+}
+
+export function templatedTextCatalog(
+  storage: StoragePresenceQueryLike,
+  templates: TemplateNamesQueryLike,
+): TemplatedTextCatalog {
+  const presenceKnown = storage.data !== undefined;
+  const present = storage.data?.present === true;
+  // A presence failure matters only until presence is first known: once it is in
+  // hand, a later background-refetch failure must not blow away a field already
+  // working from it. Presence is the prerequisite of the catalog, so its failure
+  // surfaces ahead of a catalog-fetch failure.
+  const presenceFailed = storage.isError && !presenceKnown;
+  return {
+    // Never expose template names while storage is absent or unknown — the caller's
+    // gate keeps the list query from firing there, and its pending/stale data must
+    // not leak into a picker the field will not show.
+    templates: present ? (templates.data ?? []).map((id) => ({ id })) : [],
+    loading: present && templates.isPending,
+    error: presenceFailed
+      ? errorMessage(storage.error)
+      : templates.isError
+        ? errorMessage(templates.error)
+        : undefined,
+    onRetry: () => {
+      if (presenceFailed) void storage.refetch();
+      else void templates.refetch();
+    },
+    storageAbsent: storage.data?.present === false,
+    storagePresenceLoading: !presenceKnown && storage.isPending,
+  };
+}

package/src/state-binding/types.ts

@@ -7,9 +7,38 @@
  * the states it may bind, the templates each may attach, and — when a schema is
  * known — the fields a picker offers.
  */
-import type { StateBinding, StateAttach, StateInjection, StateUpdate } from '@tai42/api-client';
+import type {
+  StateBinding,
+  StateAttach,
+  StateInjection,
+  StateUpdate,
+  TemplatedText,
+} from '@tai42/api-client';
 
-export type { StateBinding, StateAttach, StateInjection, StateUpdate };
+import type { TemplatedTextTemplateOption } from '../components/templated-text-field';
+
+export type { StateBinding, StateAttach, StateInjection, StateUpdate, TemplatedText };
+
+/**
+ * The stored templates a {@link TemplatedText} field's id picker offers, with the
+ * fetch's loading/error state — resolved by the door screen and passed to the
+ * editor, which holds no data edge of its own. Absent leaves every templated-text
+ * field with the inline source only.
+ */
+export interface TemplatedTextCatalog {
+  readonly templates?: readonly TemplatedTextTemplateOption[];
+  readonly loading?: boolean;
+  readonly error?: string;
+  readonly onRetry?: () => void;
+  /**
+   * Storage is registered absent (`GET /api/storage` → `present: false`), so the
+   * catalog was not fetched and the stored source is not offered on the fields this
+   * catalog feeds; an already-stored id is shown read-only.
+   */
+  readonly storageAbsent?: boolean;
+  /** Storage presence is not yet known — the fields render a placeholder, not a toggle. */
+  readonly storagePresenceLoading?: boolean;
+}
 
 /** One selectable field of a schema: the record path + a human label. */
 export interface SchemaFieldPath {