@tai42/studio-sdk 16.0.0 → 17.0.0

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

@@ -9,12 +9,12 @@ import type { ReactNode } from 'react';
 import { useContext, useId, useState } from 'react';
 
 import { Badge } from '../components/badge';
+import { Field, type FieldControlProps, useFieldControl } from '../components/field';
 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 { Button } from '../components/primitives';
 import { MaxUploadBytesContext } from './context';
+import type { MediaUpload } from './field-model';
 import { decodedByteSize, effectiveMaxBytes, overCapMessage } from './media';
 
 /**
@@ -114,9 +114,7 @@ export function MediaField({
   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 [attached, setAttached] = useState<AttachedMedia | undefined>(undefined);
 
   const accept = (file: File | undefined): void => {
     if (file === undefined) return;
@@ -139,19 +137,7 @@ export function MediaField({
     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);
+  const { previewUrl, isImage, fileName } = mediaPreview(attached, value, media);
 
   return (
     <Field label={heading} description={description} error={error}>
@@ -161,29 +147,12 @@ export function MediaField({
         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}
+      <AttachedPreview
+        fileName={fileName}
+        isImage={isImage}
+        previewUrl={previewUrl}
+        onClear={clear}
+      />
 
       {uploadError !== undefined ? (
         <span id={uploadErrorId} role="alert" className="tai-field-error">
@@ -192,33 +161,133 @@ export function MediaField({
         </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);
+      <MediaPasteInput
+        pasteId={pasteId}
+        value={value}
+        maxBytes={maxBytes}
+        uploadErrorId={uploadError === undefined ? undefined : uploadErrorId}
+        onReject={setUploadError}
+        onAccept={(next) => {
+          setUploadError(undefined);
+          setAttached(undefined);
+          onChange(next);
+        }}
+      />
+    </Field>
+  );
+}
+
+/** The just-picked file, retained only while it still matches the current field value. */
+interface AttachedMedia {
+  name: string;
+  previewUrl: string;
+  value: string;
+}
+
+/**
+ * The display derived from the attached file and the current value: the chip/preview
+ * applies ONLY while the attachment still matches the value (an external reset or a
+ * different record loading falls back to a value-derived display so a stale
+ * filename/thumbnail can never linger); an existing data-url value reconstructs its
+ * own preview.
+ */
+function mediaPreview(
+  attached: AttachedMedia | undefined,
+  value: string,
+  media: MediaUpload,
+): { previewUrl: string | undefined; isImage: boolean; fileName: string | undefined } {
+  const activeAttached = attached?.value === value ? attached : undefined;
+  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 { previewUrl, isImage, fileName };
+}
+
+/** The attached-file chip: an image thumbnail when previewable, else a filename badge, plus Remove. */
+function AttachedPreview({
+  fileName,
+  isImage,
+  previewUrl,
+  onClear,
+}: {
+  fileName: string | undefined;
+  isImage: boolean;
+  previewUrl: string | undefined;
+  onClear: () => void;
+}): ReactNode {
+  if (fileName === undefined) return null;
+  return (
+    <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)',
           }}
         />
-      </label>
-    </Field>
+      ) : (
+        <Badge>{fileName}</Badge>
+      )}
+      <Button type="button" variant="secondary" onClick={onClear}>
+        Remove
+      </Button>
+    </div>
+  );
+}
+
+/**
+ * The paste fallback: a text input that enforces the SAME effective byte cap the
+ * picker does, measured on the pasted string's DECODED size. An over-cap paste is
+ * rejected LOUDLY (`onReject`) and the field keeps its prior value; an accepted paste
+ * clears any attachment and emits the new value (`onAccept`).
+ */
+function MediaPasteInput({
+  pasteId,
+  value,
+  maxBytes,
+  uploadErrorId,
+  onReject,
+  onAccept,
+}: {
+  pasteId: string;
+  value: string;
+  maxBytes: number;
+  /** Set while an upload error stands, so the input points at it and reads invalid. */
+  uploadErrorId: string | undefined;
+  onReject: (message: string) => void;
+  onAccept: (value: string) => void;
+}): ReactNode {
+  return (
+    <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={uploadErrorId}
+        aria-invalid={uploadErrorId === undefined ? undefined : true}
+        value={value}
+        onChange={(event) => {
+          const next = event.target.value;
+          const size = decodedByteSize(next);
+          if (size > maxBytes) {
+            onReject(overCapMessage('The pasted value', size, maxBytes));
+            return;
+          }
+          onAccept(next);
+        }}
+      />
+    </label>
   );
 }
 

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

@@ -10,11 +10,11 @@
  * silently merged): the map cannot represent two entries under one key, so the
  * later duplicate is withheld and flagged rather than overwriting the first.
  */
-import { useContext, useRef, useState } from 'react';
 import type { ReactNode } from 'react';
+import { useContext, useRef, useState } from 'react';
 
-import { CloseIcon } from '../components/icons';
 import { Field } from '../components/field';
+import { CloseIcon } from '../components/icons';
 import { TextInput } from '../components/inputs';
 import { Button } from '../components/primitives';
 import { classifySchema } from './classify';

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

@@ -24,11 +24,11 @@ import { Suspense, useCallback, useContext, useMemo, useState } from 'react';
 import { CompletionInput } from '../components/completion-input';
 import { Field } from '../components/field';
 import { AlertTriangleIcon } from '../components/icons';
-import { TextInput, Textarea } from '../components/inputs';
+import { Textarea, TextInput } from '../components/inputs';
 import { errorMessage } from '../errors';
-import type { ExpressionAnnotation, MediaUpload } from './classify';
 import type { ExpressionFieldComponent, ExpressionInputShape } from './context';
 import { CompletionProviderContext, ExpressionFieldContext } from './context';
+import type { ExpressionAnnotation, MediaUpload } from './field-model';
 import { MediaField } from './media-field';
 import type { CompletionProvider } from './SchemaForm';
 

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

@@ -11,15 +11,16 @@ 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 { skeletonValueForSchema } from './default-value';
 import { FieldGroup } from './field-group';
+import type { FieldModel, UnionVariant } from './field-model';
 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';
+import { activeVariantIndex } from './union';
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);

package/src/schema-form/union.ts

@@ -5,8 +5,8 @@
  * when Pydantic emitted no discriminator). Returns `-1` when no variant is
  * active (an unset/`null` value, or nothing matches).
  */
+import type { UnionVariant } from './field-model';
 import { resolveRef } from './resolve';
-import type { UnionVariant } from './classify';
 import type { JsonSchema } from './types';
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {