@tai42/studio-sdk 13.3.0 → 15.0.0

package/src/state-binding/catalog.ts

@@ -0,0 +1,87 @@
+/**
+ * Pure catalog helpers — resolve the template jq an attached state offers, with the
+ * name-collision rule shared by every layer: an unqualified name that TWO attached
+ * templates declare is ambiguous, so both are offered attachment-qualified as
+ * `template.name`; a name only one template declares stays bare.
+ */
+import { encodeTemplateSegment } from './adapter';
+import type { BindingTemplateJqOption, BindingTemplateOption } from './types';
+
+/** One template jq of an attached template, resolved to the reference a binding stores. */
+export interface ResolvedTemplateJq extends BindingTemplateJqOption {
+  /** The owning template. */
+  readonly template: string;
+  /** The reference a binding writes: `name`, or `template.name` when ambiguous. */
+  readonly ref: string;
+}
+
+/**
+ * Every template jq the given attached templates offer for a purpose (or all
+ * purposes when `purpose` is omitted), each carrying the reference a binding stores.
+ */
+export function resolveTemplateJq(
+  templateNames: readonly string[],
+  catalog: readonly BindingTemplateOption[],
+  purpose?: 'input' | 'update',
+): ResolvedTemplateJq[] {
+  const chosen = catalog.filter((template) => templateNames.includes(template.name));
+  const counts = new Map<string, number>();
+  for (const template of chosen) {
+    for (const jq of template.templateJq) {
+      if (purpose !== undefined && jq.purpose !== purpose) continue;
+      counts.set(jq.name, (counts.get(jq.name) ?? 0) + 1);
+    }
+  }
+  const resolved: ResolvedTemplateJq[] = [];
+  for (const template of chosen) {
+    for (const jq of template.templateJq) {
+      if (purpose !== undefined && jq.purpose !== purpose) continue;
+      const ambiguous = (counts.get(jq.name) ?? 0) > 1;
+      resolved.push({
+        ...jq,
+        template: template.name,
+        ref: ambiguous ? `${template.name}.${jq.name}` : jq.name,
+      });
+    }
+  }
+  return resolved;
+}
+
+/** Find one resolved template jq by the reference a binding stores. */
+export function findByRef(
+  ref: string,
+  resolved: readonly ResolvedTemplateJq[],
+): ResolvedTemplateJq | undefined {
+  return resolved.find((entry) => entry.ref === ref);
+}
+
+/**
+ * Resolve a jq call name (`enc(template)__name`, or a bare `name`) back to the catalog
+ * ref, driven by the catalog — never by string splitting, since a jq name may carry its
+ * own `__` past the template boundary and `enc` maps `-`→`_`. Under the template-slug
+ * invariant (no consecutive/trailing hyphens ⇒ `enc(template)` has no `__` and no
+ * trailing `_`) the FIRST `__` is the one true boundary, so the longest encoded-template
+ * prefix whose remainder is a jq the template declares is the unique qualified match;
+ * failing that, a bare name a single template declares. `null` when nothing claims it.
+ */
+export function resolveCallName(
+  callName: string,
+  catalog: readonly BindingTemplateOption[],
+): string | null {
+  let bestRef: string | null = null;
+  let bestPrefixLength = -1;
+  for (const template of catalog) {
+    const prefix = `${encodeTemplateSegment(template.name)}__`;
+    if (!callName.startsWith(prefix)) continue;
+    const jqName = callName.slice(prefix.length);
+    if (template.templateJq.some((jq) => jq.name === jqName) && prefix.length > bestPrefixLength) {
+      bestRef = `${template.name}.${jqName}`;
+      bestPrefixLength = prefix.length;
+    }
+  }
+  if (bestRef !== null) return bestRef;
+  for (const template of catalog) {
+    if (template.templateJq.some((jq) => jq.name === callName)) return callName;
+  }
+  return null;
+}

package/src/state-binding/index.ts

@@ -0,0 +1,67 @@
+/**
+ * The shared state-binding editor — the ONE binding shape every door and every flow
+ * node authors. Consumed by the platform door screens, the tai42 states surface, and
+ * (in the flow engine) the node State tab. Holds no edge to jq; paints from SDK
+ * tokens only.
+ */
+export { StateBindingEditor } from './StateBindingEditor';
+export type { StateBindingEditorProps } from './StateBindingEditor';
+export { StateBindingSection } from './StateBindingSection';
+export type { StateBindingSectionProps } from './StateBindingSection';
+export { StateAttachRow } from './StateAttachRow';
+export type { StateAttachRowProps, InheritedSubject } from './StateAttachRow';
+export { InjectionList } from './InputInjectionRow';
+export type { InjectionListProps } from './InputInjectionRow';
+export { UpdateList } from './UpdateRow';
+export type { UpdateListProps } from './UpdateRow';
+export { AdapterMapping } from './AdapterMapping';
+export type { AdapterMappingProps } from './AdapterMapping';
+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,
+  fieldPathsFromSchema,
+} from './build-catalog';
+export {
+  compileAdapter,
+  rowValueJq,
+  fieldPathToJq,
+  jqKey,
+  defaultRowsForInput,
+  parseAdapter,
+  parseFieldPath,
+  generateTemplateCall,
+  parseTemplateCall,
+  encodeTemplateSegment,
+} from './adapter';
+export type {
+  MappingRow,
+  MappingSource,
+  FieldSource,
+  LiteralSource,
+  JqSource,
+  FieldRoot,
+  AdapterCompileResult,
+} from './adapter';
+export type {
+  BindingStateOption,
+  BindingTemplateOption,
+  BindingTemplateJqOption,
+  BindingSourceSchemas,
+  SchemaFieldPath,
+  StateBinding,
+  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

@@ -0,0 +1,91 @@
+/**
+ * The catalog + value types the state-binding editor is fed and edits.
+ *
+ * The VALUE is the `StateBinding` document (mirrored in `@tai42/api-client`,
+ * imported type-only so this package keeps no runtime edge to the client). The
+ * CATALOGS are what the consumer resolves from the api-client and hands the editor:
+ * 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,
+  TemplatedText,
+} from '@tai42/api-client';
+
+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 {
+  readonly path: readonly string[];
+  readonly label: string;
+}
+
+/** One template jq of an attached template, as the pickers present it. */
+export interface BindingTemplateJqOption {
+  readonly name: string;
+  readonly purpose: 'input' | 'update';
+  readonly description?: string;
+  /** An `input` jq's declared params / an `update` jq's declared input keys. */
+  readonly params?: readonly string[];
+  /** An `update` jq's declared write paths, each a list of key segments. */
+  readonly writes?: readonly (readonly string[])[];
+}
+
+/** One template the editor may attach to a state (attach-on-use), with its template jq. */
+export interface BindingTemplateOption {
+  readonly name: string;
+  readonly description?: string;
+  /** Whether this template is already attached to the chosen state (else: attach on save). */
+  readonly attached?: boolean;
+  readonly templateJq: readonly BindingTemplateJqOption[];
+}
+
+/** One state the editor may bind, with the templates already attached to it and its fields. */
+export interface BindingStateOption {
+  readonly name: string;
+  /** Templates already attached to the state (the rest attach on save). */
+  readonly attachedTemplates?: readonly string[];
+  /** The state's own record fields, for the `state` source of a field picker. */
+  readonly fields?: readonly SchemaFieldPath[];
+}
+
+/**
+ * The schemas a field picker draws from when authoring an injection or an adapter:
+ * the run's `output` and `input` fields (the state's fields ride each
+ * {@link BindingStateOption}). Absent roots offer no picked field — the author uses
+ * a literal or a jq expression instead.
+ */
+export interface BindingSourceSchemas {
+  readonly output?: readonly SchemaFieldPath[];
+  readonly input?: readonly SchemaFieldPath[];
+  /** The tool-schema fetch that feeds the pickers is in flight. */
+  readonly loading?: boolean;
+  /** The tool-schema fetch failed — the field control shows a note but stays usable. */
+  readonly error?: string;
+}