@tai42/studio-sdk 17.1.2 → 18.0.0

package/src/index.ts

@@ -221,6 +221,7 @@ export { Button, Card, EmptyState, ErrorState, Skeleton, Spinner } from './compo
 export type { RadioGroupProps, RadioOption } from './components/radio-group';
 export { RadioGroup } from './components/radio-group';
 export type {
+  OverflowAxis,
   OverflowRegionAttributes,
   ProseScrollLabels,
   ScrollRegionProps,
@@ -295,6 +296,8 @@ export { openTargetProps } from './components/open-target';
 // hands back the parsed URL, so a caller that needs the URL does not re-parse it.
 export type { CopyFieldProps } from './components/copy-field';
 export { CopyField } from './components/copy-field';
+export type { ExecutionKeyPickerProps, ExecutionKeyQuery } from './components/execution-key-picker';
+export { ExecutionKeyPicker, isExecutionKeyListEmpty } from './components/execution-key-picker';
 export type { ExtensionComboBuilderProps } from './components/extension-combo-builder';
 export { ExtensionComboBuilder } from './components/extension-combo-builder';
 export type { ExtensionFamily, ExtensionKindGroup } from './components/extension-grouping';
@@ -311,6 +314,14 @@ export type { ExternalLinkButtonProps } from './components/external-link';
 export { safeHttpUrl } from './components/primitives';
 export type { RevealInputProps } from './components/reveal-input';
 export { RevealInput } from './components/reveal-input';
+export type { SubjectSectionProps, SubjectTargetOption } from './components/subject-section';
+export {
+  buildSubject,
+  SUBJECT_INCOMPLETE_MESSAGE,
+  SubjectSection,
+  toSubjectTargetOptions,
+  useSubjectFields,
+} from './components/subject-section';
 export type { TokenName } from './components/tokens';
 export { TOKEN_NAMES } from './components/tokens';
 export type { ToolPickerProps } from './components/tool-picker';

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

@@ -11,6 +11,7 @@ import { classifySchema } from './classify';
 import { defaultValueForSchema } from './default-value';
 import { FieldGroup } from './field-group';
 import { FieldNode } from './field-node';
+import { useKeyedCallbacks } from './keyed-callbacks';
 import type { JsonSchema, SchemaFormErrors } from './types';
 
 export function ArrayField({
@@ -46,6 +47,7 @@ export function ArrayField({
   const setItem = (index: number, next: unknown): void => {
     onChange(list.map((item, position) => (position === index ? next : item)));
   };
+  const changeFor = useKeyedCallbacks<number, unknown>(setItem, list.keys());
 
   return (
     <FieldGroup heading={heading} description={description} error={error} atRoot={false}>
@@ -63,9 +65,7 @@ export function ArrayField({
               schema={items}
               root={root}
               value={item}
-              onChange={(next) => {
-                setItem(index, next);
-              }}
+              onChange={changeFor(index)}
               path={`${path}[${String(index)}]`}
               label={`Item ${String(index + 1)}`}
               required

package/src/schema-form/context.ts

@@ -52,6 +52,23 @@ export interface ExpressionInputKey {
   readonly gloss: string;
 }
 
+/**
+ * One named jq variable the form hands the door beside `.`, mirroring jq-studio's
+ * variable descriptor without importing it. The door lists it in the legend, offers
+ * `$name` as a path root, and seeds the Test panel with its `sample`.
+ */
+export interface ExpressionInputVariable {
+  /** The variable name WITHOUT the leading `$` (referenced as `$name`). */
+  readonly name: string;
+  /** One sentence: what this variable holds. */
+  readonly blurb: string;
+  /** The top-level keys of the variable's value; empty when it is a scalar or
+   *  the annotation glosses none. */
+  readonly keys: readonly ExpressionInputKey[];
+  /** A static skeleton of the variable's value for the door's Test panel. */
+  readonly sample?: unknown;
+}
+
 /**
  * What `.` IS for an expression-annotated field, as the form hands it to the
  * injected door. Built by the renderer from the schema's `x-tai42-expression`
@@ -77,6 +94,9 @@ export interface ExpressionInputShape {
   readonly caveats?: readonly string[];
   /** A static skeleton of `.` for the door's test surface. */
   readonly sample?: unknown;
+  /** The named variables the expression reads as `$name` beside `.`; omitted when
+   *  the field declares none. */
+  readonly variables?: readonly ExpressionInputVariable[];
 }
 
 /**

package/src/schema-form/field-model.ts

@@ -34,6 +34,23 @@ export interface ExpressionAnnotationKey {
   readonly gloss: string;
 }
 
+/**
+ * One named jq variable the expression may read as `$name` beside its `.` input:
+ * its blurb and a representative sample the editor's Test panel binds it to. The
+ * `x-tai42-expression` annotation carries these under `variables`; a field whose
+ * `.` is its only input carries none.
+ */
+export interface ExpressionAnnotationVariable {
+  readonly name: string;
+  readonly blurb: string;
+  /** True when the annotation carries a `sample` for this variable — tracked
+   *  separately because a legitimate sample may be JSON `null`. */
+  readonly hasSample: boolean;
+  /** The sample value the Test panel binds `$name` to. Meaningful only when
+   *  {@link hasSample} is true. */
+  readonly sample: unknown;
+}
+
 /**
  * The `x-tai42-expression` annotation on a string schema: the server declares
  * that the field's value is authored in a pipeline expression language (only jq
@@ -53,6 +70,9 @@ export interface ExpressionAnnotation {
   readonly blurb: string | undefined;
   /** The top-level keys of `.`, each with a one-liner. */
   readonly keys: readonly ExpressionAnnotationKey[] | undefined;
+  /** The named variables the expression reads as `$name` beside `.`. Absent when
+   *  the annotation declares none (the field's `.` is its only input). */
+  readonly variables: readonly ExpressionAnnotationVariable[] | undefined;
   /** What the expression must return (e.g. "true or false"). */
   readonly returns: string | undefined;
   /** Per-field caveats. */

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

@@ -4,7 +4,7 @@
  * inline; every other kind delegates to a dedicated field component). Object,
  * array, and union renderers recurse back through here for their children.
  */
-import type { ReactNode } from 'react';
+import { memo, type ReactNode } from 'react';
 
 import { Checkbox } from '../components/checkbox';
 import { Field } from '../components/field';
@@ -45,8 +45,14 @@ function labelText(explicit: string | undefined, label: string | undefined): str
   return explicit ?? label ?? 'Value';
 }
 
-/** A single schema node, dispatched on its classified model kind. */
-export function FieldNode(props: FieldNodeProps): ReactNode {
+/**
+ * A single schema node, dispatched on its classified model kind. Wrapped in
+ * `memo` so a field whose props are unchanged is skipped: the containers hand
+ * each child a referentially-stable `onChange` (see {@link useKeyedCallbacks})
+ * and the controlled value keeps unedited branches identity-equal, so editing
+ * one field re-renders only that field's subtree, not every sibling.
+ */
+function FieldNodeImpl(props: FieldNodeProps): ReactNode {
   const { root, value, onChange, path, required, idPrefix, errors } = props;
   const classified = classifySchema(props.schema, root);
   const base = labelText(classified.title, props.label);
@@ -187,6 +193,8 @@ export function FieldNode(props: FieldNodeProps): ReactNode {
   }
 }
 
+export const FieldNode = memo(FieldNodeImpl);
+
 /** The label/description/error chrome every scalar leaf field shares. */
 interface ScalarFieldChrome {
   readonly heading: string;

package/src/schema-form/keyed-callbacks.ts

@@ -0,0 +1,46 @@
+/**
+ * A stable per-key callback factory. A container (object, array, record) renders
+ * one child per key and folds that child's edits back into the container value.
+ * Written inline, each child's `onChange` is a fresh closure every render, which
+ * defeats {@link FieldNode}'s `memo`: an untouched sibling re-renders whenever any
+ * field changes. This returns the SAME function identity for a given key across
+ * renders — so a memoized child keyed on that identity is skipped when a sibling
+ * changes — while each call reads the latest folding logic through a ref, so the
+ * callback never closes over a stale container value.
+ *
+ * The cache is bounded by `liveKeys`, the container's current key set: every
+ * render evicts each cached handler whose key is not live, so a mounted form that
+ * adds and drops entries holds at most one handler per live key (the record
+ * field keys by a monotonic row id, so without eviction it would leak one dead
+ * handler per id ever created). Eviction runs during render on the ref-held Map —
+ * no effect, no extra render — and never touches a live key's handler, so
+ * identity stays stable for every key that survives the render.
+ */
+import { useRef } from 'react';
+
+export function useKeyedCallbacks<K, A>(
+  fold: (key: K, arg: A) => void,
+  liveKeys: Iterable<K>,
+): (key: K) => (arg: A) => void {
+  const foldRef = useRef(fold);
+  foldRef.current = fold;
+  // The cache lives in a ref, lazily initialised, so its identity is HARD-stable
+  // for the component's whole life: a `useMemo(() => new Map(), [])` cache is only
+  // a hint React may discard, which would drop every cached handler and re-render
+  // every sibling — the regression the memo is here to prevent.
+  const cacheRef = useRef<Map<K, (arg: A) => void> | undefined>(undefined);
+  const cache = (cacheRef.current ??= new Map<K, (arg: A) => void>());
+  const live = new Set<K>(liveKeys);
+  for (const key of cache.keys()) {
+    if (!live.has(key)) cache.delete(key);
+  }
+  return (key: K) => {
+    const cached = cache.get(key);
+    if (cached !== undefined) return cached;
+    const handler = (arg: A): void => {
+      foldRef.current(key, arg);
+    };
+    cache.set(key, handler);
+    return handler;
+  };
+}

package/src/schema-form/object-fields.tsx

@@ -7,6 +7,7 @@
 import type { ReactNode } from 'react';
 
 import { FieldNode } from './field-node';
+import { useKeyedCallbacks } from './keyed-callbacks';
 import type { JsonSchema, SchemaFormErrors } from './types';
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
@@ -38,6 +39,12 @@ export function ObjectFields({
   markRequired?: boolean;
 }): ReactNode {
   const obj = isPlainObject(value) ? value : {};
+  const changeFor = useKeyedCallbacks<string, unknown>(
+    (name, next) => {
+      onChange(setKey(obj, name, next));
+    },
+    properties.map(([name]) => name),
+  );
   return (
     <>
       {properties.map(([name, propSchema]) => {
@@ -49,9 +56,7 @@ export function ObjectFields({
             schema={propSchema}
             root={root}
             value={obj[name]}
-            onChange={(next) => {
-              onChange(setKey(obj, name, next));
-            }}
+            onChange={changeFor(name)}
             path={childPath}
             label={name}
             required={requiredKeys.has(name)}

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

@@ -22,6 +22,7 @@ import { RecordEntryRendererContext } from './context';
 import { defaultValueForSchema } from './default-value';
 import { FieldGroup } from './field-group';
 import { FieldNode } from './field-node';
+import { useKeyedCallbacks } from './keyed-callbacks';
 import type { JsonSchema, SchemaFormErrors } from './types';
 
 interface Row {
@@ -119,6 +120,10 @@ export function RecordField({
   const setValue = (id: number, next: unknown): void => {
     commit(rows.map((row) => (row.id === id ? { ...row, value: next } : row)));
   };
+  const valueChangeFor = useKeyedCallbacks<number, unknown>(
+    setValue,
+    rows.map((row) => row.id),
+  );
   const addRow = (): void => {
     commit([...rows, { id: nextId.current++, key: '', value: newEntryValue(values, root) }]);
   };
@@ -146,9 +151,7 @@ export function RecordField({
             schema={values}
             root={root}
             value={row.value}
-            onChange={(next) => {
-              setValue(row.id, next);
-            }}
+            onChange={valueChangeFor(row.id)}
             path={entryPath}
             label={undefined}
             required
@@ -179,9 +182,7 @@ export function RecordField({
                     path: entryPath,
                     valueSchema: values,
                     value: row.value,
-                    onChange: (next) => {
-                      setValue(row.id, next);
-                    },
+                    onChange: valueChangeFor(row.id),
                     defaultField,
                   })}
             </div>

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

@@ -6,7 +6,12 @@
  * renders differently from the plain string it falls back to.
  */
 import { isRecord } from '../guards';
-import type { ExpressionAnnotation, ExpressionAnnotationKey, MediaUpload } from './field-model';
+import type {
+  ExpressionAnnotation,
+  ExpressionAnnotationKey,
+  ExpressionAnnotationVariable,
+  MediaUpload,
+} from './field-model';
 import type { JsonSchema } from './types';
 
 const EXPRESSION_KEYWORD = 'x-tai42-expression';
@@ -58,6 +63,29 @@ function parseAnnotationKeys(
   return keys;
 }
 
+/** Parse the optional `variables` array: absent → `undefined`, malformed → `null`
+ *  (reject). Each entry needs a string `name` and `blurb`; `sample` is any JSON
+ *  (including `null`), so its presence is tracked rather than typed. */
+function parseAnnotationVariables(
+  value: unknown,
+): readonly ExpressionAnnotationVariable[] | undefined | null {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value)) return null;
+  const variables: ExpressionAnnotationVariable[] = [];
+  for (const entry of value as readonly unknown[]) {
+    if (!isRecord(entry) || typeof entry.name !== 'string' || typeof entry.blurb !== 'string') {
+      return null;
+    }
+    variables.push({
+      name: entry.name,
+      blurb: entry.blurb,
+      hasSample: 'sample' in entry,
+      sample: entry.sample,
+    });
+  }
+  return variables;
+}
+
 /** Parse the optional `caveats` array: absent → `undefined`, malformed → `null` (reject). */
 function parseCaveatList(value: unknown): readonly string[] | undefined | null {
   if (value === undefined) return undefined;
@@ -94,6 +122,8 @@ export function expressionAnnotation(schema: JsonSchema): ExpressionAnnotation |
 
   const keys = parseAnnotationKeys(raw.keys);
   if (keys === null) return undefined;
+  const variables = parseAnnotationVariables(raw.variables);
+  if (variables === null) return undefined;
   const caveats = parseCaveatList(raw.caveats);
   if (caveats === null) return undefined;
 
@@ -103,6 +133,7 @@ export function expressionAnnotation(schema: JsonSchema): ExpressionAnnotation |
     label: label.value,
     blurb: blurb.value,
     keys,
+    variables,
     returns: returns.value,
     caveats,
     hasSample: 'sample' in raw,

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

@@ -296,12 +296,14 @@ function expressionShape(
   argName: string,
 ): ExpressionInputShape | undefined {
   const declared =
-    expression.label !== undefined ||
-    expression.blurb !== undefined ||
-    expression.keys !== undefined ||
-    expression.returns !== undefined ||
-    expression.caveats !== undefined ||
-    expression.hasSample;
+    [
+      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).
@@ -312,6 +314,23 @@ function expressionShape(
     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 } : {}),
   };
 }
 

package/src/testing.ts

@@ -109,25 +109,33 @@ export function flushResizeObserversFor(target: Element): void {
   }
 }
 
-/** The faked widths: equal reads as "fits", unequal as "scrolls". */
-const FITTING_WIDTH = 100;
-const OVERFLOWING_SCROLL_WIDTH = 400;
+/** The faked extents: equal reads as "fits", unequal as "scrolls". */
+const FITTING_EXTENT = 100;
+const OVERFLOWING_SCROLL_EXTENT = 400;
 
 /**
- * Makes `element` report itself as horizontally overflowing (or not). jsdom runs
- * no layout, so `scrollWidth` and `clientWidth` are both 0 and every
- * overflow test reads as "fits"; this shadows the prototype getters with own,
- * configurable values so a test can drive either state. Call it again with the
- * opposite flag to flip the element back.
+ * Makes `element` report itself as overflowing (or not) on `axis`. jsdom runs no
+ * layout, so `scroll*` and `client*` are both 0 and every overflow test reads as
+ * "fits"; this shadows the prototype getters with own, configurable values so a
+ * test can drive either state. Call it again with the opposite flag to flip the
+ * element back.
  *
  * @param element - the element whose scroll metrics to fake.
- * @param overflowing - true to report content wider than the box.
+ * @param overflowing - true to report content larger than the box on `axis`.
+ * @param axis - the dimension to fake: `horizontal` (width, the default) or
+ *   `vertical` (height).
  */
-export function setElementOverflow(element: HTMLElement, overflowing: boolean): void {
-  Object.defineProperty(element, 'clientWidth', { configurable: true, value: FITTING_WIDTH });
-  Object.defineProperty(element, 'scrollWidth', {
+export function setElementOverflow(
+  element: HTMLElement,
+  overflowing: boolean,
+  axis: 'horizontal' | 'vertical' = 'horizontal',
+): void {
+  const [client, scroll] =
+    axis === 'vertical' ? ['clientHeight', 'scrollHeight'] : ['clientWidth', 'scrollWidth'];
+  Object.defineProperty(element, client, { configurable: true, value: FITTING_EXTENT });
+  Object.defineProperty(element, scroll, {
     configurable: true,
-    value: overflowing ? OVERFLOWING_SCROLL_WIDTH : FITTING_WIDTH,
+    value: overflowing ? OVERFLOWING_SCROLL_EXTENT : FITTING_EXTENT,
   });
 }