@tai42/studio-sdk 0.2.0

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

@@ -0,0 +1,74 @@
+/**
+ * Renders the property fields of an object schema, one {@link FieldNode} per
+ * property. Each child's edits are folded back into an immutable copy of the
+ * object value; an optional `skip` omits a property (used for a union's
+ * discriminator tag, which the variant picker owns).
+ */
+import type { ReactNode } from 'react';
+
+import { FieldNode } from './field-node';
+import type { JsonSchema, SchemaFormErrors } from './types';
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function ObjectFields({
+  properties,
+  requiredKeys,
+  root,
+  value,
+  onChange,
+  path,
+  errors,
+  idPrefix,
+  skip,
+}: {
+  properties: readonly (readonly [string, JsonSchema])[];
+  requiredKeys: ReadonlySet<string>;
+  root: JsonSchema;
+  value: unknown;
+  onChange: (value: unknown) => void;
+  path: string;
+  errors: SchemaFormErrors | undefined;
+  idPrefix: string;
+  skip: string | undefined;
+}): ReactNode {
+  const obj = isPlainObject(value) ? value : {};
+  return (
+    <>
+      {properties.map(([name, propSchema]) => {
+        if (skip !== undefined && name === skip) return null;
+        const childPath = path === '' ? name : `${path}.${name}`;
+        return (
+          <FieldNode
+            key={name}
+            schema={propSchema}
+            root={root}
+            value={obj[name]}
+            onChange={(next) => {
+              onChange(setKey(obj, name, next));
+            }}
+            path={childPath}
+            label={name}
+            required={requiredKeys.has(name)}
+            errors={errors}
+            idPrefix={idPrefix}
+          />
+        );
+      })}
+    </>
+  );
+}
+
+function setKey(
+  obj: Record<string, unknown>,
+  name: string,
+  next: unknown,
+): Record<string, unknown> {
+  if (next === undefined) {
+    const { [name]: _removed, ...rest } = obj;
+    return rest;
+  }
+  return { ...obj, [name]: next };
+}

package/src/schema-form/resolve.ts

@@ -0,0 +1,114 @@
+/**
+ * Pure helpers over the JSON-Schema subset: `$ref`/`$defs` resolution and the
+ * small predicates the renderer, defaulting, and validation all share. Kept
+ * side-effect-free so they can be unit-tested and reused across the module.
+ */
+import type { JsonSchema, JsonSchemaType } from './types';
+
+/** Un-escape one JSON-Pointer reference token (`~1`→`/`, `~0`→`~`). */
+function unescapePointerToken(token: string): string {
+  return token.replace(/~1/g, '/').replace(/~0/g, '~');
+}
+
+/**
+ * Resolve an internal `$ref` against the document root, following chained refs
+ * (a `$ref` whose target is itself a `$ref`). Only same-document pointers are
+ * supported (`#/$defs/Name`, `#/definitions/Name`, `#`); an external or
+ * unresolvable ref throws LOUDLY rather than yielding a silent empty schema.
+ * A schema with no `$ref` is returned unchanged. A pointer cycle throws.
+ */
+export function resolveRef(schema: JsonSchema, root: JsonSchema): JsonSchema {
+  let current = schema;
+  const seen = new Set<string>();
+  while (typeof current.$ref === 'string') {
+    const ref = current.$ref;
+    if (seen.has(ref)) {
+      throw new Error(`SchemaForm: circular $ref chain at "${ref}"`);
+    }
+    seen.add(ref);
+    if (!ref.startsWith('#')) {
+      throw new Error(`SchemaForm: only same-document $ref is supported, got "${ref}"`);
+    }
+    const segments = ref.split('/').slice(1).map(unescapePointerToken);
+    let node: unknown = root;
+    for (const segment of segments) {
+      if (node === null || typeof node !== 'object') {
+        throw new Error(`SchemaForm: unresolvable $ref "${ref}"`);
+      }
+      node = (node as Record<string, unknown>)[segment];
+    }
+    if (node === null || typeof node !== 'object') {
+      throw new Error(`SchemaForm: unresolvable $ref "${ref}"`);
+    }
+    current = node as JsonSchema;
+  }
+  return current;
+}
+
+/** Does this schema describe the JSON `null` type (and nothing else)? */
+export function isNullSchema(schema: JsonSchema): boolean {
+  return schema.type === 'null';
+}
+
+/** The list of type tokens a schema declares, normalized to an array. */
+export function typeList(schema: JsonSchema): readonly JsonSchemaType[] {
+  const type = schema.type;
+  if (type === undefined) return [];
+  if (typeof type === 'string') return [type];
+  return type;
+}
+
+/**
+ * The union member list from a schema, if it is a union. Pydantic emits
+ * discriminated unions under `oneOf` and plain/null unions under `anyOf`; both
+ * are treated as a union here. `allOf` is NOT a union (it is an intersection)
+ * and is not returned.
+ */
+export function unionMembers(schema: JsonSchema): readonly JsonSchema[] | undefined {
+  if (schema.anyOf !== undefined) return schema.anyOf;
+  if (schema.oneOf !== undefined) return schema.oneOf;
+  return undefined;
+}
+
+/** An option row derived from an `enum` or a discriminated variant tag. */
+export interface EnumOption {
+  readonly value: unknown;
+  readonly label: string;
+}
+
+/** Render-facing label for an arbitrary JSON scalar used as an enum/const value. */
+export function scalarLabel(value: unknown): string {
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  if (value === null) return 'null';
+  return JSON.stringify(value);
+}
+
+/**
+ * The single tag value a discriminated-union variant pins on the discriminator
+ * property (Pydantic emits it as `const`, or a single-entry `enum`), or
+ * `undefined` if the variant does not constrain that property to one value.
+ */
+export function variantTag(variant: JsonSchema, propertyName: string, root: JsonSchema): unknown {
+  const resolved = resolveRef(variant, root);
+  const prop = resolved.properties?.[propertyName];
+  if (prop === undefined) return undefined;
+  const propSchema = resolveRef(prop, root);
+  if ('const' in propSchema) return propSchema.const;
+  const enumValues = propSchema.enum;
+  if (enumValues?.length === 1) return enumValues[0];
+  return undefined;
+}
+
+/** A human label for a union variant: its title, its tag, or a positional fallback. */
+export function variantLabel(
+  variant: JsonSchema,
+  index: number,
+  discriminatorTag: unknown,
+  root: JsonSchema,
+): string {
+  if (discriminatorTag !== undefined) return scalarLabel(discriminatorTag);
+  const resolved = resolveRef(variant, root);
+  if (typeof resolved.title === 'string' && resolved.title.length > 0) return resolved.title;
+  return `Option ${String(index + 1)}`;
+}

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

@@ -0,0 +1,161 @@
+/**
+ * The string field renderer. A plain string renders as a text input (its
+ * `type` derived from any JSON-Schema `format`); a media-annotated schema
+ * renders the upload control instead; and when the form supplies a completion
+ * provider, the input is backed by argument autocomplete.
+ */
+import type { ReactNode } 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 { TextInput } from '../components/inputs';
+import { errorMessage } from '../errors';
+import type { MediaUpload } from './classify';
+import { CompletionProviderContext } from './context';
+import { MediaField } from './media-field';
+import type { CompletionProvider } from './SchemaForm';
+
+export function StringField({
+  heading,
+  description,
+  error,
+  format,
+  media,
+  argName,
+  value,
+  required,
+  onChange,
+}: {
+  heading: string;
+  description: string | undefined;
+  error: string | undefined;
+  format: string | undefined;
+  media: MediaUpload | undefined;
+  argName: string;
+  value: unknown;
+  required: boolean;
+  onChange: (value: unknown) => void;
+}): ReactNode {
+  const completionProvider = useContext(CompletionProviderContext);
+  const current = typeof value === 'string' ? value : '';
+  // An empty optional field emits `undefined` (drops the key); a required one
+  // keeps the empty string so validation can flag it.
+  const emit = (next: string): void => {
+    onChange(next === '' && !required ? undefined : next);
+  };
+
+  // A media-annotated field renders the upload control instead of a text box.
+  if (media !== undefined) {
+    return (
+      <MediaField
+        heading={heading}
+        description={description}
+        error={error}
+        media={media}
+        value={current}
+        onChange={emit}
+      />
+    );
+  }
+
+  return (
+    <Field label={heading} description={description} error={error}>
+      {completionProvider !== undefined ? (
+        <CompletionField
+          argName={argName}
+          value={current}
+          onChange={emit}
+          provider={completionProvider}
+        />
+      ) : (
+        <TextInput
+          type={stringInputType(format)}
+          value={current}
+          onChange={(event) => {
+            emit(event.target.value);
+          }}
+        />
+      )}
+    </Field>
+  );
+}
+
+/**
+ * A string field backed by argument completions. Split out so its memoised
+ * hooks stay unconditional (they cannot live behind the provider check in
+ * {@link StringField}) and so the completion `provider` is a non-optional prop.
+ */
+function CompletionField({
+  argName,
+  value,
+  onChange,
+  provider,
+}: {
+  argName: string;
+  value: string;
+  onChange: (value: string) => void;
+  provider: CompletionProvider;
+}): ReactNode {
+  // Memoised so its identity is stable across renders: CompletionInput lists
+  // `fetchCompletions` in its effect deps, so a fresh function each render would
+  // re-fetch on every keystroke in every string field.
+  const fetchCompletions = useCallback(
+    (partial: string) => provider(argName, partial),
+    [provider, argName],
+  );
+  // A completion fetch is a best-effort enhancement, not a fatal error — but it
+  // must never be swallowed. The failure goes to the human as a hint under the
+  // input AND to the console with the field's path, because the two audiences
+  // need different things: the reason the suggestions are gone, and which field
+  // and which throw produced it.
+  const [failure, setFailure] = useState<string | null>(null);
+  // Memoised for the same effect-deps reason as `fetchCompletions`.
+  const onError = useCallback(
+    (error: unknown) => {
+      console.error(`SchemaForm: completion fetch failed for field "${argName}"`, error);
+      setFailure(errorMessage(error));
+    },
+    [argName],
+  );
+
+  return (
+    <>
+      <CompletionInput
+        value={value}
+        // Every edit starts a fresh fetch, so the previous one's failure stops
+        // being true here; a new one re-reports through `onError`.
+        onChange={(next) => {
+          setFailure(null);
+          onChange(next);
+        }}
+        fetchCompletions={fetchCompletions}
+        onError={onError}
+      />
+      {/* A degradation, not a rejected value: the field still accepts what is
+          typed, only the suggestions are gone. So it wears the warning mark and
+          the hint style, never the error one. */}
+      {failure === null ? null : (
+        <p role="status" className="tai-field-hint" style={{ margin: 0 }}>
+          <AlertTriangleIcon />
+          {`Suggestions are unavailable: ${failure}`}
+        </p>
+      )}
+    </>
+  );
+}
+
+const FORMAT_INPUT_TYPES: Record<string, string> = {
+  email: 'email',
+  uri: 'url',
+  'uri-reference': 'url',
+  date: 'date',
+  'date-time': 'datetime-local',
+  time: 'time',
+};
+
+function stringInputType(format: string | undefined): string {
+  if (format === undefined) return 'text';
+  return FORMAT_INPUT_TYPES[format] ?? 'text';
+}

package/src/schema-form/styles.ts

@@ -0,0 +1,20 @@
+/**
+ * The design-system CLASS NAMES the schema-form field tree is built from. One
+ * module owns them so the form root, the group wrapper and the union editor
+ * cannot drift apart — and so no field component re-derives control geometry or
+ * color of its own: every name below is defined in `components.css`, which is
+ * the single source of truth for what they look like.
+ */
+
+/** The vertical rhythm a sibling set of fields sits in. */
+export const stackClass = 'tai-stack';
+
+/** The label + description + error block that introduces a nested group. */
+export const groupHeaderClass = 'tai-stack tai-stack-2';
+
+/**
+ * The surface a nested object / array / union renders its children on. A card
+ * makes every level of nesting a visible container on its own ground, so depth
+ * reads without any hand-drawn indent rail.
+ */
+export const groupClass = 'tai-card tai-stack tai-stack-3';

package/src/schema-form/types.ts

@@ -0,0 +1,71 @@
+/**
+ * Structural types for the JSON-Schema subset the auto-form supports. The shape
+ * is deliberately PERMISSIVE — every field is optional and an open index
+ * signature admits unknown keywords — because the schemas come from Pydantic v2
+ * and may carry constructs the renderer does not consume. Unknown keys never
+ * break typing; the renderer classifies a node and surfaces anything it cannot
+ * render as a LOUD "unsupported field" notice rather than dropping it.
+ */
+
+/** The JSON-Schema `type` keyword values Pydantic emits. */
+export type JsonSchemaType =
+  'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
+
+/** A Pydantic-style discriminated-union tag: which property selects the variant. */
+export interface Discriminator {
+  readonly propertyName: string;
+  readonly mapping?: Readonly<Record<string, string>>;
+}
+
+/**
+ * A structural JSON Schema node. All keys optional; the index signature keeps
+ * the type permissive so an unrecognized keyword is never a type error — it is a
+ * runtime classification concern the renderer handles.
+ */
+export interface JsonSchema {
+  readonly $ref?: string;
+  readonly $defs?: Readonly<Record<string, JsonSchema>>;
+  readonly definitions?: Readonly<Record<string, JsonSchema>>;
+  readonly type?: JsonSchemaType | readonly JsonSchemaType[];
+  readonly title?: string;
+  readonly description?: string;
+  readonly default?: unknown;
+  readonly const?: unknown;
+  readonly enum?: readonly unknown[];
+  readonly format?: string;
+  /**
+   * Media annotations (see the `SchemaForm` module). `contentEncoding: "base64"`
+   * together with `contentMediaType` (or `format: "data-url"`) opts a string
+   * field into the upload control; `contentMaxBytes` pins a per-field size cap.
+   *
+   * `contentMaxBytes` is a NONSTANDARD JSON-Schema extension keyword — a standard
+   * JSON-Schema validator ignores it. The client-side caps it drives (see the
+   * `media` module) are UX guards, NOT a security boundary: the SERVER MUST
+   * independently validate the decoded size of any uploaded content.
+   */
+  readonly contentEncoding?: string;
+  readonly contentMediaType?: string;
+  readonly contentMaxBytes?: number;
+  readonly properties?: Readonly<Record<string, JsonSchema>>;
+  readonly required?: readonly string[];
+  readonly items?: JsonSchema;
+  readonly anyOf?: readonly JsonSchema[];
+  readonly oneOf?: readonly JsonSchema[];
+  readonly allOf?: readonly JsonSchema[];
+  readonly discriminator?: Discriminator;
+  readonly additionalProperties?: boolean | JsonSchema;
+  readonly minimum?: number;
+  readonly maximum?: number;
+  readonly minLength?: number;
+  readonly maxLength?: number;
+  readonly minItems?: number;
+  readonly maxItems?: number;
+  readonly [key: string]: unknown;
+}
+
+/**
+ * A structured, per-path bag of validation problems. Keys are dotted/bracketed
+ * paths from the form root (`""` = the root value, `"user.name"`, `"tags[0]"`);
+ * each entry is a loud, human-readable message. Empty object = valid.
+ */
+export type SchemaFormErrors = Readonly<Record<string, string>>;

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

@@ -0,0 +1,122 @@
+/**
+ * The union field renderer: a variant picker plus the active variant's fields.
+ * An object variant renders its properties inline (skipping the discriminator
+ * tag, which the picker owns); a scalar/enum variant renders as a single nested
+ * {@link FieldNode}. Selecting a variant seeds a concrete value for it.
+ */
+import type { ReactNode } from 'react';
+
+import { Field } from '../components/field';
+import { Select } from '../components/select';
+import { classifySchema, type FieldModel } from './classify';
+import { defaultValueForSchema } from './default-value';
+import { FieldGroup } from './field-group';
+import { FieldNode } from './field-node';
+import { ObjectFields } from './object-fields';
+import { resolveRef } from './resolve';
+import { groupClass } from './styles';
+import { activeVariantIndex } from './union';
+import type { JsonSchema, SchemaFormErrors } from './types';
+
+/**
+ * A concrete seed for a chosen union variant. Object variants get their
+ * required-field skeleton; a scalar/enum variant that has no explicit default
+ * still needs a non-`undefined` value so the selection sticks (otherwise
+ * `activeVariantIndex` reads it back as "no variant" and the picker snaps empty).
+ */
+function seedVariantValue(schema: JsonSchema, root: JsonSchema): unknown {
+  const seeded = defaultValueForSchema(schema, root);
+  if (seeded !== undefined) return seeded;
+  const resolved = resolveRef(schema, root);
+  if (resolved.const !== undefined) return resolved.const;
+  if (resolved.enum !== undefined && resolved.enum.length > 0) return resolved.enum[0];
+  switch (classifySchema(schema, root).model.kind) {
+    case 'string':
+      return '';
+    case 'number':
+      return 0;
+    case 'boolean':
+      return false;
+    default:
+      return undefined;
+  }
+}
+
+export function UnionField({
+  heading,
+  description,
+  error,
+  model,
+  root,
+  value,
+  onChange,
+  path,
+  errors,
+  idPrefix,
+}: {
+  heading: string;
+  description: string | undefined;
+  error: string | undefined;
+  model: Extract<FieldModel, { kind: 'union' }>;
+  root: JsonSchema;
+  value: unknown;
+  onChange: (value: unknown) => void;
+  path: string;
+  errors: SchemaFormErrors | undefined;
+  idPrefix: string;
+}): ReactNode {
+  const index = activeVariantIndex(value, model.variants, model.discriminator, root);
+  const options = model.variants.map((variant, position) => ({
+    value: String(position),
+    label: variant.label,
+  }));
+  const selectVariant = (key: string): void => {
+    const position = Number(key);
+    const variant = model.variants[position];
+    if (variant === undefined) return;
+    onChange(seedVariantValue(variant.schema, root));
+  };
+
+  const active = index === -1 ? undefined : model.variants[index];
+  const activeClassified = active === undefined ? undefined : classifySchema(active.schema, root);
+
+  return (
+    <FieldGroup heading={heading} description={description} error={error} atRoot={false}>
+      <Field label="Variant">
+        <Select
+          options={options}
+          value={index === -1 ? '' : String(index)}
+          placeholder="Select a variant…"
+          onValueChange={selectVariant}
+        />
+      </Field>
+      {activeClassified?.model.kind === 'object' ? (
+        <div className={groupClass}>
+          <ObjectFields
+            properties={activeClassified.model.properties}
+            requiredKeys={activeClassified.model.required}
+            root={root}
+            value={value}
+            onChange={onChange}
+            path={path}
+            errors={errors}
+            idPrefix={idPrefix}
+            skip={model.discriminator}
+          />
+        </div>
+      ) : active !== undefined ? (
+        <FieldNode
+          schema={active.schema}
+          root={root}
+          value={value}
+          onChange={onChange}
+          path={path}
+          label={active.label}
+          required
+          errors={errors}
+          idPrefix={idPrefix}
+        />
+      ) : null}
+    </FieldGroup>
+  );
+}

package/src/schema-form/union.ts

@@ -0,0 +1,78 @@
+/**
+ * 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).
+ */
+import { resolveRef } from './resolve';
+import type { UnionVariant } from './classify';
+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 scalar schema accepts the runtime type of `value`. */
+function scalarSchemaAccepts(schema: JsonSchema, value: unknown): boolean {
+  if (schema.const !== undefined) return schema.const === value;
+  if (schema.enum !== undefined) return schema.enum.includes(value);
+  const types =
+    schema.type === undefined ? [] : Array.isArray(schema.type) ? schema.type : [schema.type];
+  return types.some((type) => {
+    switch (type) {
+      case 'string':
+        return typeof value === 'string';
+      case 'number':
+        return typeof value === 'number';
+      case 'integer':
+        return typeof value === 'number' && Number.isInteger(value);
+      case 'boolean':
+        return typeof value === 'boolean';
+      case 'null':
+        return value === null;
+      default:
+        return false;
+    }
+  });
+}
+
+export function activeVariantIndex(
+  value: unknown,
+  variants: readonly UnionVariant[],
+  discriminator: string | undefined,
+  root: JsonSchema,
+): number {
+  if (value === undefined || value === null) return -1;
+
+  if (discriminator !== undefined) {
+    if (!isPlainObject(value)) return -1;
+    const tag = value[discriminator];
+    const index = variants.findIndex((variant) => variant.tag === tag);
+    return index;
+  }
+
+  if (!isPlainObject(value)) {
+    // A scalar value: match the first variant whose resolved schema accepts the
+    // value's runtime type (a non-discriminated `Union[str, int]` and friends).
+    return variants.findIndex((variant) =>
+      scalarSchemaAccepts(resolveRef(variant.schema, root), value),
+    );
+  }
+
+  let bestIndex = -1;
+  let bestScore = -1;
+  variants.forEach((variant, index) => {
+    const resolved = resolveRef(variant.schema, root);
+    const required = resolved.required ?? [];
+    let score = 0;
+    for (const key of required) {
+      if (key in value) score += 1;
+    }
+    if (score > bestScore) {
+      bestScore = score;
+      bestIndex = index;
+    }
+  });
+  return bestIndex;
+}

package/src/schema-form/unsupported-notice.tsx

@@ -0,0 +1,39 @@
+/**
+ * The notice rendered for a schema node the form cannot turn into an input: a
+ * warning badge — a mark beside its label, so the meaning never rests on the
+ * tint alone — followed by the reason, shown inside a labelled field.
+ *
+ * The three parts each say ONE thing once. The `Field` prints the heading, the
+ * `Badge` prints the state, and the hint prints the REASON alone — repeating
+ * either of the first two there would name the field twice and the state twice,
+ * in a developer-log register on a surface a user reads.
+ */
+import type { ReactNode } from 'react';
+
+import { Badge } from '../components/badge';
+import { Field } from '../components/field';
+import { AlertTriangleIcon } from '../components/icons';
+
+export function UnsupportedNotice({
+  heading,
+  reason,
+  description,
+  error,
+}: {
+  heading: string;
+  reason: string;
+  description: string | undefined;
+  error: string | undefined;
+}): ReactNode {
+  return (
+    <Field label={heading} description={description} error={error} group>
+      <div role="alert" className="tai-row">
+        <Badge variant="warning">
+          <AlertTriangleIcon />
+          Unsupported
+        </Badge>
+        <span className="tai-field-hint">{reason}</span>
+      </div>
+    </Field>
+  );
+}