@jxsuite/studio 6.1.1 → 8.0.0

package/src/surfaces/schema-form.ts

@@ -29,14 +29,15 @@
  * @docs extending/ui-kit
  */
 
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import schemaFormDoc from "./schema-form.json";
-import type { SurfaceHandle } from "../ui/surface";
+import type { KeyedLabel, SurfaceHandle, SurfaceOption } from "../ui/surface";
 import type { JxScope } from "@jxsuite/runtime/types";
-import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+import type { JxElement } from "@jxsuite/schema/types";
 
-registerSurface("schema-form", schemaFormDoc as unknown as JxDocument);
+registerSurface("schema-form", schemaFormDoc);
 
 /** Which of the nine controls a row draws. The flow picks it; the document switches on it. */
 export type SchemaFormFieldKind =
@@ -50,12 +51,6 @@ export type SchemaFormFieldKind =
   | "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. */
@@ -70,7 +65,7 @@ export interface SchemaFormCellView {
   kind: "text" | "select" | "checkbox" | "number" | "control";
   value: string;
   checked: boolean;
-  options: SchemaFormOption[];
+  options: SurfaceOption[];
 }
 
 /** One item of an array-of-objects field. */
@@ -84,12 +79,6 @@ export interface SchemaFormRowView {
   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. */
@@ -106,7 +95,7 @@ export interface SchemaFormFieldView {
   checked: boolean;
   placeholder: string;
   /** Choices for `select`, suggestions for `pointer`. */
-  options: SchemaFormOption[];
+  options: SurfaceOption[];
   /** 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. */
@@ -117,6 +106,8 @@ export interface SchemaFormFieldView {
   mono: boolean;
   /** Draw the text control as a text area. */
   multiline: boolean;
+  /** The native input type of the text control: `date` for a `format: "date"` field, else `text`. */
+  inputType: string;
   /** Why this value is refused (§16.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. */
@@ -138,7 +129,7 @@ export interface SchemaFormFieldView {
   /** 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[];
+  chips: KeyedLabel[];
   hasChips: boolean;
   rows: SchemaFormRowView[];
   /** The add button's accessible name on an array-of-objects field. */
@@ -179,7 +170,7 @@ export interface SchemaFormSurface {
 /** 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 {
+interface SchemaFormScope extends SchemaFormView, SchemaFormActions {
   /** The Mixed text placeholder, held in state because the literal is itself a template. */
   templatePlaceholder: string;
 }
@@ -194,20 +185,21 @@ interface SchemaFormScope extends Record<string, unknown>, SchemaFormView, Schem
  * node that needs filling.
  */
 function controlIdOf(part: string, state: JxScope | undefined): string {
-  const item = (state?.["$map"] as { item?: Record<string, unknown> } | undefined)?.item;
+  const map = state?.["$map"];
+  const item = isJsonObject(map) && isJsonObject(map["item"]) ? map["item"] : undefined;
   const id =
     part === "control-host"
       ? item?.["key"]
       : part === "cell-control-host"
         ? item?.["id"]
         : undefined;
-  return typeof id === "string" ? id : "";
+  return isString(id) ? 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 : "";
+  const part = isString(def) ? undefined : def.attributes?.["part"];
+  return isString(part) ? part : "";
 }
 
 /**
@@ -226,11 +218,11 @@ export function createSchemaFormSurface(
 ): SchemaFormSurface {
   const host = document.createElement("div");
   host.style.display = "contents";
-  const scope = reactive({
+  const scope: SchemaFormScope = reactive<SchemaFormScope>({
     ...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;

package/src/surfaces/secret-field.ts

@@ -28,10 +28,9 @@ 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);
+registerSurface("secret-field", secretDoc);
 
 /** What the field says right now. Every field is the flow's, never a state it derives. */
 export interface SecretFieldView {
@@ -65,7 +64,7 @@ export interface SecretFieldSurfaceHandle {
   dispose: () => void;
 }
 
-interface SecretScope extends Record<string, unknown>, SecretFieldView, SecretFieldActions {
+interface SecretScope extends SecretFieldView, SecretFieldActions {
   /**
    * What the field's value is bound to, and the whole of the "never render a secret back" rule.
    *
@@ -92,7 +91,7 @@ export function mountSecretFieldSurface(
   actions: SecretFieldActions,
 ): SecretFieldSurfaceHandle {
   host.textContent = "";
-  const scope = reactive<SecretScope>({ ...emptyView(), ...actions, shown: "" }) as SecretScope;
+  const scope: SecretScope = reactive<SecretScope>({ ...emptyView(), ...actions, shown: "" });
 
   /** `null` while a mount is in flight — which is a standing surface, not a missing one. */
   let handle: SurfaceHandle | null = null;
@@ -101,13 +100,17 @@ export function mountSecretFieldSurface(
 
   const mount = (): Promise<HTMLElement> =>
     mountSurface("secret-field", scope, host).then((mounted) => {
+      /* SAFETY: `secret-field.json`'s root definition carries `tagName: "div"`, so the runtime
+         mounts an HTMLElement; a `Text` root only comes from a document whose root is a bare
+         string. */
+      const root = mounted.root as HTMLElement;
       mounting = false;
       if (disposed) {
         mounted.dispose();
-        return mounted.root as HTMLElement;
+        return root;
       }
       handle = mounted;
-      return mounted.root as HTMLElement;
+      return root;
     });
 
   const ready = mount();

package/src/surfaces/seo.json

@@ -244,7 +244,7 @@
       "color": "var(--warning)"
     },
     "& [part=\"empty\"]": {
-      "$description": "A fully-described page says so rather than printing an empty list. It borrowed `.doc-header-empty` from the card this block used to live in; the card still writes that class, so the rule stays where it is and this surface stops reaching across for it.",
+      "$description": "A fully-described page says so rather than printing an empty list.",
       "margin": "0",
       "padding": "0 0 var(--jx-space-3)",
       "fontSize": "var(--jx-text-md)",

package/src/surfaces/seo.ts

@@ -33,13 +33,12 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import { overlayRegion, REGION_ATTR } from "../ui/regions";
-import { close as closeDialog, showModal } from "@jxsuite/ui/behaviors/dialog";
+import { close, showModal } from "@jxsuite/ui/behaviors/dialog";
 import { whenReady } from "./dialog";
 import seoDoc from "./seo.json";
 import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
 
-registerSurface("seo", seoDoc as unknown as JxDocument);
+registerSurface("seo", seoDoc);
 
 /** How a field's provenance is drawn — §6.7's vocabulary, reduced to three shapes and an absence. */
 export type SeoChipKind = "none" | "dot" | "static" | "link";
@@ -65,8 +64,9 @@ export interface SeoFieldView {
   chipTitle: string;
 }
 
-/** One named warning. A list, never a total. */
+/** A named thing that is wrong, or absent. Never summed: the list IS the report. */
 export interface SeoWarningView {
+  /** Stable id, so a test and a shot name the same warning. */
   id: string;
   /** The head key it is about, so the row can carry it as code. */
   field: string;
@@ -154,17 +154,17 @@ export interface SeoSurfaceHandle {
 type LineState = "text" | "unset";
 
 /** One field row with the flags the document branches on. */
-interface SeoFieldRow extends SeoFieldView, Record<string, unknown> {
+interface SeoFieldRow extends SeoFieldView {
   valueState: LineState;
 }
 
 /** One editable row with the flags the document branches on. */
-interface SeoEditRow extends SeoEditRowView, Record<string, unknown> {
+interface SeoEditRow extends SeoEditRowView {
   hasThumb: boolean;
 }
 
 /** One group with its rows already flagged. */
-interface SeoGroupRow extends Record<string, unknown> {
+interface SeoGroupRow {
   key: string;
   title: string;
   note: string;
@@ -196,12 +196,12 @@ interface SeoFlags {
   groups: SeoGroupRow[];
 }
 
-interface SeoScope extends Record<string, unknown>, SeoFlags {
+interface SeoScope extends SeoFlags {
   documentLabel: string;
   edit: (key: string, value: string) => void;
   commit: (key: string, value: string) => void;
   upload: (key: string) => void;
-  browse: (key: string, anchor: unknown) => void;
+  browse: (key: string, anchor: EventTarget | null) => void;
   openDonor: (key: string) => void;
   closed: () => void;
 }
@@ -268,9 +268,9 @@ export function openSeoSurface(options: SeoSurfaceOptions): SeoSurfaceHandle {
     options.onClosed();
   };
 
-  const scope = reactive({
+  const scope: SeoScope = reactive<SeoScope>({
     ...derive(options.view),
-    browse: (key: string, anchor: unknown) => {
+    browse: (key: string, anchor: EventTarget | null) => {
       if (anchor instanceof HTMLElement) {
         options.onBrowse(key, anchor);
       }
@@ -288,18 +288,24 @@ export function openSeoSurface(options: SeoSurfaceOptions): SeoSurfaceHandle {
     upload: (key: string) => {
       options.onUpload(key);
     },
-  }) as SeoScope;
+  });
 
+  /* Read through a call, not the bare binding: `close()` can run while the mount is awaiting the
+     element, and a direct `closed` test after that `await` would be narrowed to the value the test
+     before it saw. */
+  const isClosed = (): boolean => closed;
   let mounted: SurfaceHandle | null = null;
   const ready = mountSurface("seo", scope, slot).then(async (surface) => {
     mounted = surface;
+    /* SAFETY: `seo.json`'s root definition carries `tagName: "jx-dialog"`, so the runtime mounts an
+       HTMLElement; a `Text` root only comes from a document whose root is a bare string. */
     const element = surface.root as HTMLElement;
-    if (closed) {
+    if (isClosed()) {
       surface.dispose();
       return element;
     }
     await whenReady(element);
-    if (closed) {
+    if (isClosed()) {
       return element;
     }
     const box = element.querySelector<HTMLElement>('dialog[part="dialog"]') ?? element;
@@ -317,7 +323,7 @@ export function openSeoSurface(options: SeoSurfaceOptions): SeoSurfaceHandle {
       const element = mounted?.root;
       if (element instanceof HTMLElement) {
         // The platform's close first, so focus goes back where it came from; then the document.
-        closeDialog(element);
+        close(element);
       }
       // A mount that has not landed yet is disposed by `ready` when it does — `finish` tells it so.
       mounted?.dispose();

package/src/surfaces/settings-contexts.ts

@@ -22,10 +22,9 @@ import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import contextsDoc from "./settings-contexts.json";
 
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("settings-contexts", contextsDoc as unknown as JxDocument);
+registerSurface("settings-contexts", contextsDoc);
 
 /** One `$media` row, as the document draws it. */
 export interface ContextRowView {
@@ -111,7 +110,7 @@ export interface ContextsSurfaceHandle {
  * would be a second place to get it wrong. The refusal lines need none — `invalid` already says
  * which control the message belongs to.
  */
-interface ContextsScope extends Record<string, unknown>, ContextsView, ContextsActions {
+interface ContextsScope extends ContextsView, ContextsActions {
   hasSectionError: boolean;
   hasNotice: boolean;
 }
@@ -141,7 +140,7 @@ export function mountContextsSurface(
   actions: ContextsActions,
 ): ContextsSurfaceHandle {
   host.textContent = "";
-  const scope = reactive<ContextsScope>({
+  const scope: ContextsScope = reactive<ContextsScope>({
     ...emptyView(),
     add: actions.add,
     hasNotice: false,
@@ -151,17 +150,20 @@ export function mountContextsSurface(
     setBase: actions.setBase,
     setQuery: actions.setQuery,
     setScheme: actions.setScheme,
-  }) as ContextsScope;
+  });
 
   let mounted: SurfaceHandle | null = null;
   let disposed = false;
   const ready = mountSurface("settings-contexts", scope, host).then((surface) => {
+    /* SAFETY: `settings-contexts.json`'s root definition carries `tagName: "div"`, so the runtime
+       mounts an HTMLElement; a `Text` root only comes from a document whose root is a bare string. */
+    const root = surface.root as HTMLElement;
     if (disposed) {
       surface.dispose();
-      return surface.root as HTMLElement;
+      return root;
     }
     mounted = surface;
-    return surface.root as HTMLElement;
+    return root;
   });
 
   return {

package/src/surfaces/settings-contributed.json

@@ -214,7 +214,7 @@
                         "part": "new-open"
                       },
                       "$props": {
-                        "label": "New Entry",
+                        "label": "${state.newLabel}",
                         "icon": "plus",
                         "quiet": true,
                         "size": "sm"
@@ -234,7 +234,7 @@
                       "children": [
                         {
                           "tagName": "span",
-                          "textContent": "New Entry"
+                          "textContent": "${state.newLabel}"
                         }
                       ]
                     },
@@ -250,8 +250,8 @@
                             "part": "new-field"
                           },
                           "$props": {
-                            "label": "New entry name",
-                            "placeholder": "entry-name",
+                            "label": "${state.newFieldLabel}",
+                            "placeholder": "${state.newPlaceholder}",
                             "size": "sm",
                             "value": {
                               "$ref": "#/state/newName"
@@ -361,7 +361,7 @@
                   "attributes": {
                     "part": "empty"
                   },
-                  "textContent": "Select or create an entry"
+                  "textContent": "${state.emptyText}"
                 },
                 "editing": {
                   "tagName": "div",

package/src/surfaces/settings-contributed.ts

@@ -26,21 +26,22 @@
  * @docs studio/projects/settings
  */
 
+import { isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import contributedDoc from "./settings-contributed.json";
 
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { SurfaceHandle } from "../ui/surface";
+import type { JxElement } from "@jxsuite/schema/types";
 
-registerSurface("settings-contributed", contributedDoc as unknown as JxDocument);
+registerSurface("settings-contributed", contributedDoc);
 
 /** One entry key in a map-layout section's left column. */
 export interface ContributedEntryView {
   /** The key in the section's map on disk — the row's identity and its `data-entry`. */
   key: string;
   selected: boolean;
-  /** `pane.primary/entry:<key>`, so a shot can name the row without a selector. */
+  /** `overlay.dialog:settings/entry:<key>`, so a shot can name the row without a selector. */
   region: string;
 }
 
@@ -60,8 +61,16 @@ export interface ContributedView {
   editorState: "empty" | "editing";
   /** What the rename field holds — the key on disk, or what the reader has just typed. */
   entryName: string;
-  /** `pane.primary/editor`. */
+  /** `overlay.dialog:settings/editor`. */
   editorRegion: string;
+  /** The new-entry button: "New content type", or "New entry" when the section names none. */
+  newLabel: string;
+  /** The new-entry field's accessible label. */
+  newFieldLabel: string;
+  /** The new-entry field's placeholder, a slug of the noun. */
+  newPlaceholder: string;
+  /** What the right column says while nothing is selected. */
+  emptyText: string;
 }
 
 /** What the reader may do here. Each one is a decision the section makes. */
@@ -101,7 +110,7 @@ export interface ContributedSurfaceHandle {
   dispose: () => void;
 }
 
-interface ContributedScope extends Record<string, unknown>, ContributedView, ContributedActions {}
+interface ContributedScope extends ContributedView, ContributedActions {}
 
 /** The view a freshly mounted surface starts on: a form layout with nothing in it. */
 function emptyView(): ContributedView {
@@ -115,14 +124,17 @@ function emptyView(): ContributedView {
     newName: "",
     newState: "closed",
     title: "",
+    emptyText: "",
+    newFieldLabel: "",
+    newLabel: "",
+    newPlaceholder: "",
   };
 }
 
 /** The `part` a node was authored with, or `""` — the only thing this adapter asks about a node. */
-function partOf(def: unknown): string {
-  const attributes = (def as { attributes?: Record<string, unknown> } | null)?.attributes;
-  const part = attributes?.["part"];
-  return typeof part === "string" ? part : "";
+function partOf(def: JxElement | string): string {
+  const part = isString(def) ? undefined : def.attributes?.["part"];
+  return isString(part) ? part : "";
 }
 
 /**
@@ -139,7 +151,7 @@ export function mountContributedSurface(
   islands: ContributedIslands,
 ): ContributedSurfaceHandle {
   host.textContent = "";
-  const scope = reactive<ContributedScope>({ ...emptyView(), ...actions }) as ContributedScope;
+  const scope: ContributedScope = reactive<ContributedScope>({ ...emptyView(), ...actions });
 
   let mounted: SurfaceHandle | null = null;
   let disposed = false;
@@ -160,12 +172,16 @@ export function mountContributedSurface(
       }
     },
   }).then((surface) => {
+    /* SAFETY: `settings-contributed.json`'s root definition carries `tagName: "section"`, so the
+       runtime mounts an HTMLElement; a `Text` root only comes from a document whose root is a bare
+       string. */
+    const root = surface.root as HTMLElement;
     if (disposed) {
       surface.dispose();
-      return surface.root as HTMLElement;
+      return root;
     }
     mounted = surface;
-    return surface.root as HTMLElement;
+    return root;
   });
 
   return {
@@ -195,6 +211,10 @@ export function mountContributedSurface(
       scope.newName = view.newName;
       scope.newState = view.newState;
       scope.title = view.title;
+      scope.emptyText = view.emptyText;
+      scope.newFieldLabel = view.newFieldLabel;
+      scope.newLabel = view.newLabel;
+      scope.newPlaceholder = view.newPlaceholder;
     },
   };
 }