@jxsuite/studio 6.1.1 → 8.0.0

package/src/surfaces/formula-palette.ts

@@ -39,9 +39,8 @@ import formulaPaletteDoc from "./formula-palette.json";
 
 import type { FormulaCatalogEntry } from "../ui/formula-catalog";
 import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
 
-registerSurface("formula-palette", formulaPaletteDoc as unknown as JxDocument);
+registerSurface("formula-palette", formulaPaletteDoc);
 
 /** The popover slot id, and so the `overlay.popover:formula-palette` region the shots address. */
 const SLOT = "formula-palette";
@@ -81,7 +80,7 @@ interface GroupProjection {
 }
 
 /** The scope `formula-palette.json` reads, and the six things a gesture asks of this module. */
-interface FormulaPaletteScope extends Record<string, unknown> {
+interface FormulaPaletteScope {
   open: boolean;
   query: string;
   groups: GroupProjection[];
@@ -106,7 +105,7 @@ interface FormulaPaletteScope extends Record<string, unknown> {
   move: (delta: number) => void;
   activate: () => void;
   hover: (index: number) => void;
-  activateRow: (value: unknown) => void;
+  activateRow: (value: string) => void;
 }
 
 let _open = false;
@@ -228,7 +227,7 @@ function scope(): FormulaPaletteScope {
     },
     open: false,
     query: "",
-  }) as FormulaPaletteScope;
+  });
   return _scope;
 }
 

package/src/surfaces/github-auth.ts

@@ -27,13 +27,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 githubAuthDoc from "./github-auth.json";
-import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
+import type { DialogLayerHandle, SurfaceHandle } from "../ui/surface";
 
-registerSurface("github-auth", githubAuthDoc as unknown as JxDocument);
+registerSurface("github-auth", githubAuthDoc);
 
 export interface GithubAuthSurfaceOptions {
   /** Where the dialog is mounted — the dialog layer, handed in so this never reaches back. */
@@ -48,16 +47,7 @@ export interface GithubAuthSurfaceOptions {
   onClosed: () => void;
 }
 
-export interface GithubAuthSurfaceHandle {
-  /** The slot in the dialog layer that carries the region. */
-  host: HTMLElement;
-  /** Resolves with the `jx-dialog` element once it has rendered and been opened. */
-  ready: Promise<HTMLElement>;
-  /** Close the dialog (the platform restores focus) and dispose the document. Idempotent. */
-  close: () => void;
-}
-
-interface GithubAuthScope extends Record<string, unknown> {
+interface GithubAuthScope {
   userCode: string;
   verificationUri: string;
   cancel: () => void;
@@ -65,7 +55,7 @@ interface GithubAuthScope extends Record<string, unknown> {
 }
 
 /** Put the code up. The handle's `ready` resolves once the dialog is showing. */
-export function openGithubAuthSurface(options: GithubAuthSurfaceOptions): GithubAuthSurfaceHandle {
+export function openGithubAuthSurface(options: GithubAuthSurfaceOptions): DialogLayerHandle {
   const slot = document.createElement("div");
   /* The layer is `pointer-events: none` so a click passes through it when nothing is up, and every
      slot in it turns them back on for its own content. `pointer-events` INHERITS, and the top layer
@@ -90,26 +80,32 @@ export function openGithubAuthSurface(options: GithubAuthSurfaceOptions): Github
     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<GithubAuthScope>({
+  const scope: GithubAuthScope = reactive<GithubAuthScope>({
     cancel: () => {
       options.onCancel();
     },
     closed: finish,
     userCode: options.userCode,
     verificationUri: options.verificationUri,
-  }) as GithubAuthScope;
+  });
 
   let mounted: SurfaceHandle | null = null;
   const ready = mountSurface("github-auth", scope, slot).then(async (surface) => {
     mounted = surface;
+    /* SAFETY: `github-auth.json`'s root definition is a `jx-dialog` element, 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;
     }
     showModal(element);
@@ -125,7 +121,7 @@ export function openGithubAuthSurface(options: GithubAuthSurfaceOptions): Github
       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/github-publish.ts

@@ -22,13 +22,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 githubPublishDoc from "./github-publish.json";
-import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
+import type { DialogLayerHandle, SurfaceHandle } from "../ui/surface";
 
-registerSurface("github-publish", githubPublishDoc as unknown as JxDocument);
+registerSurface("github-publish", githubPublishDoc);
 
 /**
  * What the dialog collects.
@@ -55,15 +54,7 @@ export interface GithubPublishSurfaceOptions {
   onClosed: () => void;
 }
 
-export interface GithubPublishSurfaceHandle {
-  host: HTMLElement;
-  /** Resolves with the `jx-dialog` element once it has rendered and been opened. */
-  ready: Promise<HTMLElement>;
-  /** Close the dialog (the platform restores focus) and dispose the document. Idempotent. */
-  close: () => void;
-}
-
-interface GithubPublishScope extends Record<string, unknown> {
+interface GithubPublishScope {
   name: string;
   description: string;
   isPrivate: boolean;
@@ -76,9 +67,7 @@ interface GithubPublishScope extends Record<string, unknown> {
 }
 
 /** Open the dialog. The handle's `ready` resolves once it is showing. */
-export function openGithubPublishSurface(
-  options: GithubPublishSurfaceOptions,
-): GithubPublishSurfaceHandle {
+export function openGithubPublishSurface(options: GithubPublishSurfaceOptions): DialogLayerHandle {
   const slot = document.createElement("div");
   /* The layer is `pointer-events: none` so a click passes through it when nothing is up, and every
      slot in it turns them back on for its own content. */
@@ -100,8 +89,12 @@ export function openGithubPublishSurface(
     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<GithubPublishScope>({
+  const scope: GithubPublishScope = reactive<GithubPublishScope>({
     cancel: () => {
       options.onCancel();
     },
@@ -125,13 +118,15 @@ export function openGithubPublishSurface(
     setPrivate: (value) => {
       scope.isPrivate = value;
     },
-  }) as GithubPublishScope;
+  });
 
   let mounted: SurfaceHandle | null = null;
   const ready = mountSurface("github-publish", scope, slot).then(async (surface) => {
     mounted = surface;
+    /* SAFETY: `github-publish.json`'s root definition is a `jx-dialog` element, 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;
     }
@@ -140,14 +135,14 @@ export function openGithubPublishSurface(
        `<dialog>` to open — the body is all there, correctly styled, and never shows. Shared with
        `openDialogSurface` and `openAboutSurface` rather than reimplemented. */
     await whenReady(element);
-    if (closed) {
+    if (isClosed()) {
       return element;
     }
     showModal(element);
     return element;
   });
 
-  const handle: GithubPublishSurfaceHandle = {
+  const handle: DialogLayerHandle = {
     close() {
       if (closed) {
         return;
@@ -155,7 +150,7 @@ export function openGithubPublishSurface(
       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);
       }
       mounted?.dispose();
       mounted = null;

package/src/surfaces/grid-cell.ts

@@ -15,25 +15,21 @@
  * @docs studio/editing/grid
  */
 
+import { isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { openPopoverSurface } from "../ui/popover-surface";
 import { registerSurface } from "../ui/surface";
 import gridCellDoc from "./grid-cell.json";
-import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+import type { JxElement } from "@jxsuite/schema/types";
 import type { JxPath } from "@jxsuite/runtime/types";
-import type { PopoverSurfaceHandle } from "../ui/popover-surface";
+import type { OpenPopoverSurfaceOptions, PopoverSurfaceHandle } from "../ui/popover-surface";
+import type { SurfaceOption } from "../ui/surface";
 
-registerSurface("grid-cell", gridCellDoc as unknown as JxDocument);
+registerSurface("grid-cell", gridCellDoc);
 
 /** The slot id, and so the panel's region: `overlay.popover:grid/cell`. */
 const SLOT = "grid/cell";
 
-/** One row of a relationship column's list. */
-export interface GridCellOption {
-  value: string;
-  label: string;
-}
-
 /** Everything the panel draws. */
 export interface GridCellView {
   x: number;
@@ -45,7 +41,7 @@ export interface GridCellView {
   /** "Entries of “post”", when the column names a target type. */
   hint: string;
   hintState: "hidden" | "shown";
-  options: GridCellOption[];
+  options: SurfaceOption[];
   /** What the list holds; empty when the current value is not one of its rows. */
   value: string;
   /** What the free-text field holds: the current value when no row matches it. */
@@ -62,28 +58,26 @@ export interface GridCellSurfaceOptions {
   dismissed?: () => void;
 }
 
-export type GridCellSurfaceHandle = PopoverSurfaceHandle;
-
-interface GridCellScope extends Record<string, unknown>, GridCellView {
+interface GridCellScope extends GridCellView {
   pick: (value: string) => void;
   done: () => void;
 }
 
 /** 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 : "";
 }
 
 /**
  * Open the cell value picker.
  *
  * @param {GridCellSurfaceOptions} options
- * @returns {GridCellSurfaceHandle}
+ * @returns {PopoverSurfaceHandle}
  */
-export function openGridCellSurface(options: GridCellSurfaceOptions): GridCellSurfaceHandle {
+export function openGridCellSurface(options: GridCellSurfaceOptions): PopoverSurfaceHandle {
   const { view } = options;
-  const scope = reactive<GridCellScope>({
+  const scope: GridCellScope = reactive<GridCellScope>({
     custom: view.custom,
     done: () => {
       handle.close();
@@ -98,23 +92,28 @@ export function openGridCellSurface(options: GridCellSurfaceOptions): GridCellSu
     value: view.value,
     x: view.x,
     y: view.y,
-  }) as GridCellScope;
+  });
 
-  const handle = openPopoverSurface({
+  const popover: OpenPopoverSurfaceOptions<GridCellScope> = {
     anchor: null,
     name: "grid-cell",
     scope,
     slot: SLOT,
-    ...(options.dismissed ? { onDismissed: options.dismissed } : {}),
-    ...(options.island
-      ? {
-          onNodeCreated: (element: HTMLElement | Text, _path: JxPath, def: JxElement | string) => {
-            if (partOf(def) === "picker-host" && element instanceof HTMLElement) {
-              options.island?.(element);
-            }
-          },
-        }
-      : {}),
-  });
+  };
+  if (options.dismissed) {
+    popover.onDismissed = options.dismissed;
+  }
+  if (options.island) {
+    popover.onNodeCreated = (
+      element: HTMLElement | Text,
+      _path: JxPath,
+      def: JxElement | string,
+    ) => {
+      if (partOf(def) === "picker-host" && element instanceof HTMLElement) {
+        options.island?.(element);
+      }
+    };
+  }
+  const handle = openPopoverSurface(popover);
   return handle;
 }

package/src/surfaces/grid-open.ts

@@ -19,16 +19,9 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import gridOpenDoc from "./grid-open.json";
-import type { JxDocument } from "@jxsuite/schema/types";
-import type { SurfaceHandle } from "../ui/surface";
+import type { SurfaceAction, SurfaceHandle } from "../ui/surface";
 
-registerSurface("grid-open", gridOpenDoc as unknown as JxDocument);
-
-/** One openable source. The id is opaque here: only the flow knows what it names. */
-export interface GridSourceRow {
-  id: string;
-  label: string;
-}
+registerSurface("grid-open", gridOpenDoc);
 
 /** One origin of sources — the project itself, or one connection. */
 export interface GridSourceGroup {
@@ -36,7 +29,7 @@ export interface GridSourceGroup {
   key: string;
   title: string;
   state: "listed" | "empty";
-  rows: GridSourceRow[];
+  rows: SurfaceAction[];
   /** Why the group is empty, in a sentence. Empty when it is not. */
   emptyMessage: string;
 }
@@ -47,7 +40,7 @@ export interface GridOpenSurfaceHandle {
   dispose: () => void;
 }
 
-interface GridOpenScope extends Record<string, unknown> {
+interface GridOpenScope {
   groups: GridSourceGroup[];
   open: (id: string) => void;
 }
@@ -65,16 +58,19 @@ export function mountGridOpenSurface(
   groups: GridSourceGroup[],
   open: (id: string) => void,
 ): GridOpenSurfaceHandle {
-  const scope = reactive<GridOpenScope>({ groups, open }) as GridOpenScope;
+  const scope: GridOpenScope = reactive<GridOpenScope>({ groups, open });
   let mounted: SurfaceHandle | null = null;
   let disposed = false;
   const ready = mountSurface("grid-open", scope, host).then((surface) => {
+    /* SAFETY: `grid-open.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. */
+    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 {
     dispose() {

package/src/surfaces/grid-panel.ts

@@ -25,13 +25,14 @@
  * @docs studio/data/grid
  */
 
+import { isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import gridPanelDoc from "./grid-panel.json";
-import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+import type { JxElement } from "@jxsuite/schema/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("grid-panel", gridPanelDoc as unknown as JxDocument);
+registerSurface("grid-panel", gridPanelDoc);
 
 /** Everything the frame draws, as one value. Every field is already a string or a boolean. */
 export interface GridPanelView {
@@ -98,7 +99,7 @@ export interface GridPanelSurfaceHandle {
 }
 
 /** The scope the document reads: {@link GridPanelView} plus the actions its controls call. */
-interface GridPanelScope extends Record<string, unknown>, GridPanelView, GridPanelActions {}
+interface GridPanelScope extends GridPanelView, GridPanelActions {}
 
 /** Write a projection into the scope. */
 function project(scope: GridPanelScope, view: GridPanelView): void {
@@ -124,8 +125,8 @@ function project(scope: GridPanelScope, view: GridPanelView): void {
 
 /** 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 : "";
 }
 
 /**
@@ -142,7 +143,7 @@ export function mountGridPanelSurface(
   actions: GridPanelActions,
 ): GridPanelSurfaceHandle {
   host.replaceChildren();
-  const scope = reactive<GridPanelScope>({
+  const scope: GridPanelScope = reactive<GridPanelScope>({
     addRow: actions.addRow,
     canDelete: false,
     canInsert: false,
@@ -172,7 +173,7 @@ export function mountGridPanelSurface(
     setFilter: actions.setFilter,
     view: "grid",
     viewLabel: "View",
-  }) as GridPanelScope;
+  });
   project(scope, view);
 
   let mounted: SurfaceHandle | null = null;
@@ -186,12 +187,15 @@ export function mountGridPanelSurface(
       }
     },
   }).then((surface) => {
+    /* SAFETY: `grid-panel.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. */
+    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/grid-replace.ts

@@ -15,10 +15,9 @@ import { reactive } from "../reactivity";
 import { openPopoverSurface } from "../ui/popover-surface";
 import { registerSurface } from "../ui/surface";
 import gridReplaceDoc from "./grid-replace.json";
-import type { JxDocument } from "@jxsuite/schema/types";
-import type { PopoverSurfaceHandle } from "../ui/popover-surface";
+import type { OpenPopoverSurfaceOptions, PopoverSurfaceHandle } from "../ui/popover-surface";
 
-registerSurface("grid-replace", gridReplaceDoc as unknown as JxDocument);
+registerSurface("grid-replace", gridReplaceDoc);
 
 /** The slot id, and so the panel's region: `overlay.popover:grid/replace`. */
 const SLOT = "grid/replace";
@@ -31,9 +30,7 @@ export interface GridReplaceActions {
   dismissed?: () => void;
 }
 
-export type GridReplaceSurfaceHandle = PopoverSurfaceHandle;
-
-interface GridReplaceScope extends Record<string, unknown> {
+interface GridReplaceScope {
   x: number;
   y: number;
   find: string;
@@ -50,14 +47,14 @@ interface GridReplaceScope extends Record<string, unknown> {
  * @param {{ x: number; y: number }} at - Where it opens, in viewport pixels
  * @param {GridReplaceActions} actions - What each press does
  * @param {HTMLElement | null} anchor - The toolbar button it hangs from
- * @returns {GridReplaceSurfaceHandle}
+ * @returns {PopoverSurfaceHandle}
  */
 export function openGridReplaceSurface(
   at: { x: number; y: number },
   actions: GridReplaceActions,
   anchor: HTMLElement | null,
-): GridReplaceSurfaceHandle {
-  const scope = reactive<GridReplaceScope>({
+): PopoverSurfaceHandle {
+  const scope: GridReplaceScope = reactive<GridReplaceScope>({
     cancel: () => {
       handle.close();
       actions.dismissed?.();
@@ -75,15 +72,18 @@ export function openGridReplaceSurface(
     },
     x: at.x,
     y: at.y,
-  }) as GridReplaceScope;
+  });
 
-  const handle = openPopoverSurface({
+  const popover: OpenPopoverSurfaceOptions<GridReplaceScope> = {
     anchor,
     name: "grid-replace",
     scope,
     slot: SLOT,
-    ...(actions.dismissed ? { onDismissed: actions.dismissed } : {}),
-  });
+  };
+  if (actions.dismissed) {
+    popover.onDismissed = actions.dismissed;
+  }
+  const handle = openPopoverSurface(popover);
 
   return handle;
 }

package/src/surfaces/grid-views.ts

@@ -20,10 +20,10 @@ import { reactive } from "../reactivity";
 import { openPopoverSurface } from "../ui/popover-surface";
 import { registerSurface } from "../ui/surface";
 import gridViewsDoc from "./grid-views.json";
-import type { JxDocument } from "@jxsuite/schema/types";
-import type { PopoverSurfaceHandle } from "../ui/popover-surface";
+import type { OpenPopoverSurfaceOptions, PopoverSurfaceHandle } from "../ui/popover-surface";
+import type { SurfaceOption } from "../ui/surface";
 
-registerSurface("grid-views", gridViewsDoc as unknown as JxDocument);
+registerSurface("grid-views", gridViewsDoc);
 
 /** The slot id, and so the panel's region: `overlay.popover:grid/views`. */
 const SLOT = "grid/views";
@@ -41,12 +41,6 @@ export interface GridSavedViewRow {
   deleteLabel: string;
 }
 
-/** A closed list of choices, in the shape the kit's select reads. */
-export interface GridSelectOption {
-  value: string;
-  label: string;
-}
-
 /** One column's visibility. */
 export interface GridColumnToggle {
   field: string;
@@ -65,9 +59,9 @@ export interface GridViewsView {
   saveLabel: string;
   columns: GridColumnToggle[];
   /** Every column, plus the "Source order" row that clears the sort. */
-  fieldOptions: GridSelectOption[];
-  dirOptions: GridSelectOption[];
-  groupOptions: GridSelectOption[];
+  fieldOptions: SurfaceOption[];
+  dirOptions: SurfaceOption[];
+  groupOptions: SurfaceOption[];
   sortField: string;
   sortDir: string;
   /** There is no sort to redirect, so the direction control is off rather than lying. */
@@ -93,7 +87,7 @@ export interface GridViewsSurfaceHandle extends PopoverSurfaceHandle {
   update: (view: GridViewsView) => void;
 }
 
-interface GridViewsScope extends Record<string, unknown>, GridViewsView, GridViewsActions {}
+interface GridViewsScope extends GridViewsView, GridViewsActions {}
 
 /** Write a projection into the scope. */
 function project(scope: GridViewsScope, view: GridViewsView): void {
@@ -125,7 +119,7 @@ export function openGridViewsSurface(
   actions: GridViewsActions,
   anchor: HTMLElement | null,
 ): GridViewsSurfaceHandle {
-  const scope = reactive<GridViewsScope>({
+  const scope: GridViewsScope = reactive<GridViewsScope>({
     applyView: actions.applyView,
     columns: [],
     deleteView: actions.deleteView,
@@ -147,16 +141,19 @@ export function openGridViewsSurface(
     viewsState: "empty",
     x: 0,
     y: 0,
-  }) as GridViewsScope;
+  });
   project(scope, view);
 
-  const handle = openPopoverSurface({
+  const popover: OpenPopoverSurfaceOptions<GridViewsScope> = {
     anchor,
     name: "grid-views",
     scope,
     slot: SLOT,
-    ...(actions.dismissed ? { onDismissed: actions.dismissed } : {}),
-  });
+  };
+  if (actions.dismissed) {
+    popover.onDismissed = actions.dismissed;
+  }
+  const handle = openPopoverSurface(popover);
 
   return {
     close: handle.close,