@tai42/studio-sdk 17.1.5 → 18.1.0

package/src/components/overflow-measure.ts

@@ -7,12 +7,23 @@
 
 export const SCROLL_REGION_CLASS = 'tai-scroll-region';
 
-export function overflows(element: HTMLElement): boolean {
-  return element.scrollWidth > element.clientWidth;
+/**
+ * The axis a scroll region is measured on. A prose table or a code line scrolls
+ * SIDEWAYS (`horizontal`, the default); a bounded, capped-height list scrolls
+ * DOWN (`vertical`). Both wear the same conditional region attributes — only the
+ * dimension read to decide whether they overflow differs.
+ */
+export type OverflowAxis = 'horizontal' | 'vertical';
+
+export function overflows(element: HTMLElement, axis: OverflowAxis = 'horizontal'): boolean {
+  return axis === 'vertical'
+    ? element.scrollHeight > element.clientHeight
+    : element.scrollWidth > element.clientWidth;
 }
 
 /**
- * Whether the element should carry the region attributes right now.
+ * Whether the element should carry the region attributes right now, measured on
+ * `axis`.
  *
  * A region that stops overflowing keeps its tab stop for as long as it holds
  * focus: taking `tabindex` off the focused element drops the reader onto the
@@ -20,8 +31,8 @@ export function overflows(element: HTMLElement): boolean {
  * already has the stop can be the active element, so this can hold a stop open
  * but never invent one.
  */
-export function needsRegion(element: HTMLElement): boolean {
-  return overflows(element) || element.ownerDocument.activeElement === element;
+export function needsRegion(element: HTMLElement, axis: OverflowAxis = 'horizontal'): boolean {
+  return overflows(element, axis) || element.ownerDocument.activeElement === element;
 }
 
 /** A tracked scrollable surface, with the name it wears while it scrolls. */

package/src/components/scroll-region.tsx

@@ -34,6 +34,7 @@ import {
 import {
   clearScrollRegionAttributes,
   needsRegion,
+  type OverflowAxis,
   refreshRegions,
   SCROLL_REGION_CLASS,
   type TrackedSurface,
@@ -46,12 +47,20 @@ import {
   uniquelyNamed,
 } from './prose-regions';
 
+export type { OverflowAxis } from './overflow-measure';
+
 export interface ScrollRegionProps {
   /** The region's accessible name, applied only while it actually scrolls. */
   readonly label: string;
   readonly children: ReactNode;
   readonly className?: string;
   readonly style?: CSSProperties;
+  /**
+   * The dimension overflow is measured on. `horizontal` (the default) fits a pane
+   * that scrolls sideways; `vertical` fits a bounded, capped-height box that scrolls
+   * down. The caller styles the box's own overflow to match.
+   */
+  readonly axis?: OverflowAxis;
   /**
    * The one arbitrary attribute this component forwards. The measured attributes
    * — `tabindex`, `role` and `aria-label` — are the component's own and appear
@@ -118,10 +127,13 @@ export interface OverflowRegionAttributes {
  *
  * @param ref - a consumer ref that wants the same element, or `undefined`.
  * @param label - its accessible name, applied only while it actually scrolls.
+ * @param axis - the dimension to measure overflow on (`horizontal` by default;
+ *   `vertical` for a bounded, capped-height box that scrolls down).
  */
 export function useOverflowRegion(
   ref: Ref<HTMLElement> | undefined,
   label: string,
+  axis: OverflowAxis = 'horizontal',
 ): OverflowRegionAttributes {
   const [scrollable, setScrollable] = useState(false);
 
@@ -132,7 +144,7 @@ export function useOverflowRegion(
       const detachConsumer = attachRef(ref, box);
 
       const measure = (): void => {
-        setScrollable(needsRegion(box));
+        setScrollable(needsRegion(box, axis));
       };
 
       // The box gives resize; its children give the overflowing width. The
@@ -177,7 +189,7 @@ export function useOverflowRegion(
         detachConsumer();
       };
     },
-    [ref],
+    [ref, axis],
   );
 
   if (!scrollable) return { ref: measuredRef };
@@ -189,10 +201,11 @@ export function ScrollRegion({
   children,
   className,
   style,
+  axis,
   'data-testid': testId,
   ref,
 }: ScrollRegionProps) {
-  const region = useOverflowRegion(ref, label);
+  const region = useOverflowRegion(ref, label, axis);
 
   return (
     <div

package/src/components/subject-section.tsx

@@ -0,0 +1,177 @@
+/**
+ * The optional-subject sub-form shared by every form that keys a run's state to a
+ * conversation subject (the add-schedule dialog and the tool run panel). A collapsible
+ * block whose target / kind / key fields render only while expanded, so a form's default
+ * (collapsed) shape sends no subject.
+ *
+ * Presentational and prop-driven, like {@link ExecutionKeyPicker}: the host feature owns
+ * the conversation-targets query (the SDK holds no data-fetching library) and hands the
+ * resolved `targetOptions` in. {@link useSubjectFields} owns the field state; the host
+ * feature wraps it with its own targets query under its own query-key namespace. The
+ * caption and the two placeholders are the only copy that differs between hosts, so they
+ * are props.
+ */
+import type { StateSubject } from '@tai42/api-client';
+import { type ReactNode, useState } from 'react';
+
+import { Field } from './field';
+import { TextInput } from './inputs';
+import { Select } from './select';
+
+/** One conversation-target option: `target_kind:target_name` value, `kind · name` label. */
+export interface SubjectTargetOption {
+  readonly value: string;
+  readonly label: string;
+}
+
+/** The message a partially-filled subject is refused with (all three fields or none). */
+export const SUBJECT_INCOMPLETE_MESSAGE = 'A subject needs a target, a kind, and a key.';
+
+/** Map the conversation routes read to the target select's options. */
+export function toSubjectTargetOptions(
+  routes: readonly { readonly target_kind: string; readonly target_name: string }[],
+): SubjectTargetOption[] {
+  return routes.map((route) => ({
+    value: `${route.target_kind}:${route.target_name}`,
+    label: `${route.target_kind} · ${route.target_name}`,
+  }));
+}
+
+/**
+ * Build a {@link StateSubject} from the sub-form values: `null` when untouched (no
+ * subject), a subject when target, kind and key are all set, or a loud failure when only
+ * some are — never a silently dropped partial subject. The target splits on its FIRST
+ * colon, so a target name may itself contain one.
+ */
+export function buildSubject(v: {
+  readonly target: string;
+  readonly kind: string;
+  readonly key: string;
+}): { ok: true; subject: StateSubject | null } | { ok: false; message: string } {
+  const touched = v.target !== '' || v.kind.trim() !== '' || v.key.trim() !== '';
+  if (!touched) return { ok: true, subject: null };
+  const separator = v.target.indexOf(':');
+  const targetKind = separator < 0 ? '' : v.target.slice(0, separator);
+  const targetName = separator < 0 ? '' : v.target.slice(separator + 1);
+  if (targetKind === '' || targetName === '' || v.kind.trim() === '' || v.key.trim() === '') {
+    return { ok: false, message: SUBJECT_INCOMPLETE_MESSAGE };
+  }
+  // The target is chosen from the conversation-routes options, so its kind is one of the
+  // route target kinds; the value carries it as text and this narrows it to the subject's
+  // union without a runtime schema (the SDK holds no api-client value import).
+  return {
+    ok: true,
+    subject: {
+      target_kind: targetKind as StateSubject['target_kind'],
+      target_name: targetName,
+      kind: v.kind.trim(),
+      key: v.key.trim(),
+    },
+  };
+}
+
+/** Subject field state + setters + the collapse toggle. The host feature owns the
+ *  open-gated conversation-targets query and derives `targetOptions` from it. */
+export function useSubjectFields() {
+  const [target, setTarget] = useState('');
+  const [kind, setKind] = useState('');
+  const [key, setKey] = useState('');
+  const [error, setError] = useState<string | null>(null);
+  const [open, setOpen] = useState(false);
+  return { target, setTarget, kind, setKind, key, setKey, error, setError, open, setOpen };
+}
+
+export interface SubjectSectionProps {
+  readonly open: boolean;
+  readonly onToggle: () => void;
+  readonly target: string;
+  readonly onTargetChange: (value: string) => void;
+  readonly kind: string;
+  readonly onKindChange: (value: string) => void;
+  readonly subjectKey: string;
+  readonly onKeyChange: (value: string) => void;
+  readonly error: string | null;
+  readonly targetOptions: readonly SubjectTargetOption[];
+  /** The block's descriptive caption, shown under the expanded header. */
+  readonly caption: string;
+  /** The target select's empty-choice placeholder. */
+  readonly targetPlaceholder: string;
+  /** The Subject key field's helper description. */
+  readonly subjectKeyDescription: string;
+}
+
+export function SubjectSection({
+  open,
+  onToggle,
+  target,
+  onTargetChange,
+  kind,
+  onKindChange,
+  subjectKey,
+  onKeyChange,
+  error,
+  targetOptions,
+  caption,
+  targetPlaceholder,
+  subjectKeyDescription,
+}: SubjectSectionProps): ReactNode {
+  return (
+    <div>
+      <button
+        type="button"
+        className="tai-btn tai-btn-ghost"
+        aria-expanded={open}
+        onClick={onToggle}
+      >
+        Subject (optional)
+      </button>
+      {open ? (
+        <div
+          style={{
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 'var(--tai-space-3)',
+            marginTop: 'var(--tai-space-3)',
+          }}
+        >
+          <p style={{ margin: 0, color: 'var(--tai-color-text-muted)' }}>{caption}</p>
+          <Field label="Target">
+            <Select
+              value={target}
+              onValueChange={onTargetChange}
+              aria-label="Subject target"
+              placeholder={targetPlaceholder}
+              options={targetOptions}
+            />
+          </Field>
+          <Field
+            label="Subject kind"
+            description="The subject family the state declares (e.g. person)."
+          >
+            <TextInput
+              value={kind}
+              placeholder="e.g. person"
+              onChange={(event) => {
+                onKindChange(event.target.value);
+              }}
+            />
+          </Field>
+          <Field label="Subject key" description={subjectKeyDescription}>
+            <TextInput
+              value={subjectKey}
+              placeholder="e.g. a-42"
+              onChange={(event) => {
+                onKeyChange(event.target.value);
+              }}
+            />
+          </Field>
+          {error !== null ? (
+            <p role="alert" style={{ margin: 0, color: 'var(--tai-color-err-text)' }}>
+              {error}
+            </p>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/components/tool-picker.tsx

@@ -38,6 +38,11 @@ import { ALL_TAGS, SelectedToolBadges, TagFilterField, ToolSelect } from './tool
 
 export { BADGES_NOTE } from './tool-picker-parts';
 
+/** The trigger copy when the picker has no option to offer at all (after exclusions).
+ *  Shown only once the list has settled — a still-loading picker keeps its own
+ *  placeholder — so it never misreads a pending fetch as "nothing to pick". */
+const NO_TOOLS_AVAILABLE = 'No tools available';
+
 export interface ToolPickerProps {
   readonly toolNames: readonly string[];
   readonly value: string | null;
@@ -94,6 +99,13 @@ export function ToolPicker({
   const excluded = new Set(excludeNames ?? []);
   const available = toolNames.filter((name) => !excluded.has(name));
 
+  // A settled, empty option set (not a load in progress) is a "nothing to pick"
+  // state: the trigger reads the empty copy and cannot open onto an empty popup. The
+  // caller's `disabled` still marks a loading picker, which keeps its own placeholder.
+  const noneAvailable = available.length === 0;
+  const pickerDisabled = disabled === true || noneAvailable;
+  const pickerPlaceholder = noneAvailable && disabled !== true ? NO_TOOLS_AVAILABLE : placeholder;
+
   // Distinct tags across the available tools, sorted, feeding the filter control.
   const allTags =
     tagsByTool === undefined
@@ -113,9 +125,9 @@ export function ToolPicker({
       filtered={filtered}
       value={value}
       onChange={onChange}
-      placeholder={placeholder}
+      placeholder={pickerPlaceholder}
       ariaLabel={ariaLabel}
-      disabled={disabled}
+      disabled={pickerDisabled}
       displayNames={displayNames}
       agentToolNames={agentToolNames}
     />

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/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/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,
   });
 }