@tai42/studio-sdk 30.0.1 → 31.0.0

package/src/schema-form/string-annotations.ts

@@ -1,9 +1,12 @@
 /**
- * Detect the annotations that opt a (ref-resolved) string schema out of the plain
- * text box: the media-upload annotations (`contentEncoding`/`contentMediaType`/
- * `format: "data-url"`) and the `x-tai42-expression` expression-editor annotation.
- * Both degrade to `undefined` on anything malformed, so an annotated field never
- * renders differently from the plain string it falls back to.
+ * Detect the vendor and media annotations that opt a property out of its plain
+ * editor: the media-upload annotations (`contentEncoding`/`contentMediaType`/
+ * `format: "data-url"`) on a string, the `x-tai42-expression` expression-editor
+ * annotation on a string or templated-text property (or on a union of them, where
+ * it governs every member), and the `x-tai42-templated-text` mark the platform's
+ * templated-text type carries. The first two degrade to
+ * `undefined` on anything malformed, so an annotated field never renders differently
+ * from the plain field it falls back to.
  */
 import { isRecord } from '../guards';
 import type {
@@ -15,6 +18,29 @@ import type {
 import type { JsonSchema } from './types';
 
 const EXPRESSION_KEYWORD = 'x-tai42-expression';
+const TEMPLATED_TEXT_KEYWORD = 'x-tai42-templated-text';
+
+/**
+ * Is this (ref-resolved) schema the platform's templated-text type? The type stamps
+ * `x-tai42-templated-text` on its own schema, so every property of the type is
+ * recognised by the mark, never by a field name or a property layout.
+ */
+export function isTemplatedText(schema: JsonSchema): boolean {
+  return isRecord(schema[TEMPLATED_TEXT_KEYWORD]);
+}
+
+/**
+ * A schema node as its property site declares it: the `x-tai42-expression`
+ * annotation sits on the property site (a union wrapper, or the node holding a
+ * `$ref`), and it governs the node the value is checked against (the union member
+ * the value takes, or the referenced definition), so a node that carries none of its
+ * own gets the site's. The node is returned unchanged when there is nothing to carry.
+ */
+export function withSiteExpression(member: JsonSchema, site: JsonSchema): JsonSchema {
+  const annotation: unknown = site[EXPRESSION_KEYWORD];
+  if (annotation === undefined || member[EXPRESSION_KEYWORD] !== undefined) return member;
+  return { ...member, [EXPRESSION_KEYWORD]: annotation };
+}
 
 /**
  * Detect the media-upload annotations on a (ref-resolved) string schema. A field
@@ -99,20 +125,20 @@ function parseCaveatList(value: unknown): readonly string[] | undefined | null {
 }
 
 /**
- * Detect the `x-tai42-expression` annotation on a (ref-resolved) string schema,
- * mirroring {@link mediaUpload}: a well-formed annotation opts the field into the
- * jq expression editor; anything else — absent, non-object, unknown language, or
- * any wrongly-typed member — yields `undefined`, so the field renders EXACTLY as
- * the plain string input it is today. Malformed payloads NEVER throw: a bad
- * annotation is a server-side authoring bug, and degrading to the ordinary text
- * box keeps the form usable while staying byte-identical to the unannotated
- * rendering.
+ * Detect the `x-tai42-expression` annotation on a property schema (a string, or the
+ * property site of a templated-text field), mirroring {@link mediaUpload}: a
+ * well-formed annotation opts the field into the jq expression editor; anything
+ * else — absent, non-object, unknown language, or any wrongly-typed member — yields
+ * `undefined`, so the field renders EXACTLY as its unannotated editor. Malformed
+ * payloads NEVER throw: a bad annotation is a server-side authoring bug, and
+ * degrading to the ordinary editor keeps the form usable while staying
+ * byte-identical to the unannotated rendering.
  */
 export function expressionAnnotation(schema: JsonSchema): ExpressionAnnotation | undefined {
   const raw: unknown = schema[EXPRESSION_KEYWORD];
   if (!isRecord(raw)) return undefined;
   // The language gate doubles as the forward-compatibility valve: a future
-  // language this client does not understand degrades to a plain string field.
+  // language this client does not understand degrades to the unannotated field.
   if (raw.language !== 'jq') return undefined;
 
   const label = optionalString(raw.label);

package/src/schema-form/string-field.tsx

@@ -19,15 +19,15 @@
  * annotated field with no injected door falls back to the plain string input.
  */
 import type { ReactNode } from 'react';
-import { Suspense, useCallback, useContext, useMemo, useState } from 'react';
+import { useCallback, useContext, useState } from 'react';
 
 import { CompletionInput } from '../components/completion-input';
 import { Field } from '../components/field';
 import { AlertTriangleIcon } from '../components/icons';
 import { Textarea, TextInput } from '../components/inputs';
 import { errorMessage } from '../errors';
-import type { ExpressionFieldComponent, ExpressionInputShape } from './context';
 import { CompletionProviderContext, ExpressionFieldContext } from './context';
+import { ExpressionField } from './expression-field';
 import type { DateConstraints, ExpressionAnnotation, MediaUpload } from './field-model';
 import { MediaField } from './media-field';
 import type { CompletionProvider } from './SchemaForm';
@@ -240,151 +240,6 @@ function CompletionField({
   );
 }
 
-/**
- * An expression-annotated string field, rendered through the injected door: a
- * multiline resting control with the door's own visual-editor button. The door
- * brings its own label/description/error chrome (a11y-linked slots), so it is NOT
- * wrapped in the form's `Field` component — the annotation's descriptor fields map
- * onto the input-shape descriptor, and the form's per-field error feeds `error`.
- *
- * The door is rendered as an ELEMENT, never called as a function, so its hooks and
- * state (editor open, worker handle) belong to it and survive re-renders of this
- * field.
- *
- * It mounts inside a `Suspense` boundary because a host is free to inject a `lazy`
- * door to keep the jq subgraph in a split chunk of ITS OWN bundle. The fallback
- * paints the resting shell — label/description/error chrome around the current
- * value in a read-only multiline control — so the field holds its layout and keeps
- * the value visible while that chunk resolves, and the swap does not flash. A door
- * injected eagerly never suspends and renders straight through.
- *
- * The form passes only the props the field owns; a jq door's `serverValidate`,
- * `onEditorOpenChange`, and `compact` stay unwired, because no author-time
- * validation endpoint applies to a schema-declared field, the hosts that render
- * `SchemaForm` register no global shortcuts to mute, and every sibling field shows
- * a visible label (the compact variant is for dense host rows).
- */
-function ExpressionField({
-  component: Door,
-  heading,
-  description,
-  error,
-  expression,
-  argName,
-  value,
-  onChange,
-}: {
-  component: ExpressionFieldComponent;
-  heading: string;
-  description: string | undefined;
-  error: string | undefined;
-  expression: ExpressionAnnotation;
-  argName: string;
-  value: string;
-  onChange: (value: string) => void;
-}): ReactNode {
-  // Memoised: the descriptor's identity feeds the door's own memoisation, so a
-  // fresh object each keystroke would defeat it.
-  const shape = useMemo(() => expressionShape(expression, argName), [expression, argName]);
-  return (
-    <Suspense
-      fallback={
-        <ExpressionFieldSkeleton
-          heading={heading}
-          description={description}
-          error={error}
-          value={value}
-        />
-      }
-    >
-      <Door
-        label={heading}
-        description={description}
-        error={error}
-        shape={shape}
-        multiline
-        value={value}
-        onChange={onChange}
-      />
-    </Suspense>
-  );
-}
-
-/**
- * The resting shell shown while a lazily-injected door resolves. It mirrors the
- * live door's footprint — the same label/description/error chrome wrapping a
- * multiline control seeded with the current value — but the control is
- * non-interactive (read-only, `aria-busy`) because there is nothing to edit yet. Matching the
- * footprint is what keeps the Suspense swap from shifting layout or flashing.
- */
-function ExpressionFieldSkeleton({
-  heading,
-  description,
-  error,
-  value,
-}: {
-  heading: string;
-  description: string | undefined;
-  error: string | undefined;
-  value: string;
-}): ReactNode {
-  return (
-    <Field label={heading} description={description} error={error}>
-      <Textarea value={value} readOnly aria-busy="true" />
-    </Field>
-  );
-}
-
-/**
- * Map a classified expression annotation onto the door's input-shape descriptor.
- * A bare annotation (`language` only) maps to NO descriptor — an undeclared shape
- * is the honest rendering when the server said nothing about `.`. When any
- * descriptor field is present, the required descriptor members the annotation
- * omits fall back to neutral values rather than invented copy.
- */
-function expressionShape(
-  expression: ExpressionAnnotation,
-  argName: string,
-): ExpressionInputShape | undefined {
-  const declared =
-    [
-      expression.label,
-      expression.blurb,
-      expression.keys,
-      expression.variables,
-      expression.returns,
-      expression.caveats,
-    ].some((field) => field !== undefined) || expression.hasSample;
-  if (!declared) return undefined;
-  return {
-    // Opaque, host-namespaced, stable per field (memoisation/telemetry only).
-    id: argName === '' ? 'tai42.schema-form' : `tai42.schema-form.${argName}`,
-    label: expression.label ?? 'input',
-    blurb: expression.blurb ?? '',
-    keys: expression.keys ?? [],
-    returns: expression.returns ?? '',
-    ...(expression.caveats === undefined ? {} : { caveats: expression.caveats }),
-    ...(expression.hasSample ? { sample: expression.sample } : {}),
-    ...(expression.variables === undefined
-      ? {}
-      : { variables: expression.variables.map(expressionVariable) }),
-  };
-}
-
-/** Map one classified annotation variable onto the door's variable descriptor. */
-function expressionVariable(
-  variable: NonNullable<ExpressionAnnotation['variables']>[number],
-): NonNullable<ExpressionInputShape['variables']>[number] {
-  return {
-    name: variable.name,
-    blurb: variable.blurb,
-    // The annotation glosses no sub-keys of a variable's value, so the door gets
-    // the variable's shape as untyped (empty keys).
-    keys: [],
-    ...(variable.hasSample ? { sample: variable.sample } : {}),
-  };
-}
-
 // The native control per JSON-Schema `format`. `date` and `time` post the exact
 // wire shapes their formats expect (`YYYY-MM-DD`; `HH:mm` or `HH:mm:ss`), so they
 // render natively. `date-time` is deliberately absent: the browser's

package/src/schema-form/templated-field.tsx

@@ -0,0 +1,124 @@
+/**
+ * The templated-text field renderer: a property typed as the platform's templated
+ * text is authored through the shared {@link TemplatedTextField} — inline content or
+ * a stored template id, plus the render kwargs — exactly as a hand-built templated
+ * field is. When the property carries an `x-tai42-expression` annotation and the host
+ * injected an expression door, the inline editor IS that door (the resting control
+ * plus its visual-editor button); otherwise it is the field's plain textarea.
+ *
+ * The stored-template catalog comes from the host's {@link TemplatedTextCatalogContext}
+ * hook, called only here, so only a form that draws a templated-text field reads it.
+ */
+import type { TemplatedText } from '@tai42/api-client';
+import { type ReactNode, useContext, useState } from 'react';
+
+import {
+  TemplatedTextField,
+  type TemplatedTextInlineProps,
+} from '../components/templated-text-field';
+import { isRecord } from '../guards';
+import { ExpressionFieldContext, TemplatedTextCatalogContext } from './context';
+import { ExpressionField } from './expression-field';
+import type { ExpressionAnnotation } from './field-model';
+
+/** The form value read as a templated text: its string source(s) and its kwargs. */
+function templatedTextOf(value: unknown): TemplatedText | null {
+  if (!isRecord(value)) return null;
+  const { content, id, kwargs } = value;
+  return {
+    ...(typeof content === 'string' ? { content } : {}),
+    ...(typeof id === 'string' ? { id } : {}),
+    ...(isRecord(kwargs) ? { kwargs } : {}),
+  };
+}
+
+/**
+ * Which mount of the field is current. The field seeds its editing state from the
+ * value once, so a value the caller REPLACES (not one this field emitted) mounts a
+ * fresh field seeded from it.
+ */
+interface Mount {
+  readonly value: unknown;
+  readonly emitted: unknown;
+  readonly generation: number;
+}
+
+export function TemplatedField({
+  heading,
+  description,
+  error,
+  expression,
+  argName,
+  required,
+  value,
+  onChange,
+}: {
+  heading: string;
+  description: string | undefined;
+  error: string | undefined;
+  expression: ExpressionAnnotation | undefined;
+  argName: string;
+  required: boolean;
+  value: unknown;
+  onChange: (value: unknown) => void;
+}): ReactNode {
+  const useCatalog = useContext(TemplatedTextCatalogContext);
+  const catalog = useCatalog();
+  const door = useContext(ExpressionFieldContext);
+  const [mount, setMount] = useState<Mount>({ value, emitted: value, generation: 0 });
+  if (mount.value !== value) {
+    setMount({
+      value,
+      emitted: mount.emitted,
+      generation: value === mount.emitted ? mount.generation : mount.generation + 1,
+    });
+  }
+
+  // An emptied optional field drops its key; a required one keeps its empty source
+  // (the shared field emits it), so validation names the missing source and a union
+  // member stays the chosen one.
+  const emit = (next: TemplatedText | null): void => {
+    const formValue = next ?? undefined;
+    setMount((current) => ({ ...current, emitted: formValue }));
+    onChange(formValue);
+  };
+
+  const renderInline =
+    expression !== undefined && door !== undefined
+      ? (inline: TemplatedTextInlineProps): ReactNode => (
+          // The field's group header is the single visible label; the door keeps
+          // its own label element as the control's accessible name.
+          <div className={inline.hideLabel ? 'tai-templated-inline--grouped' : undefined}>
+            <ExpressionField
+              component={door}
+              heading={inline.label}
+              description={undefined}
+              error={inline.error}
+              expression={expression}
+              argName={argName}
+              value={inline.value}
+              onChange={inline.onChange}
+            />
+          </div>
+        )
+      : undefined;
+
+  return (
+    <TemplatedTextField
+      key={mount.generation}
+      label={heading}
+      description={description}
+      error={error}
+      value={templatedTextOf(value)}
+      onChange={emit}
+      required={required}
+      templates={catalog?.templates}
+      templatesLoading={catalog?.loading}
+      templatesError={catalog?.error}
+      onTemplatesRetry={catalog?.onRetry}
+      storageAbsent={catalog?.storageAbsent}
+      storagePresenceLoading={catalog?.storagePresenceLoading}
+      renderInline={renderInline}
+    />
+  );
+}

package/src/schema-form/union-field.tsx

@@ -18,6 +18,7 @@ import type { FieldModel, UnionVariant } from './field-model';
 import { FieldNode } from './field-node';
 import { ObjectFields } from './object-fields';
 import { resolveRef } from './resolve';
+import { useSeedingAction } from './seeding-action';
 import { groupClass } from './styles';
 import type { JsonSchema, SchemaFormErrors } from './types';
 import { activeVariantIndex } from './union';
@@ -132,11 +133,15 @@ export function UnionField({
     value: String(position),
     label: variant.label,
   }));
+  const switching = useSeedingAction(model.members);
   const selectVariant = (key: string): void => {
     const position = Number(key);
     const variant = model.variants[position];
     if (variant === undefined) return;
-    onChange(switchVariantValue(value, variant, model.discriminator, root));
+    const switched = switching.seed(() =>
+      switchVariantValue(value, variant, model.discriminator, root),
+    );
+    if (switched.ok) onChange(switched.value);
   };
 
   const active = index === -1 ? undefined : model.variants[index];
@@ -147,7 +152,10 @@ export function UnionField({
     // and describes — a synthetic heading there is noise, so it is suppressed
     // exactly as a root object's is; nested unions keep theirs.
     <FieldGroup heading={heading} description={description} error={error} atRoot={path === ''}>
-      <Field label={pickerLabel(model.discriminator, model.variants, root)}>
+      <Field
+        label={pickerLabel(model.discriminator, model.variants, root)}
+        error={switching.failure}
+      >
         <Select
           options={options}
           value={index === -1 ? '' : String(index)}
@@ -159,6 +167,7 @@ export function UnionField({
         <div className={groupClass}>
           <ObjectFields
             properties={activeClassified.model.properties}
+            shape={activeClassified.model.shape}
             requiredKeys={activeClassified.model.required}
             root={root}
             value={value}

package/src/schema-form/union.ts

@@ -1,18 +1,24 @@
 /**
  * Which variant of a union a given value currently inhabits. Discriminated
- * unions read the tag property directly; plain unions score each object variant
- * by how many of its required properties the value carries (a best-effort match
- * when Pydantic emitted no discriminator). Returns `-1` when no variant is
- * active (an unset/`null` value, or nothing matches).
+ * unions read the tag property directly; plain unions score each variant that can
+ * hold an object by how many of its required properties the value carries (a
+ * best-effort match when Pydantic emitted no discriminator). Returns `-1` when no
+ * variant is active (an unset/`null` value, or nothing matches).
  */
 import type { UnionVariant } from './field-model';
-import { resolveRef } from './resolve';
+import { resolveRef, typeList } from './resolve';
 import type { JsonSchema } from './types';
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+/** Whether a resolved schema can hold an object: it is typed `object`, or untyped. */
+function holdsObject(schema: JsonSchema): boolean {
+  const types = typeList(schema);
+  return types.length === 0 || types.includes('object');
+}
+
 /** Whether a resolved scalar schema accepts the runtime type of `value`. */
 function scalarSchemaAccepts(schema: JsonSchema, value: unknown): boolean {
   if (schema.const !== undefined) return schema.const === value;
@@ -64,6 +70,7 @@ export function activeVariantIndex(
   let bestScore = -1;
   variants.forEach((variant, index) => {
     const resolved = resolveRef(variant.schema, root);
+    if (!holdsObject(resolved)) return;
     const required = resolved.required ?? [];
     let score = 0;
     for (const key of required) {

package/src/schema-form/validate.ts

@@ -508,6 +508,31 @@ function validateRecord(
   }
 }
 
+/**
+ * A templated-text value: an object carrying exactly one non-empty source — inline
+ * `content` or a stored template `id` — and, when present, a `kwargs` object.
+ */
+function validateTemplatedText(value: unknown, path: string, ctx: ValidateCtx): void {
+  if (!isRecord(value)) {
+    shapeError(ctx, path, 'must be an object');
+    return;
+  }
+  const content = ownValue(value, 'content');
+  const id = ownValue(value, 'id');
+  const hasContent = typeof content === 'string';
+  const hasId = typeof id === 'string';
+  if (hasContent === hasId) {
+    shapeError(ctx, path, 'must set exactly one of inline content or a stored template id');
+    return;
+  }
+  if ((hasContent ? content : id) === '') {
+    shapeError(ctx, path, 'needs inline content or a stored template');
+    return;
+  }
+  const kwargs = ownValue(value, 'kwargs');
+  if (kwargs !== undefined && !isRecord(kwargs)) shapeError(ctx, path, 'kwargs must be an object');
+}
+
 function validateUnion(
   model: ModelOf<'union'>,
   value: unknown,
@@ -569,6 +594,9 @@ function dispatchKind(model: FieldModel, value: unknown, path: string, ctx: Vali
     case 'record':
       validateRecord(model, value, path, ctx);
       return;
+    case 'templated-text':
+      validateTemplatedText(value, path, ctx);
+      return;
     case 'union':
       validateUnion(model, value, path, ctx);
       return;

package/src/search-match.ts

@@ -0,0 +1,41 @@
+/**
+ * The one text-search rule every Studio list applies: a case-insensitive substring
+ * match of the trimmed query against the texts the reader sees. A blank query matches
+ * everything.
+ */
+
+/**
+ * The query in the form a match compares: trimmed and lower-cased. A list that tests
+ * many texts against one query computes this once and hands it to {@link textHasNeedle}.
+ */
+export function searchNeedle(query: string): string {
+  return query.trim().toLowerCase();
+}
+
+/** True when `needle` (from {@link searchNeedle}) is blank or `loweredText` contains it. */
+export function textHasNeedle(loweredText: string, needle: string): boolean {
+  return needle === '' || loweredText.includes(needle);
+}
+
+/**
+ * True when `query` holds nothing but blanks, so it matches every text: a list that
+ * draws itself differently while no search is active asks this.
+ */
+export function isBlankSearch(query: string): boolean {
+  return searchNeedle(query) === '';
+}
+
+/**
+ * True when any one of `texts` contains `query`, ignoring case and the query's
+ * surrounding blanks; a blank query matches every row. Each text is tested on its own,
+ * so a row searched by several fields (a name and a display name) never matches across
+ * the seam between two of them.
+ *
+ * @param query - what the reader typed.
+ * @param texts - the texts the row is searched by (for a row of the connector's tool
+ *   list, its `toolDisplayLabel`, which carries both the display name and the raw name).
+ */
+export function matchesSearch(query: string, ...texts: readonly string[]): boolean {
+  const needle = searchNeedle(query);
+  return needle === '' || texts.some((text) => textHasNeedle(text.toLowerCase(), needle));
+}

package/src/tool-organization.ts

@@ -0,0 +1,34 @@
+/**
+ * The tool-organization folder tree the package publishes: the folder model and its
+ * navigation, which folders a screen draws, the folder writes, filing one tool, and
+ * who may make each overlay write. Every screen that shows the tree composes these.
+ */
+export type {
+  CreateFolder,
+  FolderActionsMenuProps,
+  FoldersChanged,
+} from './components/folder-actions';
+export { FolderActionsMenu, useCreateFolder } from './components/folder-actions';
+export type { MoveToFolderDialogProps } from './components/folder-filing';
+export { MoveToFolderDialog } from './components/folder-filing';
+export type {
+  Folder,
+  FolderBreadcrumbProps,
+  FolderPickerProps,
+  FolderRowProps,
+} from './components/folder-nav';
+export {
+  childFolders,
+  FolderBreadcrumb,
+  folderPathTo,
+  FolderPicker,
+  FolderRow,
+  toFolders,
+} from './components/folder-nav';
+export { foldersForView } from './components/folder-occupancy';
+export type { ToolMetaWriteAccess } from './components/tool-meta-access';
+export {
+  ToolMetaWriteError,
+  useReportToolMetaRefusal,
+  useToolMetaWriteAccess,
+} from './components/tool-meta-access';