@tai42/studio-sdk 15.0.0 → 16.0.1

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

@@ -0,0 +1,111 @@
+/**
+ * Detect the annotations that opt a (ref-resolved) string schema out of the plain
+ * text box: the media-upload annotations (`contentEncoding`/`contentMediaType`/
+ * `format: "data-url"`) and the `x-tai42-expression` expression-editor annotation.
+ * Both degrade to `undefined` on anything malformed, so an annotated field never
+ * renders differently from the plain string it falls back to.
+ */
+import { isRecord } from '../guards';
+import type { ExpressionAnnotation, ExpressionAnnotationKey, MediaUpload } from './field-model';
+import type { JsonSchema } from './types';
+
+const EXPRESSION_KEYWORD = 'x-tai42-expression';
+
+/**
+ * Detect the media-upload annotations on a (ref-resolved) string schema. A field
+ * opts into the upload control when it carries `contentEncoding: "base64"` plus a
+ * `contentMediaType`, OR `format: "data-url"`. Anything else is a plain string.
+ */
+export function mediaUpload(schema: JsonSchema): MediaUpload | undefined {
+  const mediaType =
+    typeof schema.contentMediaType === 'string' ? schema.contentMediaType : undefined;
+  const maxBytes =
+    typeof schema.contentMaxBytes === 'number' && schema.contentMaxBytes > 0
+      ? schema.contentMaxBytes
+      : undefined;
+  if (schema.format === 'data-url') {
+    return { encoding: 'data-url', mediaType, maxBytes };
+  }
+  if (schema.contentEncoding === 'base64' && mediaType !== undefined) {
+    return { encoding: 'base64', mediaType, maxBytes };
+  }
+  return undefined;
+}
+
+/** An optional string member: absent is fine, a non-string is a malformed annotation. */
+type StringOrInvalid =
+  { readonly ok: true; readonly value: string | undefined } | { readonly ok: false };
+
+function optionalString(value: unknown): StringOrInvalid {
+  if (value === undefined) return { ok: true, value: undefined };
+  if (typeof value === 'string') return { ok: true, value };
+  return { ok: false };
+}
+
+/** Parse the optional `keys` array: absent → `undefined`, malformed → `null` (reject). */
+function parseAnnotationKeys(
+  value: unknown,
+): readonly ExpressionAnnotationKey[] | undefined | null {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value)) return null;
+  const keys: ExpressionAnnotationKey[] = [];
+  for (const entry of value as readonly unknown[]) {
+    if (!isRecord(entry) || typeof entry.name !== 'string' || typeof entry.gloss !== 'string') {
+      return null;
+    }
+    keys.push({ name: entry.name, gloss: entry.gloss });
+  }
+  return keys;
+}
+
+/** Parse the optional `caveats` array: absent → `undefined`, malformed → `null` (reject). */
+function parseCaveatList(value: unknown): readonly string[] | undefined | null {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value)) return null;
+  const caveats: string[] = [];
+  for (const entry of value as readonly unknown[]) {
+    if (typeof entry !== 'string') return null;
+    caveats.push(entry);
+  }
+  return caveats;
+}
+
+/**
+ * Detect the `x-tai42-expression` annotation on a (ref-resolved) string schema,
+ * mirroring {@link mediaUpload}: a well-formed annotation opts the field into the
+ * jq expression editor; anything else — absent, non-object, unknown language, or
+ * any wrongly-typed member — yields `undefined`, so the field renders EXACTLY as
+ * the plain string input it is today. Malformed payloads NEVER throw: a bad
+ * annotation is a server-side authoring bug, and degrading to the ordinary text
+ * box keeps the form usable while staying byte-identical to the unannotated
+ * rendering.
+ */
+export function expressionAnnotation(schema: JsonSchema): ExpressionAnnotation | undefined {
+  const raw: unknown = schema[EXPRESSION_KEYWORD];
+  if (!isRecord(raw)) return undefined;
+  // The language gate doubles as the forward-compatibility valve: a future
+  // language this client does not understand degrades to a plain string field.
+  if (raw.language !== 'jq') return undefined;
+
+  const label = optionalString(raw.label);
+  const blurb = optionalString(raw.blurb);
+  const returns = optionalString(raw.returns);
+  if (!label.ok || !blurb.ok || !returns.ok) return undefined;
+
+  const keys = parseAnnotationKeys(raw.keys);
+  if (keys === null) return undefined;
+  const caveats = parseCaveatList(raw.caveats);
+  if (caveats === null) return undefined;
+
+  // `sample` is any JSON — including `null` — so presence is tracked, not typed.
+  return {
+    language: 'jq',
+    label: label.value,
+    blurb: blurb.value,
+    keys,
+    returns: returns.value,
+    caveats,
+    hasSample: 'sample' in raw,
+    sample: raw.sample,
+  };
+}

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

@@ -26,7 +26,7 @@ import { Field } from '../components/field';
 import { AlertTriangleIcon } from '../components/icons';
 import { TextInput, Textarea } from '../components/inputs';
 import { errorMessage } from '../errors';
-import type { ExpressionAnnotation, MediaUpload } from './classify';
+import type { ExpressionAnnotation, MediaUpload } from './field-model';
 import type { ExpressionFieldComponent, ExpressionInputShape } from './context';
 import { CompletionProviderContext, ExpressionFieldContext } from './context';
 import { MediaField } from './media-field';

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

@@ -11,7 +11,8 @@ import type { ReactNode } from 'react';
 
 import { Field } from '../components/field';
 import { Select } from '../components/select';
-import { classifySchema, type FieldModel, type UnionVariant } from './classify';
+import { classifySchema } from './classify';
+import type { FieldModel, UnionVariant } from './field-model';
 import { skeletonValueForSchema } from './default-value';
 import { FieldGroup } from './field-group';
 import { FieldNode } from './field-node';

package/src/schema-form/union.ts

@@ -6,7 +6,7 @@
  * active (an unset/`null` value, or nothing matches).
  */
 import { resolveRef } from './resolve';
-import type { UnionVariant } from './classify';
+import type { UnionVariant } from './field-model';
 import type { JsonSchema } from './types';
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {

package/src/schema-form/validate.ts

@@ -6,6 +6,8 @@
  * malformed value — a malformed value IS the error it reports.
  */
 import { classifySchema } from './classify';
+import type { FieldModel } from './field-model';
+import { isRecord } from '../guards';
 import { decodedByteSize, effectiveMaxBytes, overCapMessage } from './media';
 import { scalarLabel } from './resolve';
 import { activeVariantIndex } from './union';
@@ -21,14 +23,20 @@ export interface ValidateOptions {
   readonly maxUploadBytes?: number;
 }
 
+/** The invariants every per-node validator shares while walking one value tree. */
+interface ValidateCtx {
+  /** The document root, for `$ref` resolution during re-classification. */
+  readonly root: JsonSchema;
+  /** The path-keyed error bag every validator writes into. */
+  readonly errors: Record<string, string>;
+  /** The host's default media byte cap (a field's own cap still overrides it). */
+  readonly maxUploadBytes: number | undefined;
+}
+
 const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 function joinPath(path: string, key: string): string {
   return path === '' ? key : `${path}.${key}`;
 }
@@ -58,127 +66,200 @@ function formatError(format: string, value: string): string | undefined {
   }
 }
 
-function walk(
-  schema: JsonSchema,
+type ModelOf<K extends FieldModel['kind']> = Extract<FieldModel, { kind: K }>;
+
+// A free-form JSON field: any JSON is accepted, subject only to the container the
+// schema commits to (mirrors the renderer's inline check).
+function validateJson(
+  model: ModelOf<'json'>,
+  value: unknown,
+  path: string,
+  ctx: ValidateCtx,
+): void {
+  if (model.jsonType === 'object' && !isRecord(value)) {
+    ctx.errors[path] = 'must be a JSON object';
+  } else if (model.jsonType === 'array' && !Array.isArray(value)) {
+    ctx.errors[path] = 'must be a JSON array';
+  }
+}
+
+function validateConst(
+  model: ModelOf<'const'>,
+  value: unknown,
+  path: string,
+  ctx: ValidateCtx,
+): void {
+  if (value !== model.value) ctx.errors[path] = `must equal ${scalarLabel(model.value)}`;
+}
+
+function validateEnum(
+  model: ModelOf<'enum'>,
+  value: unknown,
+  path: string,
+  ctx: ValidateCtx,
+): void {
+  const allowed = model.options.some((option) => option.value === value);
+  if (!allowed) ctx.errors[path] = 'must be one of the allowed values';
+}
+
+function validateString(
+  model: ModelOf<'string'>,
+  value: unknown,
+  path: string,
+  ctx: ValidateCtx,
+): void {
+  if (typeof value !== 'string') {
+    ctx.errors[path] = 'must be a string';
+    return;
+  }
+  // A media-annotated string carries a byte cap; enforce it on the value's
+  // DECODED size so a value that arrived by any route is caught here too. The
+  // precedence matches the renderer: field `contentMaxBytes` → host cap →
+  // shared default.
+  if (model.media !== undefined) {
+    const cap = effectiveMaxBytes(model.media.maxBytes, ctx.maxUploadBytes);
+    const size = decodedByteSize(value);
+    if (size > cap) {
+      ctx.errors[path] = overCapMessage('The value', size, cap);
+      return;
+    }
+  }
+  if (value.length > 0 && model.format !== undefined) {
+    const message = formatError(model.format, value);
+    if (message !== undefined) ctx.errors[path] = message;
+  }
+}
+
+function validateNumber(
+  model: ModelOf<'number'>,
   value: unknown,
   path: string,
-  root: JsonSchema,
-  errors: Record<string, string>,
-  maxUploadBytes: number | undefined,
+  ctx: ValidateCtx,
 ): void {
-  const classified = classifySchema(schema, root);
+  if (typeof value !== 'number' || Number.isNaN(value)) {
+    ctx.errors[path] = model.integer ? 'must be an integer' : 'must be a number';
+    return;
+  }
+  if (model.integer && !Number.isInteger(value)) ctx.errors[path] = 'must be an integer';
+}
+
+function validateBoolean(value: unknown, path: string, ctx: ValidateCtx): void {
+  if (typeof value !== 'boolean') ctx.errors[path] = 'must be true or false';
+}
+
+function validateArray(
+  model: ModelOf<'array'>,
+  value: unknown,
+  path: string,
+  ctx: ValidateCtx,
+): void {
+  if (!Array.isArray(value)) {
+    ctx.errors[path] = 'must be an array';
+    return;
+  }
+  value.forEach((item, index) => {
+    walk(model.items, item, `${path}[${String(index)}]`, ctx);
+  });
+}
+
+function validateObject(
+  model: ModelOf<'object'>,
+  value: unknown,
+  path: string,
+  ctx: ValidateCtx,
+): void {
+  if (!isRecord(value)) {
+    ctx.errors[path] = 'must be an object';
+    return;
+  }
+  const propMap = new Map(model.properties);
+  for (const [name, propSchema] of model.properties) {
+    const childPath = joinPath(path, name);
+    const childValue = value[name];
+    if (childValue === undefined) {
+      if (model.required.has(name)) ctx.errors[childPath] = `"${name}" is required`;
+      continue;
+    }
+    walk(propSchema, childValue, childPath, ctx);
+  }
+  // Required keys naming a property that somehow isn't declared still count.
+  for (const name of model.required) {
+    if (!propMap.has(name) && value[name] === undefined) {
+      ctx.errors[joinPath(path, name)] = `"${name}" is required`;
+    }
+  }
+}
+
+function validateRecord(
+  model: ModelOf<'record'>,
+  value: unknown,
+  path: string,
+  ctx: ValidateCtx,
+): void {
+  if (!isRecord(value)) {
+    ctx.errors[path] = 'must be an object';
+    return;
+  }
+  for (const [key, entryValue] of Object.entries(value)) {
+    walk(model.values, entryValue, joinPath(path, key), ctx);
+  }
+}
+
+function validateUnion(
+  model: ModelOf<'union'>,
+  value: unknown,
+  path: string,
+  ctx: ValidateCtx,
+): void {
+  const index = activeVariantIndex(value, model.variants, model.discriminator, ctx.root);
+  const variant = index === -1 ? undefined : model.variants[index];
+  if (variant === undefined) {
+    ctx.errors[path] = 'does not match any allowed variant';
+    return;
+  }
+  walk(variant.schema, value, path, ctx);
+}
+
+function walk(schema: JsonSchema, value: unknown, path: string, ctx: ValidateCtx): void {
+  const classified = classifySchema(schema, ctx.root);
 
   if (value === null) {
-    if (!classified.nullable) errors[path] = 'must not be null';
+    if (!classified.nullable) ctx.errors[path] = 'must not be null';
     return;
   }
 
   const { model } = classified;
   switch (model.kind) {
     case 'json':
-      // A free-form JSON field: any JSON is accepted, subject only to the
-      // container the schema commits to (mirrors the renderer's inline check).
-      if (model.jsonType === 'object' && !isPlainObject(value)) {
-        errors[path] = 'must be a JSON object';
-      } else if (model.jsonType === 'array' && !Array.isArray(value)) {
-        errors[path] = 'must be a JSON array';
-      }
+      validateJson(model, value, path, ctx);
       return;
     case 'const':
-      if (value !== model.value) errors[path] = `must equal ${scalarLabel(model.value)}`;
+      validateConst(model, value, path, ctx);
       return;
-    case 'enum': {
-      const allowed = model.options.some((option) => option.value === value);
-      if (!allowed) errors[path] = 'must be one of the allowed values';
+    case 'enum':
+      validateEnum(model, value, path, ctx);
       return;
-    }
-    case 'string': {
-      if (typeof value !== 'string') {
-        errors[path] = 'must be a string';
-        return;
-      }
-      // A media-annotated string carries a byte cap; enforce it on the value's
-      // DECODED size so a value that arrived by any route is caught here too. The
-      // precedence matches the renderer: field `contentMaxBytes` → host cap →
-      // shared default.
-      if (model.media !== undefined) {
-        const cap = effectiveMaxBytes(model.media.maxBytes, maxUploadBytes);
-        const size = decodedByteSize(value);
-        if (size > cap) {
-          errors[path] = overCapMessage('The value', size, cap);
-          return;
-        }
-      }
-      if (value.length > 0 && model.format !== undefined) {
-        const message = formatError(model.format, value);
-        if (message !== undefined) errors[path] = message;
-      }
+    case 'string':
+      validateString(model, value, path, ctx);
       return;
-    }
-    case 'number': {
-      if (typeof value !== 'number' || Number.isNaN(value)) {
-        errors[path] = model.integer ? 'must be an integer' : 'must be a number';
-        return;
-      }
-      if (model.integer && !Number.isInteger(value)) errors[path] = 'must be an integer';
+    case 'number':
+      validateNumber(model, value, path, ctx);
       return;
-    }
     case 'boolean':
-      if (typeof value !== 'boolean') errors[path] = 'must be true or false';
+      validateBoolean(value, path, ctx);
       return;
-    case 'array': {
-      if (!Array.isArray(value)) {
-        errors[path] = 'must be an array';
-        return;
-      }
-      value.forEach((item, index) => {
-        walk(model.items, item, `${path}[${String(index)}]`, root, errors, maxUploadBytes);
-      });
+    case 'array':
+      validateArray(model, value, path, ctx);
       return;
-    }
-    case 'object': {
-      if (!isPlainObject(value)) {
-        errors[path] = 'must be an object';
-        return;
-      }
-      const propMap = new Map(model.properties);
-      for (const [name, propSchema] of model.properties) {
-        const childPath = joinPath(path, name);
-        const childValue = value[name];
-        if (childValue === undefined) {
-          if (model.required.has(name)) errors[childPath] = `"${name}" is required`;
-          continue;
-        }
-        walk(propSchema, childValue, childPath, root, errors, maxUploadBytes);
-      }
-      // Required keys naming a property that somehow isn't declared still count.
-      for (const name of model.required) {
-        if (!propMap.has(name) && value[name] === undefined) {
-          errors[joinPath(path, name)] = `"${name}" is required`;
-        }
-      }
+    case 'object':
+      validateObject(model, value, path, ctx);
       return;
-    }
-    case 'record': {
-      if (!isPlainObject(value)) {
-        errors[path] = 'must be an object';
-        return;
-      }
-      for (const [key, entryValue] of Object.entries(value)) {
-        walk(model.values, entryValue, joinPath(path, key), root, errors, maxUploadBytes);
-      }
+    case 'record':
+      validateRecord(model, value, path, ctx);
       return;
-    }
-    case 'union': {
-      const index = activeVariantIndex(value, model.variants, model.discriminator, root);
-      const variant = index === -1 ? undefined : model.variants[index];
-      if (variant === undefined) {
-        errors[path] = 'does not match any allowed variant';
-        return;
-      }
-      walk(variant.schema, value, path, root, errors, maxUploadBytes);
+    case 'union':
+      validateUnion(model, value, path, ctx);
       return;
-    }
   }
 }
 
@@ -194,6 +275,6 @@ export function validateAgainstSchema(
   options?: ValidateOptions,
 ): SchemaFormErrors {
   const errors: Record<string, string> = {};
-  walk(schema, value, '', schema, errors, options?.maxUploadBytes);
+  walk(schema, value, '', { root: schema, errors, maxUploadBytes: options?.maxUploadBytes });
   return errors;
 }