@tai42/studio-sdk 15.0.0 → 16.0.1

package/src/schema-form/default-value.ts

@@ -16,8 +16,11 @@
  * empty value so the committed seed validates against its own schema.
  */
 import { classifySchema } from './classify';
+import type { FieldModel } from './field-model';
 import type { JsonSchema } from './types';
 
+type ModelOf<K extends FieldModel['kind']> = Extract<FieldModel, { kind: K }>;
+
 /** The explicit `default` (wrapper takes precedence over the resolved node), if any. */
 function explicitDefault(
   raw: JsonSchema,
@@ -52,6 +55,48 @@ export function skeletonValueForSchema(schema: JsonSchema, root: JsonSchema = sc
   return seedValue(schema, root, true);
 }
 
+/**
+ * Seed an object's required nested structure and any optional property that
+ * carries an explicit default. A required property recurses; an optional one is
+ * materialized only when it declares a `default`, so its own required children
+ * never raise errors on a field the user did not opt into.
+ */
+function seedObject(
+  model: ModelOf<'object'>,
+  root: JsonSchema,
+  mintScalars: boolean,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [name, propSchema] of model.properties) {
+    if (model.required.has(name)) {
+      const seeded = seedValue(propSchema, root, mintScalars);
+      if (seeded !== undefined) result[name] = seeded;
+      continue;
+    }
+    const propClassified = classifySchema(propSchema, root);
+    const propDefault = explicitDefault(propSchema, propClassified.schema);
+    if (propDefault.present) result[name] = propDefault.value;
+  }
+  return result;
+}
+
+/**
+ * The empty value a required scalar mints in a committed skeleton: strings `''`,
+ * numbers `0`, booleans `false`. Absent (left value-less) on the default path,
+ * where a fresh form should flag the missing required scalar instead.
+ */
+function seedScalar(kind: 'string' | 'number' | 'boolean', mintScalars: boolean): unknown {
+  if (!mintScalars) return undefined;
+  switch (kind) {
+    case 'string':
+      return '';
+    case 'number':
+      return 0;
+    case 'boolean':
+      return false;
+  }
+}
+
 /**
  * The shared seeding walk. `mintScalars` distinguishes the two entry points
  * above: `false` leaves value-less required scalars absent; `true` mints their
@@ -66,30 +111,16 @@ function seedValue(schema: JsonSchema, root: JsonSchema, mintScalars: boolean):
   switch (model.kind) {
     case 'const':
       return model.value;
-    case 'object': {
-      const result: Record<string, unknown> = {};
-      for (const [name, propSchema] of model.properties) {
-        if (model.required.has(name)) {
-          const seeded = seedValue(propSchema, root, mintScalars);
-          if (seeded !== undefined) result[name] = seeded;
-          continue;
-        }
-        const propClassified = classifySchema(propSchema, root);
-        const propDefault = explicitDefault(propSchema, propClassified.schema);
-        if (propDefault.present) result[name] = propDefault.value;
-      }
-      return result;
-    }
+    case 'object':
+      return seedObject(model, root, mintScalars);
     case 'array':
       return [];
     case 'record':
       return {};
     case 'string':
-      return mintScalars ? '' : undefined;
     case 'number':
-      return mintScalars ? 0 : undefined;
     case 'boolean':
-      return mintScalars ? false : undefined;
+      return seedScalar(model.kind, mintScalars);
     case 'enum':
     case 'union':
     case 'json':

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

@@ -9,7 +9,7 @@ import type { ReactNode } from 'react';
 import { Field } from '../components/field';
 import { RadioGroup } from '../components/radio-group';
 import { Select } from '../components/select';
-import type { FieldModel } from './classify';
+import type { FieldModel } from './field-model';
 
 const RADIO_MAX_OPTIONS = 3;
 

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

@@ -0,0 +1,133 @@
+/**
+ * The renderer-facing result types produced by `classifySchema`: the discriminated
+ * `FieldModel`, the `ClassifiedField` envelope, and the annotation/variant shapes
+ * they carry. Kept apart from the classifier logic so both the renderer and the
+ * validator import the vocabulary without pulling in classification code.
+ */
+import type { EnumOption } from './resolve';
+import type { JsonSchema } from './types';
+
+/**
+ * How a string field accepts binary content as a JSON-serializable string.
+ * Derived from a field's JSON-Schema media annotations (see the `SchemaForm` module).
+ */
+export interface MediaUpload {
+  /**
+   * `base64` — the emitted value is the raw base64 body (no `data:` prefix),
+   * matching `contentEncoding: "base64"`. `data-url` — the emitted value is a
+   * full `data:<mime>;base64,<body>` URL, matching `format: "data-url"`.
+   */
+  readonly encoding: 'base64' | 'data-url';
+  /**
+   * The `contentMediaType` constraint (e.g. `image/*`, `application/pdf`), used
+   * for MIME validation and the file picker's `accept`. `undefined` for a bare
+   * `format: "data-url"` field with no declared type.
+   */
+  readonly mediaType: string | undefined;
+  /** A per-field byte cap from `contentMaxBytes`, if the schema pins one. */
+  readonly maxBytes: number | undefined;
+}
+
+/** One top-level key of the expression's input document, with a one-line gloss. */
+export interface ExpressionAnnotationKey {
+  readonly name: string;
+  readonly gloss: string;
+}
+
+/**
+ * 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
+ * today) and optionally describes what `.` is for that expression. The renderer
+ * uses it to open the visual-editor door instead of a plain text box. The shape
+ * mirrors jq-studio's input-shape descriptor WITHOUT importing it — classification
+ * stays a pure schema concern; the renderer maps this onto a jq field declaration.
+ */
+export interface ExpressionAnnotation {
+  /** The declared language. An unknown language never reaches here — it classifies
+   *  as a plain string, so an older client renders a newer server's field as the
+   *  ordinary text input it always was. */
+  readonly language: 'jq';
+  /** Short chip label for what `.` is (e.g. "node envelope"). */
+  readonly label: string | undefined;
+  /** One sentence describing what `.` is in this field. */
+  readonly blurb: string | undefined;
+  /** The top-level keys of `.`, each with a one-liner. */
+  readonly keys: readonly ExpressionAnnotationKey[] | undefined;
+  /** What the expression must return (e.g. "true or false"). */
+  readonly returns: string | undefined;
+  /** Per-field caveats. */
+  readonly caveats: readonly string[] | undefined;
+  /** True when the annotation carries a `sample` — tracked separately because a
+   *  legitimate sample may be JSON `null`. */
+  readonly hasSample: boolean;
+  /** A static skeleton of `.` for the Test panel. Meaningful only when
+   *  {@link hasSample} is true. */
+  readonly sample: unknown;
+}
+
+/** One selectable variant of a union field. */
+export interface UnionVariant {
+  readonly label: string;
+  /** The discriminator tag value, or `undefined` for a non-discriminated union. */
+  readonly tag: unknown;
+  /** The variant schema as written (unresolved — the renderer resolves it). */
+  readonly schema: JsonSchema;
+}
+
+/** The renderer-facing classification of a schema node. */
+export type FieldModel =
+  | { readonly kind: 'const'; readonly value: unknown }
+  | { readonly kind: 'enum'; readonly options: readonly EnumOption[] }
+  | {
+      readonly kind: 'string';
+      readonly format: string | undefined;
+      /** Present when media annotations opt the field into the upload control. */
+      readonly media: MediaUpload | undefined;
+      /** Present when a well-formed `x-tai42-expression` annotation opts the
+       *  field into the jq expression editor (see {@link ExpressionAnnotation}). */
+      readonly expression: ExpressionAnnotation | undefined;
+    }
+  | { readonly kind: 'number'; readonly integer: boolean }
+  | { readonly kind: 'boolean' }
+  | { readonly kind: 'array'; readonly items: JsonSchema }
+  | {
+      readonly kind: 'object';
+      readonly properties: readonly (readonly [string, JsonSchema])[];
+      readonly required: ReadonlySet<string>;
+    }
+  | {
+      // A string-keyed map typed by `additionalProperties` (no fixed
+      // `properties`), edited as key/value rows. `values` is the entry value
+      // schema AS WRITTEN — the entry editor resolves any `$ref` itself, exactly
+      // as `array.items` is.
+      readonly kind: 'record';
+      readonly values: JsonSchema;
+    }
+  | {
+      readonly kind: 'union';
+      readonly variants: readonly UnionVariant[];
+      readonly discriminator: string | undefined;
+    }
+  | {
+      // A shape with no structured editor to build — a property-less object, a
+      // bare `additionalProperties`-open object, an items-less array, an empty/
+      // multi-type/`allOf` schema. It is NOT undroppable: every one of these still
+      // describes JSON, so the renderer edits it as free-form JSON in a mono
+      // textarea rather than dead-ending on a badge. `jsonType` is the container
+      // the schema commits to, so a valid buffer must parse to it (`'any'` = no
+      // constraint beyond "is JSON"); `reason` records which shape fell through.
+      readonly kind: 'json';
+      readonly jsonType: 'object' | 'array' | 'any';
+      readonly reason: string;
+    };
+
+/** A fully classified field: its model plus resolved metadata. */
+export interface ClassifiedField {
+  readonly model: FieldModel;
+  /** True when JSON `null` is an accepted value (a null-union member). */
+  readonly nullable: boolean;
+  /** The effective (ref-resolved) schema this classification describes. */
+  readonly schema: JsonSchema;
+  readonly title: string | undefined;
+  readonly description: string | undefined;
+}

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

@@ -47,24 +47,12 @@ function labelText(explicit: string | undefined, label: string | undefined): str
 
 /** A single schema node, dispatched on its classified model kind. */
 export function FieldNode(props: FieldNodeProps): ReactNode {
-  const {
-    schema,
-    root,
-    value,
-    onChange,
-    path,
-    label,
-    required,
-    markRequired = false,
-    errors,
-    idPrefix,
-  } = props;
-  const classified = classifySchema(schema, root);
-  const base = labelText(classified.title, label);
-  const heading = markRequired && required ? `${base} *` : base;
-  const description = classified.description;
+  const { root, value, onChange, path, required, idPrefix, errors } = props;
+  const classified = classifySchema(props.schema, root);
+  const base = labelText(classified.title, props.label);
+  const heading = props.markRequired === true && required ? `${base} *` : base;
+  const { model, description } = classified;
   const error = errors?.[path];
-  const model = classified.model;
 
   switch (model.kind) {
     case 'json':
@@ -81,9 +69,12 @@ export function FieldNode(props: FieldNodeProps): ReactNode {
       );
     case 'const':
       return (
-        <Field label={heading} description={description} error={error}>
-          <TextInput value={scalarLabel(model.value)} readOnly disabled />
-        </Field>
+        <ConstField
+          heading={heading}
+          description={description}
+          error={error}
+          constValue={model.value}
+        />
       );
     case 'enum':
       return (
@@ -113,27 +104,24 @@ export function FieldNode(props: FieldNodeProps): ReactNode {
       );
     case 'number':
       return (
-        <Field label={heading} description={description} error={error}>
-          <NumberInput
-            step={model.integer ? '1' : 'any'}
-            value={typeof value === 'number' ? value : ''}
-            onChange={(event) => {
-              const raw = event.target.value;
-              onChange(raw === '' ? undefined : Number(raw));
-            }}
-          />
-        </Field>
+        <NumberField
+          heading={heading}
+          description={description}
+          error={error}
+          integer={model.integer}
+          value={value}
+          onChange={onChange}
+        />
       );
     case 'boolean':
       return (
-        <Field label={heading} description={description} error={error}>
-          <Checkbox
-            checked={value === true}
-            onCheckedChange={(checked) => {
-              onChange(checked);
-            }}
-          />
-        </Field>
+        <BooleanField
+          heading={heading}
+          description={description}
+          error={error}
+          value={value}
+          onChange={onChange}
+        />
       );
     case 'array':
       return (
@@ -198,3 +186,71 @@ export function FieldNode(props: FieldNodeProps): ReactNode {
       );
   }
 }
+
+/** The label/description/error chrome every scalar leaf field shares. */
+interface ScalarFieldChrome {
+  readonly heading: string;
+  readonly description: string | undefined;
+  readonly error: string | undefined;
+}
+
+/** A `const`-pinned value: shown read-only, never editable. */
+function ConstField({
+  heading,
+  description,
+  error,
+  constValue,
+}: ScalarFieldChrome & { constValue: unknown }): ReactNode {
+  return (
+    <Field label={heading} description={description} error={error}>
+      <TextInput value={scalarLabel(constValue)} readOnly disabled />
+    </Field>
+  );
+}
+
+/** A number/integer field; an empty input clears the value to `undefined`. */
+function NumberField({
+  heading,
+  description,
+  error,
+  integer,
+  value,
+  onChange,
+}: ScalarFieldChrome & {
+  integer: boolean;
+  value: unknown;
+  onChange: (value: unknown) => void;
+}): ReactNode {
+  return (
+    <Field label={heading} description={description} error={error}>
+      <NumberInput
+        step={integer ? '1' : 'any'}
+        value={typeof value === 'number' ? value : ''}
+        onChange={(event) => {
+          const raw = event.target.value;
+          onChange(raw === '' ? undefined : Number(raw));
+        }}
+      />
+    </Field>
+  );
+}
+
+/** A boolean field rendered as a checkbox. */
+function BooleanField({
+  heading,
+  description,
+  error,
+  value,
+  onChange,
+}: ScalarFieldChrome & { value: unknown; onChange: (value: unknown) => void }): ReactNode {
+  return (
+    <Field label={heading} description={description} error={error}>
+      <Checkbox
+        checked={value === true}
+        onCheckedChange={(checked) => {
+          onChange(checked);
+        }}
+      />
+    </Field>
+  );
+}

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

@@ -13,7 +13,7 @@ import { XCircleIcon } from '../components/icons';
 import { Button } from '../components/primitives';
 import { Field, useFieldControl, type FieldControlProps } from '../components/field';
 import { TextInput } from '../components/inputs';
-import type { MediaUpload } from './classify';
+import type { MediaUpload } from './field-model';
 import { MaxUploadBytesContext } from './context';
 import { decodedByteSize, effectiveMaxBytes, overCapMessage } from './media';
 
@@ -114,9 +114,7 @@ export function MediaField({
   const defaultMax = useContext(MaxUploadBytesContext);
   const maxBytes = effectiveMaxBytes(media.maxBytes, defaultMax);
   const [uploadError, setUploadError] = useState<string | undefined>(undefined);
-  const [attached, setAttached] = useState<
-    { name: string; previewUrl: string; value: string } | undefined
-  >(undefined);
+  const [attached, setAttached] = useState<AttachedMedia | undefined>(undefined);
 
   const accept = (file: File | undefined): void => {
     if (file === undefined) return;
@@ -139,19 +137,7 @@ export function MediaField({
     onChange('');
   };
 
-  // The just-picked file's chip/preview applies ONLY while it still matches the
-  // current field value; if the value is reset or replaced externally (an edit
-  // loads a different record, or the form resets after submit), fall back to a
-  // value-derived display so a stale filename/thumbnail can never linger.
-  const activeAttached = attached?.value === value ? attached : undefined;
-  // Prefer the just-read preview; on an edit with a pre-existing data-url value,
-  // reconstruct the preview from the value itself.
-  const previewUrl =
-    activeAttached?.previewUrl ??
-    (media.encoding === 'data-url' && value.startsWith('data:') ? value : undefined);
-  const isImage =
-    media.mediaType?.startsWith('image/') === true || previewUrl?.startsWith('data:image') === true;
-  const fileName = activeAttached?.name ?? (value !== '' ? 'Attached file' : undefined);
+  const { previewUrl, isImage, fileName } = mediaPreview(attached, value, media);
 
   return (
     <Field label={heading} description={description} error={error}>
@@ -161,29 +147,12 @@ export function MediaField({
         onFile={accept}
       />
 
-      {fileName !== undefined ? (
-        <div className="tai-row">
-          {isImage && previewUrl !== undefined ? (
-            <img
-              src={previewUrl}
-              alt={fileName}
-              // A thumbnail is per-instance geometry: it is capped to a fixed
-              // height and can never exceed the width it is given.
-              style={{
-                maxWidth: '100%',
-                maxHeight: '6rem',
-                borderRadius: 'var(--tai-radius-md)',
-                border: '1px solid var(--tai-color-control-border)',
-              }}
-            />
-          ) : (
-            <Badge>{fileName}</Badge>
-          )}
-          <Button type="button" variant="secondary" onClick={clear}>
-            Remove
-          </Button>
-        </div>
-      ) : null}
+      <AttachedPreview
+        fileName={fileName}
+        isImage={isImage}
+        previewUrl={previewUrl}
+        onClear={clear}
+      />
 
       {uploadError !== undefined ? (
         <span id={uploadErrorId} role="alert" className="tai-field-error">
@@ -192,33 +161,133 @@ export function MediaField({
         </span>
       ) : null}
 
-      <label htmlFor={pasteId} className="tai-field">
-        <span className="tai-field-hint">Or paste a value</span>
-        <TextInput
-          id={pasteId}
-          type="text"
-          // Only the upload error's id: `TextInput` joins it with the enclosing
-          // Field's own description and error IDREFs rather than replacing them.
-          aria-describedby={uploadError === undefined ? undefined : uploadErrorId}
-          aria-invalid={uploadError === undefined ? undefined : true}
-          value={value}
-          onChange={(event) => {
-            const next = event.target.value;
-            // The same effective cap the picker enforces, measured on the pasted
-            // string's DECODED byte size. Reject over-cap LOUDLY; never accept or
-            // truncate — the field keeps its prior value.
-            const size = decodedByteSize(next);
-            if (size > maxBytes) {
-              setUploadError(overCapMessage('The pasted value', size, maxBytes));
-              return;
-            }
-            setUploadError(undefined);
-            setAttached(undefined);
-            onChange(next);
+      <MediaPasteInput
+        pasteId={pasteId}
+        value={value}
+        maxBytes={maxBytes}
+        uploadErrorId={uploadError === undefined ? undefined : uploadErrorId}
+        onReject={setUploadError}
+        onAccept={(next) => {
+          setUploadError(undefined);
+          setAttached(undefined);
+          onChange(next);
+        }}
+      />
+    </Field>
+  );
+}
+
+/** The just-picked file, retained only while it still matches the current field value. */
+interface AttachedMedia {
+  name: string;
+  previewUrl: string;
+  value: string;
+}
+
+/**
+ * The display derived from the attached file and the current value: the chip/preview
+ * applies ONLY while the attachment still matches the value (an external reset or a
+ * different record loading falls back to a value-derived display so a stale
+ * filename/thumbnail can never linger); an existing data-url value reconstructs its
+ * own preview.
+ */
+function mediaPreview(
+  attached: AttachedMedia | undefined,
+  value: string,
+  media: MediaUpload,
+): { previewUrl: string | undefined; isImage: boolean; fileName: string | undefined } {
+  const activeAttached = attached?.value === value ? attached : undefined;
+  const previewUrl =
+    activeAttached?.previewUrl ??
+    (media.encoding === 'data-url' && value.startsWith('data:') ? value : undefined);
+  const isImage =
+    media.mediaType?.startsWith('image/') === true || previewUrl?.startsWith('data:image') === true;
+  const fileName = activeAttached?.name ?? (value !== '' ? 'Attached file' : undefined);
+  return { previewUrl, isImage, fileName };
+}
+
+/** The attached-file chip: an image thumbnail when previewable, else a filename badge, plus Remove. */
+function AttachedPreview({
+  fileName,
+  isImage,
+  previewUrl,
+  onClear,
+}: {
+  fileName: string | undefined;
+  isImage: boolean;
+  previewUrl: string | undefined;
+  onClear: () => void;
+}): ReactNode {
+  if (fileName === undefined) return null;
+  return (
+    <div className="tai-row">
+      {isImage && previewUrl !== undefined ? (
+        <img
+          src={previewUrl}
+          alt={fileName}
+          // A thumbnail is per-instance geometry: it is capped to a fixed height and
+          // can never exceed the width it is given.
+          style={{
+            maxWidth: '100%',
+            maxHeight: '6rem',
+            borderRadius: 'var(--tai-radius-md)',
+            border: '1px solid var(--tai-color-control-border)',
           }}
         />
-      </label>
-    </Field>
+      ) : (
+        <Badge>{fileName}</Badge>
+      )}
+      <Button type="button" variant="secondary" onClick={onClear}>
+        Remove
+      </Button>
+    </div>
+  );
+}
+
+/**
+ * The paste fallback: a text input that enforces the SAME effective byte cap the
+ * picker does, measured on the pasted string's DECODED size. An over-cap paste is
+ * rejected LOUDLY (`onReject`) and the field keeps its prior value; an accepted paste
+ * clears any attachment and emits the new value (`onAccept`).
+ */
+function MediaPasteInput({
+  pasteId,
+  value,
+  maxBytes,
+  uploadErrorId,
+  onReject,
+  onAccept,
+}: {
+  pasteId: string;
+  value: string;
+  maxBytes: number;
+  /** Set while an upload error stands, so the input points at it and reads invalid. */
+  uploadErrorId: string | undefined;
+  onReject: (message: string) => void;
+  onAccept: (value: string) => void;
+}): ReactNode {
+  return (
+    <label htmlFor={pasteId} className="tai-field">
+      <span className="tai-field-hint">Or paste a value</span>
+      <TextInput
+        id={pasteId}
+        type="text"
+        // Only the upload error's id: `TextInput` joins it with the enclosing Field's
+        // own description and error IDREFs rather than replacing them.
+        aria-describedby={uploadErrorId}
+        aria-invalid={uploadErrorId === undefined ? undefined : true}
+        value={value}
+        onChange={(event) => {
+          const next = event.target.value;
+          const size = decodedByteSize(next);
+          if (size > maxBytes) {
+            onReject(overCapMessage('The pasted value', size, maxBytes));
+            return;
+          }
+          onAccept(next);
+        }}
+      />
+    </label>
   );
 }