@tai42/studio-sdk 19.2.1 → 19.3.0

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

@@ -114,6 +114,7 @@ function seedValue(schema: JsonSchema, root: JsonSchema, mintScalars: boolean):
     case 'object':
       return seedObject(model, root, mintScalars);
     case 'array':
+    case 'multiselect':
       return [];
     case 'record':
       return {};

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

@@ -11,7 +11,9 @@ import { RadioGroup } from '../components/radio-group';
 import { Select } from '../components/select';
 import type { FieldModel } from './field-model';
 
-const RADIO_MAX_OPTIONS = 3;
+// The documented radio-vs-select threshold, shared across channels: a choice of this many
+// options or fewer draws as a radio group, a longer one as a select.
+const RADIO_MAX_OPTIONS = 5;
 
 export function EnumField({
   heading,

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

@@ -28,6 +28,24 @@ export interface MediaUpload {
   readonly maxBytes: number | undefined;
 }
 
+/**
+ * The platform date constraints classified off a `date`/`date-time` string property
+ * (scope C). `min`/`max` are inclusive `YYYY-MM-DD` bounds (passed to the native date
+ * control and enforced by the validator); `unavailable` is the set of excluded days
+ * (the native control cannot disable arbitrary days, so this is validator-enforced).
+ * A date RANGE is two ordinary date fields: on the END field, `rangeStart` names its
+ * start field and `minDays`/`maxDays` bound the inclusive span. Absent members leave
+ * that aspect unconstrained.
+ */
+export interface DateConstraints {
+  readonly min: string | undefined;
+  readonly max: string | undefined;
+  readonly unavailable: readonly string[];
+  readonly rangeStart: string | undefined;
+  readonly minDays: number | undefined;
+  readonly maxDays: number | undefined;
+}
+
 /** One top-level key of the expression's input document, with a one-line gloss. */
 export interface ExpressionAnnotationKey {
   readonly name: string;
@@ -106,10 +124,21 @@ export type FieldModel =
       /** Present when a well-formed `x-tai42-expression` annotation opts the
        *  field into the jq expression editor (see {@link ExpressionAnnotation}). */
       readonly expression: ExpressionAnnotation | undefined;
+      /** Present on a `date`/`date-time` string carrying any platform date
+       *  constraint (bounds, unavailable days, or range pairing — scope C). */
+      readonly date: DateConstraints | undefined;
     }
   | { readonly kind: 'number'; readonly integer: boolean }
   | { readonly kind: 'boolean' }
   | { readonly kind: 'array'; readonly items: JsonSchema }
+  | {
+      // An array of a FIXED set of strings (its `items` carry an `enum`, or a per-send
+      // option list set one): a multi-select control (a checkbox group), one checkbox per
+      // option, value a `string[]`. An array of free strings stays the add/remove
+      // `array` field — a multi-select needs a known option set to draw.
+      readonly kind: 'multiselect';
+      readonly options: readonly EnumOption[];
+    }
   | {
       readonly kind: 'object';
       readonly properties: readonly (readonly [string, JsonSchema])[];

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

@@ -13,7 +13,9 @@ import { ArrayField } from './array-field';
 import { classifySchema } from './classify';
 import { EnumField } from './enum-field';
 import { FieldGroup } from './field-group';
+import type { FieldModel } from './field-model';
 import { JsonField } from './json-field';
+import { MultiSelectField } from './multiselect-field';
 import { ObjectFields } from './object-fields';
 import { RecordField } from './record-field';
 import { scalarLabel } from './resolve';
@@ -58,8 +60,41 @@ function FieldNodeImpl(props: FieldNodeProps): ReactNode {
   const base = labelText(classified.title, props.label);
   const heading = props.markRequired === true && required ? `${base} *` : base;
   const { model, description } = classified;
-  const error = errors?.[path];
+  return renderField({
+    model,
+    nullable: classified.nullable,
+    heading,
+    description,
+    error: errors?.[path],
+    root,
+    value,
+    onChange,
+    path,
+    required,
+    errors,
+    idPrefix,
+  });
+}
+
+/** The props the per-kind renderer needs, computed once by {@link FieldNodeImpl}. */
+interface RenderFieldArgs {
+  readonly model: FieldModel;
+  readonly nullable: boolean;
+  readonly heading: string;
+  readonly description: string | undefined;
+  readonly error: string | undefined;
+  readonly root: JsonSchema;
+  readonly value: unknown;
+  readonly onChange: (value: unknown) => void;
+  readonly path: string;
+  readonly required: boolean;
+  readonly errors: SchemaFormErrors | undefined;
+  readonly idPrefix: string;
+}
 
+/** Render the field component matching the classified model kind. */
+function renderField(args: RenderFieldArgs): ReactNode {
+  const { model, nullable, heading, description, error, value, onChange, path, required } = args;
   switch (model.kind) {
     case 'json':
       return (
@@ -68,7 +103,7 @@ function FieldNodeImpl(props: FieldNodeProps): ReactNode {
           description={description}
           error={error}
           jsonType={model.jsonType}
-          nullable={classified.nullable}
+          nullable={nullable}
           value={value}
           onChange={onChange}
         />
@@ -102,6 +137,7 @@ function FieldNodeImpl(props: FieldNodeProps): ReactNode {
           format={model.format}
           media={model.media}
           expression={model.expression}
+          date={model.date}
           argName={path}
           value={value}
           required={required}
@@ -129,6 +165,29 @@ function FieldNodeImpl(props: FieldNodeProps): ReactNode {
           onChange={onChange}
         />
       );
+    case 'multiselect':
+      return (
+        <MultiSelectField
+          heading={heading}
+          description={description}
+          error={error}
+          model={model}
+          value={value}
+          onChange={onChange}
+        />
+      );
+    default:
+      return renderCompositeField(args, model);
+  }
+}
+
+/** The composite (recursing) field kinds: array, object, record, and union. */
+function renderCompositeField(
+  args: RenderFieldArgs,
+  model: Extract<FieldModel, { kind: 'array' | 'object' | 'record' | 'union' }>,
+): ReactNode {
+  const { heading, description, error, root, value, onChange, path, errors, idPrefix } = args;
+  switch (model.kind) {
     case 'array':
       return (
         <ArrayField

package/src/schema-form/index.ts

@@ -46,3 +46,4 @@ export type { SecretRef, SecretRefFieldProps } from './SecretRefField';
 export { SecretRefField } from './SecretRefField';
 export type { Discriminator, JsonSchema, JsonSchemaType, SchemaFormErrors } from './types';
 export { validateAgainstSchema } from './validate';
+export { isFieldVisible } from './visibility';

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

@@ -0,0 +1,58 @@
+/**
+ * The multi-select field renderer (scope E): an array of a fixed set of strings drawn
+ * as a checkbox group, one checkbox per option, emitting a `string[]`. Classification
+ * lands an array here only when its items carry a known option set (an `enum`, or a
+ * per-send option list), so there is always a definite set of boxes to draw; an array of
+ * free strings stays the add/remove `array` field.
+ */
+import type { ReactNode } from 'react';
+
+import { Checkbox } from '../components/checkbox';
+import { Field } from '../components/field';
+import type { FieldModel } from './field-model';
+
+export function MultiSelectField({
+  heading,
+  description,
+  error,
+  model,
+  value,
+  onChange,
+}: {
+  heading: string;
+  description: string | undefined;
+  error: string | undefined;
+  model: Extract<FieldModel, { kind: 'multiselect' }>;
+  value: unknown;
+  onChange: (value: unknown) => void;
+}): ReactNode {
+  const selected = Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === 'string')
+    : [];
+  // Toggle keeps the selection in the OPTIONS' declared order, so the emitted array reads
+  // the way the form lists the choices rather than the order the boxes were clicked.
+  const toggle = (optionValue: string, checked: boolean): void => {
+    const next = checked ? [...selected, optionValue] : selected.filter((v) => v !== optionValue);
+    const ordered = model.options
+      .map((option) => String(option.value))
+      .filter((candidate) => next.includes(candidate));
+    onChange(ordered);
+  };
+  return (
+    <Field label={heading} description={description} error={error} group>
+      {model.options.map((option, index) => {
+        const optionValue = String(option.value);
+        return (
+          <Checkbox
+            key={index}
+            label={option.label}
+            checked={selected.includes(optionValue)}
+            onCheckedChange={(checked) => {
+              toggle(optionValue, checked);
+            }}
+          />
+        );
+      })}
+    </Field>
+  );
+}

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

@@ -9,6 +9,7 @@ import type { ReactNode } from 'react';
 import { FieldNode } from './field-node';
 import { useKeyedCallbacks } from './keyed-callbacks';
 import type { JsonSchema, SchemaFormErrors } from './types';
+import { isFieldVisible } from './visibility';
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -49,6 +50,9 @@ export function ObjectFields({
     <>
       {properties.map(([name, propSchema]) => {
         if (skip !== undefined && name === skip) return null;
+        // A field hidden by its `visibleWhen` predicate (scope B) is not rendered; the
+        // validator skips it in step, so a hidden field is neither shown nor required.
+        if (!isFieldVisible(propSchema, obj)) return null;
         const childPath = path === '' ? name : `${path}.${name}`;
         return (
           <FieldNode

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

@@ -28,7 +28,7 @@ import { Textarea, TextInput } from '../components/inputs';
 import { errorMessage } from '../errors';
 import type { ExpressionFieldComponent, ExpressionInputShape } from './context';
 import { CompletionProviderContext, ExpressionFieldContext } from './context';
-import type { ExpressionAnnotation, MediaUpload } from './field-model';
+import type { DateConstraints, ExpressionAnnotation, MediaUpload } from './field-model';
 import { MediaField } from './media-field';
 import type { CompletionProvider } from './SchemaForm';
 
@@ -39,6 +39,7 @@ export function StringField({
   format,
   media,
   expression,
+  date,
   argName,
   value,
   required,
@@ -50,6 +51,7 @@ export function StringField({
   format: string | undefined;
   media: MediaUpload | undefined;
   expression: ExpressionAnnotation | undefined;
+  date: DateConstraints | undefined;
   argName: string;
   value: unknown;
   required: boolean;
@@ -115,6 +117,11 @@ export function StringField({
       ) : (
         <TextInput
           type={stringInputType(format)}
+          // A native date control enforces its inclusive bounds (scope C); on a
+          // non-date input the browser ignores these, and the validator enforces the
+          // rest (unavailable days, range span) that the control cannot draw.
+          min={date?.min}
+          max={date?.max}
           value={current}
           onChange={(event) => {
             emit(event.target.value);

package/src/schema-form/types.ts

@@ -60,9 +60,48 @@ export interface JsonSchema {
   readonly maxLength?: number;
   readonly minItems?: number;
   readonly maxItems?: number;
+  readonly pattern?: string;
+  /**
+   * Platform date-constraint keys on a `string`/`date` (or `date-time`) property. They
+   * are NOT the JSON-Schema numeric keywords (which are inert on a string): `minDate`/
+   * `maxDate` are inclusive `YYYY-MM-DD` bounds, `unavailableDates` is a list of
+   * `YYYY-MM-DD` days to exclude. A date RANGE is TWO ordinary date fields: the END field
+   * names its start field with `rangeStart` and carries the inclusive span in
+   * `minDays`/`maxDays`; nothing is recombined. All optional; absent = an unconstrained
+   * date. The native control enforces what it can (min/max) and the validator enforces the
+   * rest, mirroring the server.
+   */
+  readonly minDate?: string;
+  readonly maxDate?: string;
+  readonly unavailableDates?: readonly string[];
+  readonly rangeStart?: string;
+  readonly minDays?: number;
+  readonly maxDays?: number;
+  /**
+   * A declarative visibility predicate on a property: the field shows only when the
+   * predicate holds against the current form values. Static form description evaluated by
+   * the renderer (never a consumer reaction); a hidden field is not rendered and not
+   * validated. Absent = always visible. See {@link VisibleWhen}.
+   */
+  readonly visibleWhen?: VisibleWhen;
   readonly [key: string]: unknown;
 }
 
+/**
+ * A field-visibility predicate ({@link JsonSchema.visibleWhen}): the field is visible
+ * only when the referenced sibling `field` satisfies exactly one operator — `equals` a
+ * value, `in` a list of values, or `notEmpty` (a non-blank scalar / a non-empty array).
+ * A malformed predicate (none or several operators) degrades to VISIBLE: the send-time
+ * server validation rejects a malformed predicate loudly, so one never reaches a well-
+ * formed render, and showing a field is the safe non-hiding default.
+ */
+export interface VisibleWhen {
+  readonly field: string;
+  readonly equals?: unknown;
+  readonly in?: readonly unknown[];
+  readonly notEmpty?: boolean;
+}
+
 /**
  * A structured, per-path bag of validation problems. Keys are dotted/bracketed
  * paths from the form root (`""` = the root value, `"user.name"`, `"tags[0]"`);

package/src/schema-form/validate.ts

@@ -7,11 +7,12 @@
  */
 import { isRecord } from '../guards';
 import { classifySchema } from './classify';
-import type { FieldModel } from './field-model';
+import type { DateConstraints, FieldModel } from './field-model';
 import { decodedByteSize, effectiveMaxBytes, overCapMessage } from './media';
-import { scalarLabel } from './resolve';
+import { resolveRef, scalarLabel } from './resolve';
 import type { JsonSchema, SchemaFormErrors } from './types';
 import { activeVariantIndex } from './union';
+import { isFieldVisible } from './visibility';
 
 /** Options for {@link validateAgainstSchema}. */
 export interface ValidateOptions {
@@ -126,10 +127,31 @@ function validateString(
   }
   if (value.length > 0 && model.format !== undefined) {
     const message = formatError(model.format, value);
+    if (message !== undefined) {
+      ctx.errors[path] = message;
+      return;
+    }
+  }
+  // Date bounds and unavailable days (scope C). Range span/ordering needs the sibling
+  // start field, so it is enforced at the object level (see validateDateRanges).
+  if (model.date !== undefined && value.length > 0) {
+    const message = dateConstraintError(model.date, value);
     if (message !== undefined) ctx.errors[path] = message;
   }
 }
 
+/** The inclusive bound/unavailable-day violation on a date value, or `undefined`. */
+function dateConstraintError(date: DateConstraints, value: string): string | undefined {
+  // `YYYY-MM-DD` strings compare lexicographically in chronological order, so the bounds
+  // are plain string comparisons. A value that is not a well-formed date is left to the
+  // `format` check above; this runs only for a syntactically valid date.
+  if (!DATE_RE.test(value)) return undefined;
+  if (date.min !== undefined && value < date.min) return `must be on or after ${date.min}`;
+  if (date.max !== undefined && value > date.max) return `must be on or before ${date.max}`;
+  if (date.unavailable.includes(value)) return 'is not an available date';
+  return undefined;
+}
+
 function validateNumber(
   model: ModelOf<'number'>,
   value: unknown,
@@ -174,6 +196,11 @@ function validateObject(
   }
   const propMap = new Map(model.properties);
   for (const [name, propSchema] of model.properties) {
+    // A field hidden by its `visibleWhen` predicate (scope B) is not part of the answer:
+    // it is not required and not validated, and a value left on it is dropped by the
+    // server, not an error here. Evaluated on the current values, so a field that was
+    // hidden by the predicate is skipped even if it still carries a stale value.
+    if (!isFieldVisible(propSchema, value)) continue;
     const childPath = joinPath(path, name);
     const childValue = value[name];
     if (childValue === undefined) {
@@ -188,6 +215,143 @@ function validateObject(
       ctx.errors[joinPath(path, name)] = `"${name}" is required`;
     }
   }
+  validateDateRanges(model, value, path, ctx);
+}
+
+/** Days from `start` to `end` inclusive (both `YYYY-MM-DD`); 1 when they are equal. */
+function inclusiveDayCount(start: string, end: string): number {
+  return Math.round((Date.parse(end) - Date.parse(start)) / 86_400_000) + 1;
+}
+
+/**
+ * Enforce a date RANGE declared on an END field (scope C): the end is on or after its
+ * named `rangeStart` field, and the inclusive day span is within `minDays`/`maxDays`.
+ * Read from the two plain date values — nothing recombined. A missing or not-yet-valid
+ * endpoint is left to that field's own validation; a hidden end field is skipped.
+ */
+function validateDateRanges(
+  model: ModelOf<'object'>,
+  value: Record<string, unknown>,
+  path: string,
+  ctx: ValidateCtx,
+): void {
+  for (const [name, propSchema] of model.properties) {
+    if (!isFieldVisible(propSchema, value)) continue;
+    const resolved = resolveRef(propSchema, ctx.root);
+    if (typeof resolved.rangeStart !== 'string') continue;
+    const endValue = value[name];
+    const startValue = value[resolved.rangeStart];
+    if (typeof endValue !== 'string' || typeof startValue !== 'string') continue;
+    if (!DATE_RE.test(endValue) || !DATE_RE.test(startValue)) continue;
+    const childPath = joinPath(path, name);
+    if (ctx.errors[childPath] !== undefined) continue;
+    const message = dateRangeMessage(resolved, startValue, endValue);
+    if (message !== undefined) ctx.errors[childPath] = message;
+  }
+}
+
+/** The ordering/span violation on a range END field, or `undefined` when it holds. */
+function dateRangeMessage(
+  resolved: JsonSchema,
+  startValue: string,
+  endValue: string,
+): string | undefined {
+  if (endValue < startValue) return 'must be on or after the start date';
+  const days = inclusiveDayCount(startValue, endValue);
+  const minDays = typeof resolved.minDays === 'number' ? resolved.minDays : undefined;
+  const maxDays = typeof resolved.maxDays === 'number' ? resolved.maxDays : undefined;
+  if (minDays !== undefined && days < minDays)
+    return `must span at least ${String(minDays)} day(s)`;
+  if (maxDays !== undefined && days > maxDays) return `must span at most ${String(maxDays)} day(s)`;
+  return undefined;
+}
+
+function validateMultiselect(
+  model: ModelOf<'multiselect'>,
+  value: unknown,
+  path: string,
+  ctx: ValidateCtx,
+): void {
+  if (!Array.isArray(value)) {
+    ctx.errors[path] = 'must be an array';
+    return;
+  }
+  const allowed = new Set(model.options.map((option) => option.value));
+  for (const item of value) {
+    if (!allowed.has(item)) {
+      ctx.errors[path] = 'must be one of the allowed values';
+      return;
+    }
+  }
+}
+
+/**
+ * The JSON-Schema value/length/items bounds the client mirrors from the server (bug 4):
+ * `minLength`/`maxLength`/`pattern` on a string, `minimum`/`maximum` on a number,
+ * `minItems`/`maxItems` on an array. Applied only when the kind check found no type
+ * error. A `pattern` that cannot compile surfaces as a loud field error, never a silent
+ * skip — the server validates every send's schema, so a well-formed form never hits it.
+ */
+function applyBounds(schema: JsonSchema, value: unknown, path: string, ctx: ValidateCtx): void {
+  if (typeof value === 'string') applyStringBounds(schema, value, path, ctx);
+  else if (typeof value === 'number') applyNumberBounds(schema, value, path, ctx);
+  else if (Array.isArray(value)) applyArrayBounds(schema, value, path, ctx);
+}
+
+function applyStringBounds(
+  schema: JsonSchema,
+  value: string,
+  path: string,
+  ctx: ValidateCtx,
+): void {
+  const length = Array.from(value).length;
+  if (typeof schema.minLength === 'number' && length < schema.minLength) {
+    ctx.errors[path] = `must be at least ${String(schema.minLength)} character(s)`;
+    return;
+  }
+  if (typeof schema.maxLength === 'number' && length > schema.maxLength) {
+    ctx.errors[path] = `must be at most ${String(schema.maxLength)} character(s)`;
+    return;
+  }
+  if (typeof schema.pattern !== 'string' || schema.pattern === '') return;
+  let pattern: RegExp;
+  try {
+    pattern = new RegExp(schema.pattern);
+  } catch {
+    ctx.errors[path] = 'has an invalid pattern constraint';
+    return;
+  }
+  if (!pattern.test(value)) ctx.errors[path] = 'must match the required pattern';
+}
+
+function applyNumberBounds(
+  schema: JsonSchema,
+  value: number,
+  path: string,
+  ctx: ValidateCtx,
+): void {
+  if (typeof schema.minimum === 'number' && value < schema.minimum) {
+    ctx.errors[path] = `must be at least ${String(schema.minimum)}`;
+    return;
+  }
+  if (typeof schema.maximum === 'number' && value > schema.maximum) {
+    ctx.errors[path] = `must be at most ${String(schema.maximum)}`;
+  }
+}
+
+function applyArrayBounds(
+  schema: JsonSchema,
+  value: readonly unknown[],
+  path: string,
+  ctx: ValidateCtx,
+): void {
+  if (typeof schema.minItems === 'number' && value.length < schema.minItems) {
+    ctx.errors[path] = `must have at least ${String(schema.minItems)} item(s)`;
+    return;
+  }
+  if (typeof schema.maxItems === 'number' && value.length > schema.maxItems) {
+    ctx.errors[path] = `must have at most ${String(schema.maxItems)} item(s)`;
+  }
 }
 
 function validateRecord(
@@ -228,7 +392,13 @@ function walk(schema: JsonSchema, value: unknown, path: string, ctx: ValidateCtx
     return;
   }
 
-  const { model } = classified;
+  dispatchKind(classified.model, value, path, ctx);
+  // The value/length/items bounds (bug 4) mirror the server and apply only when the kind
+  // check found no type error for this field — a bound on a wrong-typed value is noise.
+  if (ctx.errors[path] === undefined) applyBounds(classified.schema, value, path, ctx);
+}
+
+function dispatchKind(model: FieldModel, value: unknown, path: string, ctx: ValidateCtx): void {
   switch (model.kind) {
     case 'json':
       validateJson(model, value, path, ctx);
@@ -251,6 +421,9 @@ function walk(schema: JsonSchema, value: unknown, path: string, ctx: ValidateCtx
     case 'array':
       validateArray(model, value, path, ctx);
       return;
+    case 'multiselect':
+      validateMultiselect(model, value, path, ctx);
+      return;
     case 'object':
       validateObject(model, value, path, ctx);
       return;

package/src/schema-form/visibility.ts

@@ -0,0 +1,47 @@
+/**
+ * The single evaluator for a property's `visibleWhen` predicate — a static,
+ * declarative field-visibility rule (scope B). The renderer (`ObjectFields`) and the
+ * validator both call it so a field shown by the form is exactly the field validated at
+ * submit, and a hidden field is neither rendered nor required. It reads only sibling
+ * values already in the object; it never calls a consumer handler (that is scope A).
+ *
+ * A malformed predicate degrades to VISIBLE: the send-time server validation rejects a
+ * malformed predicate loudly, so one never reaches a well-formed render, and showing a
+ * field is the safe non-hiding default (a hidden-by-accident required field would dead-
+ * end a form).
+ */
+import type { JsonSchema } from './types';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** A value is "empty" for a `notEmpty` test: absent/null, a blank string, an empty array. */
+function isEmptyValue(value: unknown): boolean {
+  if (value === undefined || value === null) return true;
+  if (typeof value === 'string') return value.trim() === '';
+  if (Array.isArray(value)) return value.length === 0;
+  return false;
+}
+
+/**
+ * Whether a property carrying `schema.visibleWhen` is visible against the current
+ * `values` of its enclosing object. Absent predicate ⇒ always visible. Exactly one of
+ * `equals`/`in`/`notEmpty` must be present; otherwise the predicate is malformed and the
+ * field stays visible.
+ */
+export function isFieldVisible(schema: JsonSchema, values: Record<string, unknown>): boolean {
+  const predicate: unknown = schema.visibleWhen;
+  if (!isRecord(predicate) || typeof predicate.field !== 'string') return true;
+  const current = values[predicate.field];
+
+  const inList = predicate.in;
+  const hasEquals = 'equals' in predicate;
+  const hasIn = Array.isArray(inList);
+  const hasNotEmpty = predicate.notEmpty === true;
+  if (Number(hasEquals) + Number(hasIn) + Number(hasNotEmpty) !== 1) return true;
+
+  if (hasEquals) return current === predicate.equals;
+  if (hasIn) return (inList as readonly unknown[]).some((candidate) => candidate === current);
+  return !isEmptyValue(current);
+}