@jxsuite/studio 6.1.1 → 6.1.2

package/src/surfaces/preferences.ts

@@ -27,17 +27,18 @@
  * @docs studio/interface/preferences
  */
 
+import { isString } from "@jxsuite/schema/guards";
 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 preferencesDoc from "./preferences.json";
-import type { JxElement, JxDocument } from "@jxsuite/schema/types";
+import type { JxElement } from "@jxsuite/schema/types";
 import type { JxScope } from "@jxsuite/runtime/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("preferences", preferencesDoc as unknown as JxDocument);
+registerSurface("preferences", preferencesDoc);
 
 /** One row of the section list. `current` is the string `aria-current` takes. */
 export interface PreferencesSectionRow {
@@ -173,7 +174,7 @@ interface PreferencesFlags {
   hasConflict: boolean;
 }
 
-interface PreferencesScope extends Record<string, unknown>, PreferencesView, PreferencesFlags {
+interface PreferencesScope extends PreferencesView, PreferencesFlags {
   selectSection: (id: string) => void;
   setTheme: (value: string) => void;
   runAccountAction: (key: string) => void;
@@ -199,8 +200,8 @@ function derive(view: PreferencesView): PreferencesView & PreferencesFlags {
 
 /** The `part` a node's definition carries, or `""` for a text node or an unmarked element. */
 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 : "";
 }
 
 /**
@@ -234,10 +235,16 @@ export function openPreferencesSurface(
     closed = true;
     options.onClosed();
   };
+  /* 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;
 
-  const scope = reactive({
+  const scope: PreferencesScope = reactive<PreferencesScope>({
     ...derive(options.view),
     capture: (_scope: JxScope, event: Event) => {
+      /* SAFETY: `preferences.json` names `capture` in exactly one place, the keys sheet's
+         `onkeydown`, so the event the runtime hands it is always the platform's `KeyboardEvent`. */
       options.onCaptureKey(event as KeyboardEvent);
     },
     closed: finish,
@@ -270,7 +277,7 @@ export function openPreferencesSurface(
     toggleRebind: (commandId: string) => {
       options.onToggleRebind(commandId);
     },
-  }) as PreferencesScope;
+  });
 
   let mounted: SurfaceHandle | null = null;
   const ready = mountSurface("preferences", scope, slot, {
@@ -287,13 +294,16 @@ export function openPreferencesSurface(
     },
   }).then(async (surface) => {
     mounted = surface;
+    /* SAFETY: `preferences.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;
     }
     /* The region goes on the platform's own `<dialog>`, which is the one element here that HAS a
@@ -323,7 +333,7 @@ export function openPreferencesSurface(
       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/progress-modal.ts

@@ -21,13 +21,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 progressDoc from "./progress-modal.json";
 import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
 
-registerSurface("progress-modal", progressDoc as unknown as JxDocument);
+registerSurface("progress-modal", progressDoc);
 
 /** What the flow hands the surface. Everything is a projection; the flow keeps the operation. */
 export interface ProgressSurfaceOptions {
@@ -64,7 +63,7 @@ export interface ProgressSurfaceHandle {
   close: () => void;
 }
 
-interface ProgressScope extends Record<string, unknown> {
+interface ProgressScope {
   title: string;
   status: string;
   /**
@@ -91,7 +90,11 @@ export function openProgressSurface(options: ProgressSurfaceOptions): ProgressSu
   options.layer.append(slot);
 
   let closed = false;
-  const scope = reactive<ProgressScope>({
+  /* 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;
+  const scope: ProgressScope = reactive<ProgressScope>({
     background: () => {
       options.onBackground();
     },
@@ -104,12 +107,15 @@ export function openProgressSurface(options: ProgressSurfaceOptions): ProgressSu
     },
     status: options.status,
     title: options.title,
-  }) as ProgressScope;
+  });
 
   let mounted: SurfaceHandle | null = null;
   const ready = mountSurface("progress-modal", scope, slot).then(async (surface) => {
+    /* SAFETY: `progress-modal.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;
     }
@@ -118,7 +124,7 @@ export function openProgressSurface(options: ProgressSurfaceOptions): ProgressSu
        DOCUMENT rendered, while the element's OWN template is one `connectedCallback` later.
        `showModal` in between finds no `<dialog>` to open, and the surface never shows. */
     await whenReady(element);
-    if (closed) {
+    if (isClosed()) {
       return element;
     }
     showModal(element);
@@ -134,7 +140,7 @@ export function openProgressSurface(options: ProgressSurfaceOptions): ProgressSu
       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.
       mounted?.dispose();

package/src/surfaces/properties-panel.json

@@ -629,7 +629,7 @@
                             "display": "contents"
                           },
                           "$switch": {
-                            "$ref": "$map/item/shape"
+                            "$ref": "$map/item/variant"
                           },
                           "cases": {
                             "field": {

package/src/surfaces/properties-panel.ts

@@ -31,14 +31,16 @@
  * @docs studio/design/properties
  */
 
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import propertiesPanelDoc from "./properties-panel.json";
-import type { SurfaceHandle } from "../ui/surface";
+import type { SurfaceAction, SurfaceHandle, SurfaceOption } from "../ui/surface";
+import type { ColorTokenView } from "../ui/color-selector";
 import type { JxScope } from "@jxsuite/runtime/types";
-import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+import type { JxElement } from "@jxsuite/schema/types";
 
-registerSurface("properties-panel", propertiesPanelDoc as unknown as JxDocument);
+registerSurface("properties-panel", propertiesPanelDoc);
 
 /** Which control a `field` row draws. The flow picks it; the document switches on it. */
 export type ContentFieldKind =
@@ -52,25 +54,7 @@ export type ContentFieldKind =
   | "control";
 
 /** What a row is drawn as. Everything a section body can hold is one of these. */
-export type ContentRowShape = "field" | "kv" | "note" | "action" | "file";
-
-/**
- * One colour the project has named, as a `color` row's palette draws it.
- *
- * The same three fields the Style tab projects, and for the same reason: `value` is the reference a
- * click commits, `color` is only how it reads on screen, and `label` is what a reader hears.
- */
-export interface ContentTokenView extends Record<string, unknown> {
-  value: string;
-  color: string;
-  label: string;
-}
-
-/** A choice a select offers, in the shape the kit's select reads. */
-export interface ContentOption {
-  value: string;
-  label: string;
-}
+export type ContentRowVariant = "field" | "kv" | "note" | "action" | "file";
 
 /**
  * One row of a section — every field already decided, whatever shape it is.
@@ -81,7 +65,7 @@ export interface ContentOption {
 export interface ContentRowView {
   /** The row's reconcile identity AND what every callback hands back. */
   key: string;
-  shape: ContentRowShape;
+  variant: ContentRowVariant;
   /** `data-prop` — what `inspector/field:<prop>` addresses. Every shape carries one. */
   prop: string;
   /** The visible label of a `field`; the accessible name of a `kv` pair's controls. */
@@ -99,9 +83,9 @@ export interface ContentRowView {
   /** Draw the text control monospaced — a template, a pointer, a code-ish value. */
   mono: boolean;
   /** Choices for `select`; the routes or the popover ids for a `link`'s value half. */
-  options: ContentOption[];
+  options: SurfaceOption[];
   /** The palette a `color` row offers inside its picker, and whether it has one to offer. */
-  tokens: ContentTokenView[];
+  tokens: ColorTokenView[];
   hasTokens: boolean;
   /**
    * The provenance chip's shape: `""` draws nothing (§6.7's `default` state, where absence IS the
@@ -125,7 +109,7 @@ export interface ContentRowView {
   source: string;
   /** A `link` row's kind half: the chosen kind, and the five it chooses between. */
   linkKind: string;
-  kindOptions: ContentOption[];
+  kindOptions: SurfaceOption[];
   /** `route` draws a picker of the site's own routes; `text` draws a field. */
   linkValueKind: string;
   /** A `kv` pair's key cell, and the remove button's accessible name. */
@@ -151,12 +135,6 @@ export interface ContentSectionView {
   rows: ContentRowView[];
 }
 
-/** A button an empty state offers — the action that fills the region. */
-export interface ContentEmptyAction {
-  id: string;
-  label: string;
-}
-
 /** Everything the document reads. */
 export interface ContentPanelView {
   /**
@@ -168,7 +146,7 @@ export interface ContentPanelView {
   emptyMessage: string;
   emptyDetail: string;
   hasEmptyDetail: boolean;
-  emptyActions: ContentEmptyAction[];
+  emptyActions: SurfaceAction[];
   hasEmptyActions: boolean;
   /** The layout card: the tag clicked, its class, the file it came from. */
   layoutTag: string;
@@ -218,8 +196,7 @@ export interface ContentPanelSurface {
 /** A control host the document drew, reported as the runtime created it. */
 export type ContentControlSink = (key: string, host: HTMLElement) => void;
 
-interface ContentPanelScope
-  extends Record<string, unknown>, ContentPanelView, ContentPanelActions {}
+interface ContentPanelScope extends ContentPanelView, ContentPanelActions {}
 
 /** The scope's starting shape, before the first projection lands on it. */
 export function emptyContentView(): ContentPanelView {
@@ -267,15 +244,16 @@ function controlKeyOf(part: string, state: JxScope | undefined): string {
   if (part !== "control-host") {
     return "";
   }
-  const item = (state?.["$map"] as { item?: Record<string, unknown> } | undefined)?.item;
-  const key = item?.["key"];
-  return typeof key === "string" ? key : "";
+  const map = state?.["$map"];
+  const item = isJsonObject(map) ? map["item"] : undefined;
+  const key = isJsonObject(item) ? item["key"] : undefined;
+  return isString(key) ? key : "";
 }
 
 /** 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 : "";
 }
 
 /**
@@ -296,10 +274,10 @@ export function mountContentSurface(
   actions: ContentPanelActions,
   onControlHost: ContentControlSink,
 ): ContentPanelSurface {
-  const scope = reactive<ContentPanelScope>({
+  const scope: ContentPanelScope = reactive<ContentPanelScope>({
     ...emptyContentView(),
     ...actions,
-  }) as ContentPanelScope;
+  });
   project(scope, values);
 
   let mounted: SurfaceHandle | null = null;

package/src/surfaces/publish.ts

@@ -31,23 +31,16 @@
 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 publishDoc from "./publish.json";
-import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle, SurfaceOption } from "../ui/surface";
 
-registerSurface("publish", publishDoc as unknown as JxDocument);
+registerSurface("publish", publishDoc);
 
 /** Where the Cloudflare Pages GitHub App is installed from. */
 const PAGES_APP_INSTALL_URL = "https://github.com/apps/cloudflare-pages/installations/new";
 
-/** One Cloudflare account, as the picker draws it. */
-export interface PublishAccountRow {
-  value: string;
-  label: string;
-}
-
 /** The create-and-connect form, as the reader has filled it in so far. */
 export interface PublishForm {
   accountId: string;
@@ -95,7 +88,7 @@ export interface PublishView {
   busy: boolean;
   /** The last refusal, verbatim from whatever raised it. Empty draws nothing. */
   error: string;
-  accounts: PublishAccountRow[];
+  accounts: SurfaceOption[];
   form: PublishForm;
   /** The connected Pages project, or null when this site has none yet. */
   deploy: PublishDeploy | null;
@@ -164,7 +157,7 @@ interface PublishFlags {
    */
   needsPagesApp: boolean;
   pagesAppUrl: string;
-  accountOptions: PublishAccountRow[];
+  accountOptions: SurfaceOption[];
   accountId: string;
   projectName: string;
   owner: string;
@@ -181,7 +174,7 @@ interface PublishFlags {
   busy: boolean;
 }
 
-interface PublishScope extends Record<string, unknown>, PublishFlags {
+interface PublishScope extends PublishFlags {
   connect: () => void;
   replace: () => void;
   setToken: (value: string) => void;
@@ -286,8 +279,12 @@ export function openPublishSurface(options: PublishSurfaceOptions): PublishSurfa
     closed = true;
     options.onClosed();
   };
+  /* 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;
 
-  const scope = reactive({
+  const scope: PublishScope = reactive<PublishScope>({
     ...derive(options.view),
     closed: finish,
     connect: () => {
@@ -341,18 +338,21 @@ export function openPublishSurface(options: PublishSurfaceOptions): PublishSurfa
       tokenDraft = "";
       options.onSaveToken(token);
     },
-  }) as PublishScope;
+  });
 
   let mounted: SurfaceHandle | null = null;
   const ready = mountSurface("publish", scope, slot).then(async (surface) => {
     mounted = surface;
+    /* SAFETY: `publish.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;
     }
     /* The region goes on the platform's own `<dialog>`, which is the one element here that HAS a
@@ -375,7 +375,7 @@ export function openPublishSurface(options: PublishSurfaceOptions): PublishSurfa
       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/push-plan.ts

@@ -13,10 +13,9 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import pushPlanDoc from "./push-plan.json";
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("push-plan", pushPlanDoc as unknown as JxDocument);
+registerSurface("push-plan", pushPlanDoc);
 
 /** One step of the plan. `kind` colours the rule beside it; nothing here reads it otherwise. */
 export interface PushStepRow {
@@ -44,8 +43,6 @@ export interface PushPlanSurfaceHandle {
   dispose: () => void;
 }
 
-interface PushPlanScope extends Record<string, unknown>, PushPlanView {}
-
 /**
  * Mount the plan into `host`.
  *
@@ -54,20 +51,22 @@ interface PushPlanScope extends Record<string, unknown>, PushPlanView {}
  * @returns {PushPlanSurfaceHandle}
  */
 export function mountPushPlanSurface(host: HTMLElement, view: PushPlanView): PushPlanSurfaceHandle {
-  const scope = reactive<PushPlanScope>({
+  const scope: PushPlanView = reactive<PushPlanView>({
     errors: view.errors,
     steps: view.steps,
     warnings: view.warnings,
-  }) as PushPlanScope;
+  });
 
   let mounted: SurfaceHandle | null = null;
   let disposed = false;
   const ready = mountSurface("push-plan", scope, host).then((surface) => {
     if (disposed) {
       surface.dispose();
-      return surface.root as HTMLElement;
+    } else {
+      mounted = surface;
     }
-    mounted = surface;
+    /* SAFETY: `push-plan.json`'s root definition is a `div` element, so the runtime mounts an
+       HTMLElement; a `Text` root only comes from a document whose root is a bare string. */
     return surface.root as HTMLElement;
   });
 

package/src/surfaces/rail.ts

@@ -46,11 +46,10 @@ import { activeTab } from "../workspace/workspace";
 import railDoc from "./rail.json";
 
 import type { EffectScope } from "@vue/reactivity";
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { PanelRecord } from "../panels/panel-registry";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("rail", railDoc as unknown as JxDocument);
+registerSurface("rail", railDoc);
 
 /** One rail button, as the surface reads it. */
 interface RailButton {
@@ -72,7 +71,13 @@ interface RailGroupProjection {
   panels: RailButton[];
 }
 
-interface RailScope extends Record<string, unknown> {
+/** The parts of the rail's scope recomputed from the registry and the shell on every render. */
+type RailProjection = Pick<
+  RailScope,
+  "groups" | "libraryOpen" | "libraryVisible" | "settingsVisible"
+>;
+
+interface RailScope {
   groups: RailGroupProjection[];
   settingsVisible: boolean;
   settingsOpen: boolean;
@@ -80,7 +85,7 @@ interface RailScope extends Record<string, unknown> {
   libraryOpen: boolean;
   openLibrary: () => void;
   toggle: (id: string) => void;
-  openSettings: (anchor: unknown) => void;
+  openSettings: (anchor: EventTarget | null) => void;
 }
 
 let _scope: EffectScope | null = null;
@@ -112,12 +117,7 @@ export function toggleRailPanel(panel: PanelRecord): void {
 }
 
 /** The rail, as the surface reads it, from the registry and the shell as they stand now. */
-function project(): {
-  groups: RailGroupProjection[];
-  settingsVisible: boolean;
-  libraryVisible: boolean;
-  libraryOpen: boolean;
-} {
+function project(): RailProjection {
   const ctx = panelContext();
   const groups = railGroups(ctx).map((group, index) => ({
     dividerAbove: index > 0,
@@ -146,14 +146,14 @@ const LIBRARY_COMMAND = "library.open";
 
 /** The reactive scope the surface reads, made once. */
 function state(): RailScope {
-  _state ??= reactive({
+  _state ??= reactive<RailScope>({
     groups: [],
     libraryOpen: false,
     libraryVisible: false,
     openLibrary: () => {
       void runActiveReported(LIBRARY_COMMAND, undefined, "Navigator rail");
     },
-    openSettings: (anchor: unknown) => {
+    openSettings: (anchor: EventTarget | null) => {
       if (!(anchor instanceof HTMLElement)) {
         return;
       }
@@ -175,7 +175,7 @@ function state(): RailScope {
         toggleRailPanel(panel);
       }
     },
-  }) as RailScope;
+  });
   return _state;
 }
 

package/src/surfaces/reference-field.ts

@@ -25,16 +25,9 @@ import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import referenceDoc from "./reference-field.json";
 
-import type { JxDocument } from "@jxsuite/schema/types";
-import type { SurfaceHandle } from "../ui/surface";
+import type { SurfaceHandle, SurfaceOption } from "../ui/surface";
 
-registerSurface("reference-field", referenceDoc as unknown as JxDocument);
-
-/** One row of the picker: an entry id, the empty row, or the value that is not on disk. */
-export interface ReferenceChoice {
-  value: string;
-  label: string;
-}
+registerSurface("reference-field", referenceDoc);
 
 /** What the field says right now. Every field is the flow's, never a state it derives. */
 export interface ReferenceFieldView {
@@ -50,7 +43,7 @@ export interface ReferenceFieldView {
   /** The entry id the field holds, as a string. */
   value: string;
   /** The picker's rows, in the order they are offered. Empty on a text field. */
-  options: ReferenceChoice[];
+  options: SurfaceOption[];
   /** True while the read is in flight: the picker is inert and says so in its one row. */
   disabled: boolean;
   /** A sentence under the control. Empty draws none. */
@@ -82,8 +75,7 @@ export interface ReferenceFieldSurfaceHandle {
   dispose: () => void;
 }
 
-interface ReferenceScope
-  extends Record<string, unknown>, ReferenceFieldView, ReferenceFieldActions {}
+interface ReferenceScope extends ReferenceFieldView, ReferenceFieldActions {}
 
 /** The view a freshly mounted surface starts on: a picker that has not been told anything. */
 function emptyView(): ReferenceFieldView {
@@ -112,7 +104,7 @@ export function mountReferenceFieldSurface(
   actions: ReferenceFieldActions,
 ): ReferenceFieldSurfaceHandle {
   host.textContent = "";
-  const scope = reactive<ReferenceScope>({ ...emptyView(), ...actions }) as ReferenceScope;
+  const scope: ReferenceScope = reactive<ReferenceScope>({ ...emptyView(), ...actions });
 
   /** `null` while a mount is in flight — which is a standing surface, not a missing one. */
   let handle: SurfaceHandle | null = null;
@@ -121,13 +113,17 @@ export function mountReferenceFieldSurface(
 
   const mount = (): Promise<HTMLElement> =>
     mountSurface("reference-field", scope, host).then((mounted) => {
+      /* SAFETY: `reference-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();