@tai42/studio-sdk 9.2.1 → 9.3.0

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

@@ -1,51 +1,36 @@
 /**
  * The string field renderer. A plain string renders as a text input (its
  * `type` derived from any JSON-Schema `format`); an expression-annotated schema
- * renders the jq field (a resting textarea with the visual-editor door); a
- * media-annotated schema renders the upload control instead; and when the form
- * supplies a completion provider, the input is backed by argument autocomplete.
+ * renders the INJECTED expression door (a resting textarea with the visual-editor
+ * button) when the host supplies one; a media-annotated schema renders the upload
+ * control instead; and when the form supplies a completion provider, the input is
+ * backed by argument autocomplete.
  *
- * `JqField` is reached through the SDK's own `./jq` re-export — the ONE
- * `@tai42/jq-studio` instance the whole deployment shares — never from
- * `@tai42/jq-studio` directly, which would bundle a second copy and orphan its
- * worker (see the `jq` module doc-comment).
- *
- * That door is loaded LAZILY, through a dynamic `import('../jq')` behind
- * {@link JqField}. The jq authoring door drags a heavy subgraph — the xyflow
- * visual editor, a Web Worker entry, and a wasm engine chunk — that a form
- * whose fields carry no `x-tai42-expression` annotation must never ship. A
- * static import would pin that subgraph into every consumer that bundles the
- * SDK (a host that externalises the SDK is unaffected either way); the dynamic
- * import keeps it out of `schema-form`'s static graph and pulls it only when an
- * annotated field actually mounts.
+ * NO JQ EDGE. This module — and every module under `schema-form` — names no jq
+ * type and imports the SDK's `../jq` re-export neither statically NOR dynamically.
+ * The jq authoring door drags a heavy subgraph (the xyflow visual editor, a Web
+ * Worker entry, and a multi-megabyte wasm engine), and a bundler EMITS that whole
+ * subgraph for a dynamic import just as it does for a static one — `lazy` defers
+ * the FETCH, never the emission. A consumer that bundles the SDK to render forms
+ * would still ship the chunks, the worker file, and the wasm it can never run.
+ * So the door arrives from the host instead, through
+ * {@link ExpressionFieldContext} (or the form's `expressionField` prop), and an
+ * annotated field with no injected door falls back to the plain string input.
  */
 import type { ReactNode } from 'react';
-import { Suspense, lazy, useCallback, useContext, useMemo, useState } from 'react';
+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 { errorMessage } from '../errors';
-import type { JqInputShapeDescriptor } from '../jq';
 import type { ExpressionAnnotation, MediaUpload } from './classify';
-import { CompletionProviderContext } from './context';
+import type { ExpressionFieldComponent, ExpressionInputShape } from './context';
+import { CompletionProviderContext, ExpressionFieldContext } from './context';
 import { MediaField } from './media-field';
 import type { CompletionProvider } from './SchemaForm';
 
-// The lazily-loaded jq door. Defining it at module scope (never inside a
-// component) is what keeps the lazy component's identity stable across renders,
-// so React resolves the chunk once and never re-suspends a mounted field. The
-// `import('../jq')` here is a DYNAMIC import — the sole runtime edge from
-// `schema-form` to the jq door — so the visual editor, worker, and wasm live in
-// a split chunk that a non-annotated form never requests. The `type`-only
-// import of `JqInputShapeDescriptor` above is erased at compile time and adds no
-// such edge.
-const JqField = lazy(async () => {
-  const { JqField } = await import('../jq');
-  return { default: JqField };
-});
-
 export function StringField({
   heading,
   description,
@@ -70,6 +55,7 @@ export function StringField({
   onChange: (value: unknown) => void;
 }): ReactNode {
   const completionProvider = useContext(CompletionProviderContext);
+  const expressionField = useContext(ExpressionFieldContext);
   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.
@@ -77,15 +63,20 @@ export function StringField({
     onChange(next === '' && !required ? undefined : next);
   };
 
-  // An expression-annotated field renders the jq field — the resting control plus
-  // the visual-editor door. Checked before `media` because the expression
+  // An expression-annotated field renders the injected door — the resting control
+  // plus its visual-editor button. Checked before `media` because the expression
   // annotation is the more specific, deliberate opt-in (`x-tai42-expression`);
-  // a schema carrying both is contradictory, and a jq expression is text, not an
+  // a schema carrying both is contradictory, and an expression is text, not an
   // upload. Not reachable together with the completion provider path: an
   // expression is authored, not completed from server suggestions.
-  if (expression !== undefined) {
+  //
+  // With no door injected the annotation is INERT: the field falls through to the
+  // ordinary paths below, exactly as a malformed annotation does, so a form
+  // renders the same bytes either way.
+  if (expression !== undefined && expressionField !== undefined) {
     return (
-      <JqExpressionField
+      <ExpressionField
+        component={expressionField}
         heading={heading}
         description={description}
         error={error}
@@ -198,29 +189,31 @@ function CompletionField({
 }
 
 /**
- * An expression-annotated string field, rendered as `JqField`: a multiline
- * resting control with the always-present visual-editor door. `JqField` brings
- * its own label/description/error chrome (a11y-linked slots), so it is NOT
- * wrapped in the form's `Field` component — the annotation's descriptor fields
- * map onto jq-studio's input-shape descriptor, and the form's per-field error
- * feeds the `error` prop.
+ * An expression-annotated string field, rendered through the injected door: a
+ * multiline resting control with the door's own visual-editor button. The door
+ * brings its own label/description/error chrome (a11y-linked slots), so it is NOT
+ * wrapped in the form's `Field` component — the annotation's descriptor fields map
+ * onto the input-shape descriptor, and the form's per-field error feeds `error`.
+ *
+ * The door is rendered as an ELEMENT, never called as a function, so its hooks and
+ * state (editor open, worker handle) belong to it and survive re-renders of this
+ * field.
  *
- * Deliberately unwired:
- * - `serverValidate` — no author-time validation endpoint applies to a
- *   schema-declared field (the WASM runtime still powers the Test panel locally).
- * - `onEditorOpenChange` — the hosts that render `SchemaForm` register no global
- *   keyboard shortcuts, so there is nothing to mute while the editor is open.
- * - `compact` — the form renders every sibling field with a visible label;
- *   the compact variant (visually-hidden label, icon-only door) is for dense
- *   host rows, which the schema form does not have.
+ * It mounts inside a `Suspense` boundary because a host is free to inject a `lazy`
+ * door to keep the jq subgraph in a split chunk of ITS OWN bundle. The fallback
+ * paints the resting shell — label/description/error chrome around the current
+ * value in a read-only multiline control — so the field holds its layout and keeps
+ * the value visible while that chunk resolves, and the swap does not flash. A door
+ * injected eagerly never suspends and renders straight through.
  *
- * The door is code-split ({@link JqField} is a `lazy` component), so it mounts
- * inside a `Suspense` boundary. Its fallback paints the resting shell —
- * label/description/error chrome around the current value in a read-only
- * multiline control — so the field holds its layout and keeps the value visible
- * while the chunk resolves, and the swap to the live door does not flash.
+ * The form passes only the props the field owns; a jq door's `serverValidate`,
+ * `onEditorOpenChange`, and `compact` stay unwired, because no author-time
+ * validation endpoint applies to a schema-declared field, the hosts that render
+ * `SchemaForm` register no global shortcuts to mute, and every sibling field shows
+ * a visible label (the compact variant is for dense host rows).
  */
-function JqExpressionField({
+function ExpressionField({
+  component: Door,
   heading,
   description,
   error,
@@ -229,6 +222,7 @@ function JqExpressionField({
   value,
   onChange,
 }: {
+  component: ExpressionFieldComponent;
   heading: string;
   description: string | undefined;
   error: string | undefined;
@@ -237,13 +231,13 @@ function JqExpressionField({
   value: string;
   onChange: (value: string) => void;
 }): ReactNode {
-  // Memoised: the descriptor's identity feeds jq-studio's own memoisation, so a
+  // Memoised: the descriptor's identity feeds the door's own memoisation, so a
   // fresh object each keystroke would defeat it.
   const shape = useMemo(() => expressionShape(expression, argName), [expression, argName]);
   return (
     <Suspense
       fallback={
-        <JqExpressionFieldSkeleton
+        <ExpressionFieldSkeleton
           heading={heading}
           description={description}
           error={error}
@@ -251,7 +245,7 @@ function JqExpressionField({
         />
       }
     >
-      <JqField
+      <Door
         label={heading}
         description={description}
         error={error}
@@ -265,13 +259,13 @@ function JqExpressionField({
 }
 
 /**
- * The resting shell shown while the jq door chunk loads. It mirrors the live
- * door's footprint — the same label/description/error chrome wrapping a
+ * The resting shell shown while a lazily-injected door resolves. It mirrors the
+ * live door's footprint — the same label/description/error chrome wrapping a
  * multiline control seeded with the current value — but the control is inert
  * (read-only, `aria-busy`) because there is nothing to edit yet. Matching the
  * footprint is what keeps the Suspense swap from shifting layout or flashing.
  */
-function JqExpressionFieldSkeleton({
+function ExpressionFieldSkeleton({
   heading,
   description,
   error,
@@ -290,17 +284,16 @@ function JqExpressionFieldSkeleton({
 }
 
 /**
- * Map a classified expression annotation onto jq-studio's input-shape
- * descriptor. A bare annotation (`language` only) maps to NO descriptor — the
- * undeclared-shape `JqField` is the honest rendering when the server said
- * nothing about `.`. When any descriptor field is present, the required
- * descriptor members the annotation omits fall back to neutral values rather
- * than invented copy.
+ * Map a classified expression annotation onto the door's input-shape descriptor.
+ * A bare annotation (`language` only) maps to NO descriptor — an undeclared shape
+ * is the honest rendering when the server said nothing about `.`. When any
+ * descriptor field is present, the required descriptor members the annotation
+ * omits fall back to neutral values rather than invented copy.
  */
 function expressionShape(
   expression: ExpressionAnnotation,
   argName: string,
-): JqInputShapeDescriptor | undefined {
+): ExpressionInputShape | undefined {
   const declared =
     expression.label !== undefined ||
     expression.blurb !== undefined ||