@tai42/studio-sdk 16.0.0 → 17.0.0

package/src/schema-form/context.ts

@@ -4,8 +4,8 @@
  * renderer, and the expression-field door. A field deep in the tree reads these
  * here rather than every intermediate node drilling the prop.
  */
-import { createContext } from 'react';
 import type { ComponentType, ReactNode } from 'react';
+import { createContext } from 'react';
 
 import { DEFAULT_MAX_UPLOAD_BYTES } from './media';
 import type { CompletionProvider } from './SchemaForm';

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-group.tsx

@@ -4,8 +4,8 @@
  * heading, an optional description, an optional error — the ERROR mark beside
  * the message, never a hue on its own — and the nested group surface.
  */
-import { useId } from 'react';
 import type { ReactNode } from 'react';
+import { useId } from 'react';
 
 import { XCircleIcon } from '../components/icons';
 import { groupClass, groupHeaderClass, stackClass } from './styles';

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

@@ -18,8 +18,8 @@ import { ObjectFields } from './object-fields';
 import { RecordField } from './record-field';
 import { scalarLabel } from './resolve';
 import { StringField } from './string-field';
-import { UnionField } from './union-field';
 import type { JsonSchema, SchemaFormErrors } from './types';
+import { UnionField } from './union-field';
 
 interface FieldNodeProps {
   readonly schema: JsonSchema;
@@ -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/index.ts

@@ -29,20 +29,20 @@
  * completion provider, the injected expression door — would be different objects
  * from the ones the host provides.
  */
-export { SchemaForm } from './SchemaForm';
-export type { SchemaFormProps, CompletionProvider } from './SchemaForm';
-export { RecordEntryRendererContext } from './context';
-export type { RecordEntryRenderer, RecordEntryContext } from './context';
-export { ExpressionFieldContext } from './context';
+export type { RecordEntryContext, RecordEntryRenderer } from './context';
 export type {
   ExpressionFieldComponent,
   ExpressionFieldProps,
-  ExpressionInputShape,
   ExpressionInputKey,
+  ExpressionInputShape,
 } from './context';
-export { SecretRefField } from './SecretRefField';
-export type { SecretRefFieldProps, SecretRef } from './SecretRefField';
+export { RecordEntryRendererContext } from './context';
+export { ExpressionFieldContext } from './context';
 export { defaultValueForSchema } from './default-value';
-export { validateAgainstSchema } from './validate';
 export { resolveRef } from './resolve';
-export type { JsonSchema, JsonSchemaType, Discriminator, SchemaFormErrors } from './types';
+export type { CompletionProvider, SchemaFormProps } from './SchemaForm';
+export { SchemaForm } from './SchemaForm';
+export type { SecretRef, SecretRefFieldProps } from './SecretRefField';
+export { SecretRefField } from './SecretRefField';
+export type { Discriminator, JsonSchema, JsonSchemaType, SchemaFormErrors } from './types';
+export { validateAgainstSchema } from './validate';

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

@@ -17,8 +17,8 @@
  * `lastEmitted` guard `record-field` uses, so a parent echoing our own commit back
  * does not clobber what is being typed.
  */
-import { useRef, useState } from 'react';
 import type { ReactNode } from 'react';
+import { useRef, useState } from 'react';
 
 import { Field } from '../components/field';
 import { Textarea } from '../components/inputs';