@tai42/studio-sdk 0.2.0

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

@@ -0,0 +1,65 @@
+/**
+ * The enum field renderer. A short enum (up to {@link RADIO_MAX_OPTIONS}
+ * options) renders as a radio group; a longer one renders as a select. Options
+ * are keyed by index so a non-string enum value round-trips through the string
+ * control.
+ */
+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';
+
+const RADIO_MAX_OPTIONS = 3;
+
+export function EnumField({
+  heading,
+  description,
+  error,
+  model,
+  value,
+  onChange,
+}: {
+  heading: string;
+  description: string | undefined;
+  error: string | undefined;
+  model: Extract<FieldModel, { kind: 'enum' }>;
+  value: unknown;
+  onChange: (value: unknown) => void;
+}): ReactNode {
+  const options = model.options.map((option, index) => ({
+    key: String(index),
+    label: option.label,
+    value: option.value,
+  }));
+  const selected = options.find((option) => option.value === value);
+  // Always a defined string so the control stays controlled from first render
+  // (an `undefined` → string transition warns about uncontrolled→controlled).
+  const selectedKey = selected?.key ?? '';
+  const emit = (key: string): void => {
+    const match = options.find((option) => option.key === key);
+    if (match !== undefined) onChange(match.value);
+  };
+
+  if (options.length <= RADIO_MAX_OPTIONS) {
+    return (
+      <Field label={heading} description={description} error={error} group>
+        <RadioGroup
+          options={options.map((option) => ({ value: option.key, label: option.label }))}
+          value={selectedKey}
+          onValueChange={emit}
+        />
+      </Field>
+    );
+  }
+  return (
+    <Field label={heading} description={description} error={error}>
+      <Select
+        options={options.map((option) => ({ value: option.key, label: option.label }))}
+        value={selectedKey}
+        onValueChange={emit}
+      />
+    </Field>
+  );
+}

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

@@ -0,0 +1,71 @@
+/**
+ * The wrapper around a nested group of fields (object, array, or union). At the
+ * form root it lays children out in a plain stack; below the root it renders a
+ * 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 { XCircleIcon } from '../components/icons';
+import { groupClass, groupHeaderClass, stackClass } from './styles';
+
+export function FieldGroup({
+  heading,
+  description,
+  error,
+  atRoot,
+  children,
+}: {
+  heading: string;
+  description: string | undefined;
+  error: string | undefined;
+  atRoot: boolean;
+  children: ReactNode;
+}): ReactNode {
+  const baseId = useId();
+  const headingId = `${baseId}-heading`;
+  const descriptionId = `${baseId}-desc`;
+  const errorId = `${baseId}-err`;
+
+  if (atRoot) {
+    return <div className={stackClass}>{children}</div>;
+  }
+
+  // The group container carries the ROLE, the name and the description. Without
+  // them the heading was a `<span>` — not a heading either — and the description
+  // and the validation error were orphaned text: entering a nested object in a
+  // schema form announced the controls with no indication of which group they
+  // belonged to. It is the same "named by construction" shape `Field group`
+  // uses, for the same reason.
+  const describedByIds: string[] = [];
+  if (description !== undefined) describedByIds.push(descriptionId);
+  if (error !== undefined) describedByIds.push(errorId);
+
+  return (
+    <div className={groupHeaderClass}>
+      <span id={headingId} className="tai-field-label">
+        {heading}
+      </span>
+      {description !== undefined ? (
+        <span id={descriptionId} className="tai-field-hint">
+          {description}
+        </span>
+      ) : null}
+      {error !== undefined ? (
+        <span id={errorId} role="alert" className="tai-field-error">
+          <XCircleIcon />
+          {error}
+        </span>
+      ) : null}
+      <div
+        role="group"
+        aria-labelledby={headingId}
+        aria-describedby={describedByIds.length > 0 ? describedByIds.join(' ') : undefined}
+        className={groupClass}
+      >
+        {children}
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,161 @@
+/**
+ * The recursive dispatcher: classifies a single schema node and renders the
+ * matching field component for its model kind (const/number/boolean render
+ * inline; every other kind delegates to a dedicated field component). Object,
+ * array, and union renderers recurse back through here for their children.
+ */
+import type { ReactNode } from 'react';
+
+import { Checkbox } from '../components/checkbox';
+import { Field } from '../components/field';
+import { NumberInput, TextInput } from '../components/inputs';
+import { ArrayField } from './array-field';
+import { classifySchema } from './classify';
+import { EnumField } from './enum-field';
+import { FieldGroup } from './field-group';
+import { ObjectFields } from './object-fields';
+import { scalarLabel } from './resolve';
+import { StringField } from './string-field';
+import { UnionField } from './union-field';
+import { UnsupportedNotice } from './unsupported-notice';
+import type { JsonSchema, SchemaFormErrors } from './types';
+
+interface FieldNodeProps {
+  readonly schema: JsonSchema;
+  readonly root: JsonSchema;
+  readonly value: unknown;
+  readonly onChange: (value: unknown) => void;
+  readonly path: string;
+  /** The label to show — a property key, array-item caption, or `undefined` at root. */
+  readonly label: string | undefined;
+  readonly required: boolean;
+  readonly errors: SchemaFormErrors | undefined;
+  readonly idPrefix: string;
+}
+
+function labelText(explicit: string | undefined, label: string | undefined): string {
+  return explicit ?? label ?? 'Value';
+}
+
+/** A single schema node, dispatched on its classified model kind. */
+export function FieldNode(props: FieldNodeProps): ReactNode {
+  const { schema, root, value, onChange, path, label, required, errors, idPrefix } = props;
+  const classified = classifySchema(schema, root);
+  const heading = labelText(classified.title, label);
+  const description = classified.description;
+  const error = errors?.[path];
+  const model = classified.model;
+
+  switch (model.kind) {
+    case 'unsupported':
+      return (
+        <UnsupportedNotice
+          heading={heading}
+          reason={model.reason}
+          description={description}
+          error={error}
+        />
+      );
+    case 'const':
+      return (
+        <Field label={heading} description={description} error={error}>
+          <TextInput value={scalarLabel(model.value)} readOnly disabled />
+        </Field>
+      );
+    case 'enum':
+      return (
+        <EnumField
+          heading={heading}
+          description={description}
+          error={error}
+          model={model}
+          value={value}
+          onChange={onChange}
+        />
+      );
+    case 'string':
+      return (
+        <StringField
+          heading={heading}
+          description={description}
+          error={error}
+          format={model.format}
+          media={model.media}
+          argName={path}
+          value={value}
+          required={required}
+          onChange={onChange}
+        />
+      );
+    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>
+      );
+    case 'boolean':
+      return (
+        <Field label={heading} description={description} error={error}>
+          <Checkbox
+            checked={value === true}
+            onCheckedChange={(checked) => {
+              onChange(checked);
+            }}
+          />
+        </Field>
+      );
+    case 'array':
+      return (
+        <ArrayField
+          heading={heading}
+          description={description}
+          error={error}
+          items={model.items}
+          root={root}
+          value={value}
+          onChange={onChange}
+          path={path}
+          errors={errors}
+          idPrefix={idPrefix}
+        />
+      );
+    case 'object':
+      return (
+        <FieldGroup heading={heading} description={description} error={error} atRoot={path === ''}>
+          <ObjectFields
+            properties={model.properties}
+            requiredKeys={model.required}
+            root={root}
+            value={value}
+            onChange={onChange}
+            path={path}
+            errors={errors}
+            idPrefix={idPrefix}
+            skip={undefined}
+          />
+        </FieldGroup>
+      );
+    case 'union':
+      return (
+        <UnionField
+          heading={heading}
+          description={description}
+          error={error}
+          model={model}
+          root={root}
+          value={value}
+          onChange={onChange}
+          path={path}
+          errors={errors}
+          idPrefix={idPrefix}
+        />
+      );
+  }
+}

package/src/schema-form/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Schema-driven forms — the load-bearing auto-form renderer, reused by
+ * the tools and interactions features. Public surface: the `SchemaForm`
+ * component plus the value/validation helpers a caller needs to seed, validate,
+ * and submit.
+ */
+export { SchemaForm } from './SchemaForm';
+export type { SchemaFormProps, CompletionProvider } from './SchemaForm';
+export { defaultValueForSchema } from './default-value';
+export { validateAgainstSchema } from './validate';
+export { resolveRef } from './resolve';
+export type { JsonSchema, JsonSchemaType, Discriminator, SchemaFormErrors } from './types';

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

@@ -0,0 +1,281 @@
+/**
+ * The media-upload string field: a drag-drop surface plus a paste fallback that
+ * reads the chosen file client-side and emits the encoded string the schema
+ * expects (a base64 body or a full `data:` URL). Every input path enforces the
+ * effective byte cap and the declared MIME, rejecting an over-cap value or a
+ * mismatched type LOUDLY — never silently truncated or accepted.
+ */
+import type { ReactNode } from 'react';
+import { useContext, useId, useState } from 'react';
+
+import { Badge } from '../components/badge';
+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 { MaxUploadBytesContext } from './context';
+import { decodedByteSize, effectiveMaxBytes, overCapMessage } from './media';
+
+/**
+ * Add the upload error this module owns to the enclosing `Field`'s wiring.
+ *
+ * The upload error is raised by the input surfaces themselves rather than by the
+ * schema, so `Field` cannot see it: without this the message was announced by
+ * nothing and neither surface reported itself invalid. Used only where the
+ * element is a bare `<input>`; the SDK's `TextInput` composes the field wiring
+ * with the caller's own attributes itself, so the paste fallback states only the
+ * error's id and lets it do the joining.
+ */
+function withUploadError(
+  field: FieldControlProps,
+  uploadErrorId: string | undefined,
+): FieldControlProps {
+  if (uploadErrorId === undefined) return field;
+  const describedBy = field['aria-describedby'];
+  return {
+    ...field,
+    'aria-describedby':
+      describedBy === undefined ? uploadErrorId : `${describedBy} ${uploadErrorId}`,
+    'aria-invalid': true,
+  };
+}
+
+/**
+ * The drag-drop surface + file input. Split out so its `useFieldControl` call
+ * runs INSIDE the enclosing {@link Field}, wiring the input's id/aria to the
+ * field label (a hook at {@link MediaField}'s top level would read the outer,
+ * label-less context instead).
+ */
+function UploadDropZone({
+  accept,
+  uploadErrorId,
+  onFile,
+}: {
+  accept: string | undefined;
+  /** Set while an upload error stands, so the input points at it and reads invalid. */
+  uploadErrorId: string | undefined;
+  onFile: (file: File | undefined) => void;
+}): ReactNode {
+  const field = withUploadError(useFieldControl(), uploadErrorId);
+  return (
+    <div
+      className="tai-card tai-stack tai-stack-2"
+      // The dashed edge is the drop target's ONLY boundary, so it takes the
+      // contrast-safe control border rather than the card's decorative one; the
+      // card class still owns the ground, the radius and the padding.
+      style={{ borderStyle: 'dashed', borderColor: 'var(--tai-color-control-border)' }}
+      onDragOver={(event) => {
+        event.preventDefault();
+      }}
+      onDrop={(event) => {
+        event.preventDefault();
+        onFile(event.dataTransfer.files[0]);
+      }}
+    >
+      <input
+        {...field}
+        type="file"
+        accept={accept}
+        onChange={(event) => {
+          onFile(event.target.files?.[0]);
+          // Reset so re-picking the same file fires `change` again.
+          event.target.value = '';
+        }}
+      />
+      <span className="tai-field-hint">Drag &amp; drop a file here, or choose one above.</span>
+    </div>
+  );
+}
+
+/**
+ * A string field whose schema opts into a file upload. Reads the chosen file
+ * client-side and emits the encoded string the schema expects (a base64 body or
+ * a full `data:` URL) — bounded by a size cap and the declared MIME, both
+ * rejected LOUDLY. A text fallback (paste a URL/base64) stays available.
+ */
+export function MediaField({
+  heading,
+  description,
+  error,
+  media,
+  value,
+  onChange,
+}: {
+  heading: string;
+  description: string | undefined;
+  error: string | undefined;
+  media: MediaUpload;
+  value: string;
+  onChange: (value: string) => void;
+}): ReactNode {
+  const pasteId = useId();
+  const uploadErrorId = useId();
+  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 accept = (file: File | undefined): void => {
+    if (file === undefined) return;
+    void readMediaFile(file, media, maxBytes).then(
+      ({ value: encoded, previewUrl }) => {
+        setUploadError(undefined);
+        setAttached({ name: file.name, previewUrl, value: encoded });
+        onChange(encoded);
+      },
+      (reason: unknown) => {
+        // Reject loudly; keep any previously accepted value untouched.
+        setUploadError(reason instanceof Error ? reason.message : String(reason));
+      },
+    );
+  };
+
+  const clear = (): void => {
+    setUploadError(undefined);
+    setAttached(undefined);
+    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);
+
+  return (
+    <Field label={heading} description={description} error={error}>
+      <UploadDropZone
+        accept={media.mediaType}
+        uploadErrorId={uploadError === undefined ? undefined : uploadErrorId}
+        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}
+
+      {uploadError !== undefined ? (
+        <span id={uploadErrorId} role="alert" className="tai-field-error">
+          <XCircleIcon />
+          {uploadError}
+        </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);
+          }}
+        />
+      </label>
+    </Field>
+  );
+}
+
+/** Compare a file's MIME against a `contentMediaType` pattern (`image/*` etc.). */
+function matchesMediaType(fileType: string, pattern: string): boolean {
+  // An empty file type is genuinely unknown (jsdom / OS gaps) — the server still
+  // validates, so we do not fabricate a mismatch here; only a KNOWN wrong type
+  // is rejected.
+  if (fileType === '') return true;
+  const [patType, patSub] = pattern.toLowerCase().split('/');
+  const [fileMain, fileSub] = fileType.toLowerCase().split('/');
+  if (patType !== fileMain) return false;
+  return patSub === '*' || patSub === fileSub;
+}
+
+/**
+ * Validate a chosen file against the media contract and read it into the encoded
+ * string the schema expects. Rejects an over-cap file or a MIME that does not
+ * match `contentMediaType` — never truncates, never silently accepts.
+ */
+async function readMediaFile(
+  file: File,
+  media: MediaUpload,
+  maxBytes: number,
+): Promise<{ value: string; previewUrl: string }> {
+  if (file.size > maxBytes) {
+    throw new Error(overCapMessage(`"${file.name}"`, file.size, maxBytes));
+  }
+  if (media.mediaType !== undefined && !matchesMediaType(file.type, media.mediaType)) {
+    throw new Error(
+      `"${file.name}" is ${file.type === '' ? 'an unknown type' : file.type}, which does not match the required ${media.mediaType}.`,
+    );
+  }
+  const dataUrl = await readAsDataUrl(file);
+  const comma = dataUrl.indexOf(',');
+  if (comma < 0) {
+    throw new Error(`Could not read "${file.name}" as an encoded value.`);
+  }
+  const body = dataUrl.slice(comma + 1);
+  return { value: media.encoding === 'data-url' ? dataUrl : body, previewUrl: dataUrl };
+}
+
+function readAsDataUrl(file: File): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => {
+      // A successful read must yield the data-url string; anything else is a real
+      // read anomaly and rejects loudly rather than emitting an empty value.
+      if (typeof reader.result === 'string') {
+        resolve(reader.result);
+      } else {
+        reject(new Error(`Failed to read "${file.name}" as a data URL.`));
+      }
+    };
+    reader.onerror = () => {
+      reject(reader.error ?? new Error(`Failed to read "${file.name}".`));
+    };
+    reader.readAsDataURL(file);
+  });
+}

package/src/schema-form/media.ts

@@ -0,0 +1,69 @@
+/**
+ * Shared byte-cap logic for media-upload string fields, used by EVERY path that
+ * can set a media field's value: the file picker, the "paste a value" fallback,
+ * and the pre-submit validation pass. Centralised here so the effective cap and
+ * the decoded byte size are computed IDENTICALLY on all three paths.
+ *
+ * `contentMaxBytes` is a NONSTANDARD JSON-Schema extension keyword — a standard
+ * JSON-Schema validator ignores it. These client-side caps are UX guards that
+ * fail LOUDLY and early on the obvious over-cap input; they are NOT a security
+ * boundary. The SERVER MUST independently validate the decoded size of any
+ * uploaded content.
+ */
+
+/**
+ * Default cap for a media-upload field when neither the schema's `contentMaxBytes`
+ * nor the host's `maxUploadBytes` prop pins one. 10 MiB comfortably fits a typical
+ * image or PDF while still rejecting a runaway upload loudly.
+ */
+export const DEFAULT_MAX_UPLOAD_BYTES = 10 * 1024 * 1024;
+
+/**
+ * Resolve the effective byte cap for a media field. Precedence: the schema's
+ * per-field `contentMaxBytes` wins (the only channel by which the schema-authoring
+ * party states a per-field cap), else the host's `maxUploadBytes` default, else
+ * {@link DEFAULT_MAX_UPLOAD_BYTES}.
+ */
+export function effectiveMaxBytes(
+  fieldCap: number | undefined,
+  propCap: number | undefined,
+): number {
+  return fieldCap ?? propCap ?? DEFAULT_MAX_UPLOAD_BYTES;
+}
+
+/**
+ * The DECODED byte size of a media field's string value. The value is either a
+ * raw base64 body or a full `data:<mime>;base64,<body>` URL; the cap applies to
+ * the decoded bytes, never the character length. Computed arithmetically from the
+ * base64 length and its `=` padding, so an over-cap value is caught without
+ * allocating the decoded buffer and without throwing on a malformed input.
+ */
+export function decodedByteSize(value: string): number {
+  // A data-url carries the base64 body after the first comma; a bare base64 value
+  // is the body itself.
+  const comma = value.indexOf(',');
+  const body = value.startsWith('data:') && comma >= 0 ? value.slice(comma + 1) : value;
+  // base64 decodes 4 chars → 3 bytes; drop whitespace and subtract the trailing
+  // `=` padding the encoder added.
+  const compact = body.replace(/\s/g, '');
+  if (compact === '') return 0;
+  const padding = compact.endsWith('==') ? 2 : compact.endsWith('=') ? 1 : 0;
+  return Math.floor((compact.length * 3) / 4) - padding;
+}
+
+/** Human-readable byte size for a cap/overage message (`5 B`, `1.5 KB`, `2.0 MB`). */
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${String(bytes)} B`;
+  const kb = bytes / 1024;
+  if (kb < 1024) return `${kb.toFixed(1)} KB`;
+  return `${(kb / 1024).toFixed(1)} MB`;
+}
+
+/**
+ * The loud, user-visible over-cap message, identical across the picker, the paste
+ * fallback, and validation. `subject` names the rejected input (e.g. a quoted
+ * filename, or `"The pasted value"`).
+ */
+export function overCapMessage(subject: string, actualBytes: number, maxBytes: number): string {
+  return `${subject} is ${formatBytes(actualBytes)}, over the ${formatBytes(maxBytes)} limit.`;
+}