@jxsuite/studio 4.1.0 → 5.0.0

package/src/surfaces/schema-form.ts

@@ -0,0 +1,287 @@
+/// <reference lib="dom" />
+/**
+ * The shared schema→form engine as a mounted document.
+ *
+ * `ui/schema-form.ts` is the flow — it reads the JSON Schema, decides which control each property
+ * gets, resolves enum choices through the host's context, works out which rungs of the value ladder
+ * the position permits, validates a committed value and turns every gesture into a single-key patch
+ * — and this is the surface it draws into. Nothing here knows what a schema is: the scope is a list
+ * of already-decided rows.
+ *
+ * **The host element belongs to this module, not to the caller.** Every caller is still a lit
+ * template that interpolates the form into a pane of its own (Project Settings' editor column, the
+ * Entry editor's field list, the Signals panel's config block), so there is no container in the
+ * host to mount into. The surface therefore carries its own: one `<div>` per controller, mounted
+ * once and handed to lit as a child value. lit inserts a Node it is given rather than cloning it,
+ * and re-inserting the same node is a no-op, so the document survives every repaint of the pane
+ * around it — which is the whole point here, because these are fields a reader is typing into and a
+ * repaint that rebuilt them would take the caret with it.
+ *
+ * The host is `display: contents` for the reason `surfaces/ai-credentials-form.ts` gives: the panes
+ * lay their children out themselves, and a wrapper box would become the flex or grid item in the
+ * form's place.
+ *
+ * **Control hosts are announced, never queried.** A property a registered control owns is drawn as
+ * an empty `[part="control-host"]`, and the runtime reports it through `onNodeCreated` as it is
+ * created — so the flow holds the element rather than re-finding it by selector on every repaint,
+ * and a host that the reconciler replaces announces its replacement.
+ *
+ * @docs extending/ui-kit
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import schemaFormDoc from "./schema-form.json";
+import type { SurfaceHandle } from "../ui/surface";
+import type { JxScope } from "@jxsuite/runtime/types";
+import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+
+registerSurface("schema-form", schemaFormDoc as unknown as JxDocument);
+
+/** Which of the nine controls a row draws. The flow picks it; the document switches on it. */
+export type SchemaFormFieldKind =
+  | "text"
+  | "template"
+  | "pointer"
+  | "select"
+  | "checkbox"
+  | "number"
+  | "json"
+  | "rows"
+  | "control";
+
+/** A control a row offers as a closed list, in the shape the kit's select reads. */
+export interface SchemaFormOption {
+  value: string;
+  label: string;
+}
+
+/** One cell of an array-of-objects row: a single declared property of one item. */
+export interface SchemaFormCellView {
+  /** `${field}/${row}/${key}` — the cell's reconcile identity, and a control host's id. */
+  id: string;
+  /** The owning field's key, carried on the cell because a nested `$map` shadows `$map.item`. */
+  field: string;
+  /** The owning row's key, carried for the same reason. */
+  row: string;
+  /** The item property this cell edits. */
+  key: string;
+  label: string;
+  kind: "text" | "select" | "checkbox" | "number" | "control";
+  value: string;
+  checked: boolean;
+  options: SchemaFormOption[];
+}
+
+/** One item of an array-of-objects field. */
+export interface SchemaFormRowView {
+  /** Stable across a repaint, so typing in one row does not rebuild the others. */
+  key: string;
+  /** The owning field's key — see {@link SchemaFormCellView.field}. */
+  field: string;
+  /** The remove button's accessible name; it is icon-only. */
+  removeLabel: string;
+  cells: SchemaFormCellView[];
+}
+
+/** A read of the shape a JSON field currently holds: `title: string`. */
+export interface SchemaFormChipView {
+  key: string;
+  label: string;
+}
+
+/** One property of the schema, as the document draws it. Every field is already decided. */
+export interface SchemaFormFieldView {
+  /** The schema property key: this row's reconcile identity, and what every callback names. */
+  key: string;
+  /** What the row is addressed by — `ps.name` when the schema renames it, else the key. */
+  prop: string;
+  label: string;
+  /** The sentence under the row. Empty draws no help line. */
+  description: string;
+  required: boolean;
+  kind: SchemaFormFieldKind;
+  /** The value as the control reads it — a string for every kind but `checkbox` and `rows`. */
+  value: string;
+  checked: boolean;
+  placeholder: string;
+  /** Choices for `select`, suggestions for `pointer`. */
+  options: SchemaFormOption[];
+  /** Whether the pointer rung has anything to suggest; with none it is a field alone. */
+  hasOptions: boolean;
+  /** Bounds off the property schema, so the control refuses out-of-range input itself. */
+  min: string;
+  max: string;
+  step: string;
+  /** Draw the text control monospaced — a pointer or a code-ish value. */
+  mono: boolean;
+  /** Draw the text control as a text area. */
+  multiline: boolean;
+  /** Why this value is refused (§7.1's inline tier). Empty draws nothing. */
+  error: string;
+  /** Whether there is a refusal to announce. A document branches on a flag, never on a length. */
+  hasError: boolean;
+  /** The row's value is refused: the kit shades the label and the help sentence. */
+  invalid: boolean;
+  /** `×3` from three refusals up; empty below two. */
+  errorCount: string;
+  hasCount: boolean;
+  /** Whether the value ladder is on offer here at all. */
+  hasChip: boolean;
+  /** The rung's name in the ladder's own vocabulary — "Fixed value", "From data…". */
+  sourceLabel: string;
+  /** The chip's accessible name and its tooltip. */
+  sourceName: string;
+  sourceHint: string;
+  /** `"bound"` once the value is produced from something else; `"fixed"` while it is typed. */
+  source: string;
+  /** The position permits exactly one rung, so the chip states it and refuses to open. */
+  sourceLocked: boolean;
+  /** The chips above a JSON field, naming the shape it holds. */
+  chips: SchemaFormChipView[];
+  hasChips: boolean;
+  rows: SchemaFormRowView[];
+  /** The add button's accessible name on an array-of-objects field. */
+  addLabel: string;
+}
+
+/** What the reader can do. Every one of these is a decision the flow makes. */
+export interface SchemaFormActions {
+  /** A keystroke in a text control: the flow debounces and commits. */
+  edit: (key: string, value: string) => void;
+  /** A committed scalar — a change event, a picked option, a typed pointer. */
+  commit: (key: string, value: string) => void;
+  commitChecked: (key: string, checked: boolean) => void;
+  /** A keystroke in a JSON control: parsed on a debounce, kept when it parses. */
+  editJson: (key: string, text: string) => void;
+  /** Open the value-source picker over the chip that was clicked. */
+  pickSource: (key: string, anchor: HTMLElement) => void;
+  editCell: (field: string, row: string, cell: string, value: string) => void;
+  editCellChecked: (field: string, row: string, cell: string, checked: boolean) => void;
+  removeRow: (field: string, row: string) => void;
+  addRow: (field: string) => void;
+}
+
+/** Everything the document reads that is not a row. */
+export interface SchemaFormView {
+  fields: SchemaFormFieldView[];
+}
+
+export interface SchemaFormSurface {
+  /** The element the document lives in — handed to a caller's lit template as a child value. */
+  readonly host: HTMLElement;
+  /** Bring the standing surface up to date, remounting only if its root has been taken away. */
+  readonly update: (view: SchemaFormView) => void;
+  /** Take the document down; the host is left empty for its caller to drop. */
+  readonly dispose: () => void;
+}
+
+/** A control host the document drew, reported as the runtime created it. */
+export type ControlHostSink = (id: string, host: HTMLElement) => void;
+
+interface SchemaFormScope extends Record<string, unknown>, SchemaFormView, SchemaFormActions {
+  /** The Mixed text placeholder, held in state because the literal is itself a template. */
+  templatePlaceholder: string;
+}
+
+/**
+ * The id a control host announces itself under: a field host is its property, a cell host is its
+ * `field/row/property` triple.
+ *
+ * Read out of the node's own `$map` scope rather than off the element, because `onNodeCreated`
+ * fires BEFORE the runtime applies attributes — so an element that has just been created carries
+ * neither its `part` nor its `data-control` yet, and a check on either answers no for exactly the
+ * node that needs filling.
+ */
+function controlIdOf(part: string, state: JxScope | undefined): string {
+  const item = (state?.["$map"] as { item?: Record<string, unknown> } | undefined)?.item;
+  const id =
+    part === "control-host"
+      ? item?.["key"]
+      : part === "cell-control-host"
+        ? item?.["id"]
+        : undefined;
+  return typeof id === "string" ? id : "";
+}
+
+/** A node definition's `part`, as written in the document. */
+function partOf(def: JxElement | string): string {
+  const part = typeof def === "string" ? undefined : def.attributes?.["part"];
+  return typeof part === "string" ? part : "";
+}
+
+/**
+ * Create the form's surface, mounted into a host of its own.
+ *
+ * @param {SchemaFormView} view The rows to begin with.
+ * @param {SchemaFormActions} actions What each control does.
+ * @param {ControlHostSink} onControlHost Called for every registered-control host the document
+ *   draws, as it is drawn, with the id the flow put on it.
+ * @returns {SchemaFormSurface}
+ */
+export function createSchemaFormSurface(
+  view: SchemaFormView,
+  actions: SchemaFormActions,
+  onControlHost: ControlHostSink,
+): SchemaFormSurface {
+  const host = document.createElement("div");
+  host.style.display = "contents";
+  const scope = reactive({
+    ...view,
+    ...actions,
+    templatePlaceholder: "${state.…}",
+  }) as SchemaFormScope;
+
+  /** `null` while a mount is in flight — which is a standing surface, not a missing one. */
+  let handle: SurfaceHandle | null = null;
+  let mounting = false;
+  let disposed = false;
+
+  function mount(): void {
+    mounting = true;
+    void mountSurface("schema-form", scope, host, {
+      onNodeCreated: (element, _path, def, state) => {
+        if (!(element instanceof HTMLElement)) {
+          return;
+        }
+        const id = controlIdOf(partOf(def), state);
+        if (id !== "") {
+          onControlHost(id, element);
+        }
+      },
+    }).then((mounted) => {
+      mounting = false;
+      if (disposed) {
+        mounted.dispose();
+        return;
+      }
+      handle = mounted;
+    });
+  }
+
+  mount();
+
+  return {
+    dispose() {
+      disposed = true;
+      handle?.dispose();
+      handle = null;
+      host.textContent = "";
+    },
+    host,
+    update(next) {
+      scope.fields = next.fields;
+      /* A standing mount is only ASSIGNED to: rebuilding it on every repaint of the pane around it
+         would empty the field the reader is typing in. The remount below answers the one case
+         assignment cannot — a host the document has been taken out of — and it cannot fire while a
+         mount is in flight, because a record with no handle yet IS the standing one. */
+      if (disposed || mounting || (handle !== null && host.contains(handle.root))) {
+        return;
+      }
+      handle?.dispose();
+      handle = null;
+      host.textContent = "";
+      mount();
+    },
+  };
+}

package/src/surfaces/secret-field.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioSecretField",
+  "$description": "The `secret` form control (specs/extensions.md §9.1, §13): one password field whose VALUE goes to the platform's secret store and never to project.json. A descriptor names it with `\"ui\": { \"<field>\": { \"control\": \"secret\" } }`, and `ui/schema-form.ts` mounts it into the empty host its own document announces for that field. **A surface never renders back the secret it describes, and this document is where that is visible rather than remembered**: the only thing bound to the field's value is `#/state/shown`, a scope path whose whole purpose is to hold nothing. What the field is worth is said in the placeholder instead — the env NAME the store gave it, which is the only half of a secret a screen may carry. `ui/form-controls.ts` decides everything else: whether the host has a secret store at all, what the placeholder says, what a commit is worth and what the field persists.",
+  "tagName": "div",
+  "attributes": {
+    "part": "secret",
+    "role": "none"
+  },
+  "style": {
+    "$description": "`.secret-field` carried no rule anywhere — it was one of `check-styles.ts`'s ALLOWED_ORPHANS, a class emitted only so a test could find the control — so there is nothing to translate and the wrapper takes no box of its own. The field takes the width of the control host the form drew, which is the flex item; a kit field is inline-flex by default and would otherwise sit at its intrinsic width in a row sized for it.",
+    "display": "contents",
+    "& [part=\"field\"]": {
+      "width": "100%"
+    }
+  },
+  "children": [
+    {
+      "$description": "`autocomplete: new-password` because this is a place to PUT a secret rather than to prove one: without it a password manager offers to fill the field with a credential belonging to whatever site the reader last logged in to, and the offer is the manager's own UI drawn over an editor. The value binding is `#/state/shown` and nothing else ever writes to it — see the document description.",
+      "tagName": "jx-textfield",
+      "attributes": {
+        "part": "field"
+      },
+      "$props": {
+        "type": "password",
+        "size": "sm",
+        "autocomplete": "new-password",
+        "label": {
+          "$ref": "#/state/label"
+        },
+        "placeholder": {
+          "$ref": "#/state/placeholder"
+        },
+        "disabled": {
+          "$ref": "#/state/disabled"
+        },
+        "value": {
+          "$ref": "#/state/shown"
+        }
+      },
+      "onchange": {
+        "$prototype": "Function",
+        "body": [
+          {
+            "operator": "call",
+            "target": {
+              "$ref": "#/state/commit"
+            },
+            "value": [
+              {
+                "$ref": "event#/target/value"
+              }
+            ]
+          }
+        ],
+        "description": "The change bubbles out of the field's own input, so what the reader typed is read off the event rather than off the element — and it is read here, handed to the flow, and never written back onto the scope."
+      }
+    }
+  ]
+}

package/src/surfaces/secret-field.ts

@@ -0,0 +1,146 @@
+/// <reference lib="dom" />
+/**
+ * The `secret` form control as a mounted document.
+ *
+ * `ui/form-controls.ts` is the flow — it knows whether the host has a secret store, what the field
+ * already names, what a commit sends there and what the field persists afterwards — and this is the
+ * surface it draws into (`surfaces/secret-field.json`). The host belongs to the CALLER: a
+ * registered control is drawn into the empty `[part="control-host"]` that
+ * `surfaces/schema-form.json` already announces for its field, so there is a container to mount
+ * into and no wrapper of our own.
+ *
+ * **Clearing the field is a scope MOVE, not a write to the element.** The lit control assigned
+ * `target.value = ""` from inside its own change handler, which `specs/ui.md` §2 rule 5 forbids a
+ * surface from doing at all. A document's binding writes only when the scope value CHANGES, and the
+ * scope holds the empty string before the commit and after it — so an assignment of `""` is a no-op
+ * and the secret stays in the field. {@link SecretFieldSurface.clear} therefore moves `shown` to a
+ * value that is neither the secret nor the empty string and then back, which is two changes and so
+ * two writes, the second of which empties the control.
+ *
+ * The value that stands in the middle is a SPACE rather than what the reader typed, and that is the
+ * point rather than a detail: the secret never enters the scope, so a bounce that somehow lost its
+ * second half would leave a space in the field instead of the credential.
+ *
+ * @docs studio/data/auth-and-secrets
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import secretDoc from "./secret-field.json";
+
+import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("secret-field", secretDoc as unknown as JxDocument);
+
+/** What the field says right now. Every field is the flow's, never a state it derives. */
+export interface SecretFieldView {
+  /** The accessible name — the field's own label, since the control is a bare box. */
+  label: string;
+  /**
+   * Where the secret lives, or that it does not live anywhere yet.
+   *
+   * The only thing on screen that describes the value, and it names the ENV VAR rather than the
+   * credential: `Stored as MAIN_URL`, or `Not set`.
+   */
+  placeholder: string;
+  /** True where the host has no secret store, and so nowhere to put what is typed. */
+  disabled: boolean;
+}
+
+/** The one thing the reader can do here. */
+export interface SecretFieldActions {
+  /** The reader committed a value. What it is worth is the flow's decision entirely. */
+  commit: (value: string) => void;
+}
+
+export interface SecretFieldSurfaceHandle {
+  /** The container the document was mounted into — the form's own control host. */
+  host: HTMLElement;
+  /** Resolves with the document's root once it has rendered. */
+  ready: Promise<HTMLElement>;
+  update: (view: SecretFieldView) => void;
+  /** Empty the field, whatever it is holding. See the header for why it takes two writes. */
+  clear: () => void;
+  dispose: () => void;
+}
+
+interface SecretScope extends Record<string, unknown>, SecretFieldView, SecretFieldActions {
+  /**
+   * What the field's value is bound to, and the whole of the "never render a secret back" rule.
+   *
+   * It is the empty string at rest and holds a single space for the length of one synchronous
+   * bounce; nothing else is ever assigned to it.
+   */
+  shown: string;
+}
+
+/** What a freshly mounted field says: no store named, and nothing to say about the value. */
+function emptyView(): SecretFieldView {
+  return { disabled: true, label: "", placeholder: "Not set" };
+}
+
+/**
+ * Mount the secret field into `host`, wired to `actions`.
+ *
+ * @param {HTMLElement} host - The form's `[part="control-host"]` for this field
+ * @param {SecretFieldActions} actions - What a committed value does
+ * @returns {SecretFieldSurfaceHandle}
+ */
+export function mountSecretFieldSurface(
+  host: HTMLElement,
+  actions: SecretFieldActions,
+): SecretFieldSurfaceHandle {
+  host.textContent = "";
+  const scope = reactive<SecretScope>({ ...emptyView(), ...actions, shown: "" }) as SecretScope;
+
+  /** `null` while a mount is in flight — which is a standing surface, not a missing one. */
+  let handle: SurfaceHandle | null = null;
+  let mounting = true;
+  let disposed = false;
+
+  const mount = (): Promise<HTMLElement> =>
+    mountSurface("secret-field", scope, host).then((mounted) => {
+      mounting = false;
+      if (disposed) {
+        mounted.dispose();
+        return mounted.root as HTMLElement;
+      }
+      handle = mounted;
+      return mounted.root as HTMLElement;
+    });
+
+  const ready = mount();
+
+  return {
+    clear() {
+      scope.shown = " ";
+      scope.shown = "";
+    },
+    dispose() {
+      disposed = true;
+      handle?.dispose();
+      handle = null;
+      host.textContent = "";
+    },
+    host,
+    ready,
+    update(view) {
+      scope.disabled = view.disabled;
+      scope.label = view.label;
+      scope.placeholder = view.placeholder;
+      /* A standing mount is only ASSIGNED to: rebuilding it on every repaint of the form around it
+         would empty the field the reader is typing in. The remount below answers the one case
+         assignment cannot — a host the document has been taken out of — and it cannot fire while a
+         mount is in flight, because a record with no handle yet IS the standing one. */
+      if (disposed || mounting || (handle !== null && host.contains(handle.root))) {
+        return;
+      }
+      handle?.dispose();
+      handle = null;
+      mounting = true;
+      host.textContent = "";
+      void mount();
+    },
+  };
+}