@jxsuite/studio 6.1.1 → 8.0.0

package/src/surfaces/menu.ts

@@ -20,7 +20,6 @@
  * @docs studio/interface/canvas
  * @docs studio/interface/preferences
  */
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { JxScope } from "@jxsuite/runtime/types";
 import { ensureCaret } from "@jxsuite/ui/behaviors/menu";
 import { reactive } from "../reactivity";
@@ -29,7 +28,7 @@ import { mountSurface, registerSurface } from "../ui/surface";
 import { rectOf } from "../utils/geometry";
 import menuDoc from "./menu.json";
 
-registerSurface("menu", menuDoc as unknown as JxDocument);
+registerSurface("menu", menuDoc);
 
 /**
  * What a row prints: a projection of one command record, decided by the adapter that opens the
@@ -65,12 +64,12 @@ export interface OpenMenuOptions {
   /** The menu's accessible name. */
   label: string;
   /** Where the panel opens, in viewport pixels, when `place` is not given. */
-  origin?: { x: number; y: number };
+  origin?: ViewportPoint;
   /**
    * Where the panel opens as a function of its measured box: run once the popover is shown and
    * again a frame later, so a menu that hangs off a control can put its bottom flush with a floor.
    */
-  place?: (box: DOMRect) => { x: number; y: number };
+  place?: (box: DOMRect) => ViewportPoint;
   /** The lowest edge the menu and its submenus may reach; the viewport by default. */
   floor?: () => number;
   /**
@@ -113,6 +112,12 @@ export interface MenuHandle {
   readonly setRows: (rows: readonly MenuRowProjection[]) => void;
 }
 
+/** A point in viewport pixels: where a floating panel's corner sits. */
+export interface ViewportPoint {
+  x: number;
+  y: number;
+}
+
 type MenuElement = HTMLElement & {
   open?: boolean;
   x?: number;
@@ -140,7 +145,7 @@ type ProjectedRow = Omit<
 };
 
 /** The scope shape `menu.json` reads. */
-interface MenuScope extends Record<string, unknown> {
+interface MenuScope {
   rows: ProjectedRow[];
   label: string;
   x: number;
@@ -167,7 +172,7 @@ export function placementOf(
  * Where a menu with no coordinates of its own opens on an engine that cannot anchor it: below its
  * opener, leading edges aligned — the same corner the placement names.
  */
-function belowOpener(opener: HTMLElement | null | undefined): { x: number; y: number } {
+function belowOpener(opener: HTMLElement | null | undefined): ViewportPoint {
   if (!opener) {
     return { x: 0, y: 0 };
   }
@@ -205,17 +210,6 @@ function rowById(rows: readonly ProjectedRow[], id: string): ProjectedRow | unde
   return undefined;
 }
 
-const ZERO_BOX = {
-  bottom: 0,
-  height: 0,
-  left: 0,
-  right: 0,
-  top: 0,
-  width: 0,
-  x: 0,
-  y: 0,
-} as DOMRect;
-
 /**
  * Open a menu.
  *
@@ -242,15 +236,20 @@ export function openMenu(options: OpenMenuOptions): MenuHandle {
     options.onClosed?.(handle);
   };
 
+  /* `place` is first asked before anything is laid out, so it is handed an empty box: a real
+     `DOMRect` whose every edge and dimension is zero. */
   const initial = options.place
-    ? options.place(ZERO_BOX)
+    ? options.place(new DOMRect())
     : (options.origin ?? belowOpener(options.opener));
-  const scope: MenuScope = reactive({
+  const scope: MenuScope = reactive<MenuScope>({
     floor: options.floor?.() ?? 0,
     label: options.label,
     placement: placementOf(options),
     rows: options.rows.map((row) => project(row)),
     select: (_scope: JxScope, event: Event) => {
+      /* SAFETY: `menu.json` binds this handler to `onselect` alone, and a row's `select` is raised
+         by the runtime's `dispatchEvent` statement in `jx-menu-item.json`, which always constructs
+         a `CustomEvent` whose `detail` is the row's value. */
       const id = String((event as CustomEvent).detail);
       const row = rowById(scope.rows, id);
       if (!row) {
@@ -258,6 +257,7 @@ export function openMenu(options: OpenMenuOptions): MenuHandle {
       }
       // Run BEFORE closing: a command reads its target synchronously on entry, and closing the
       // Menu is what clears it.
+      handBackKeyboard(menu, options.opener ?? null);
       if (row.run) {
         row.run();
       } else {
@@ -267,7 +267,7 @@ export function openMenu(options: OpenMenuOptions): MenuHandle {
     },
     x: initial.x,
     y: initial.y,
-  }) as MenuScope;
+  });
 
   /** Put the panel where `place` says, from its box as laid out now. */
   const place = (): void => {
@@ -279,18 +279,25 @@ export function openMenu(options: OpenMenuOptions): MenuHandle {
     scope.y = at.y;
   };
 
+  /* Read through a call, not the property path: `close()` can abort the controller while the menu
+     is awaiting `jx-ready`, and a direct test after that `await` would be narrowed to the value the
+     test before it saw. */
+  const aborted = (): boolean => controller.signal.aborted;
+
   const ready = (async () => {
     const mounted = await mountSurface("menu", scope, slot, { signal: controller.signal });
-    if (controller.signal.aborted) {
+    if (aborted()) {
       // Closed before the document finished mounting; the runtime already disposed it.
       return;
     }
     ({ dispose } = mounted);
     // The document's root IS the menu, and a custom element connects asynchronously: `jx-ready` is
     // The menu saying its `popover` attribute is on and it may be shown.
+    // SAFETY: `menu.json`'s root definition carries `tagName: "jx-menu"`, so the mounted root is
+    // The kit's menu element, which reflects `open`, `x` and `y` and inherits `showPopover`.
     menu = mounted.root as MenuElement;
     menu.addEventListener("toggle", (event) => {
-      if ((event as { newState?: string }).newState === "closed") {
+      if (event.newState === "closed") {
         finish();
       }
     });
@@ -299,7 +306,7 @@ export function openMenu(options: OpenMenuOptions): MenuHandle {
         menu!.addEventListener("jx-ready", () => resolve(), { once: true });
       });
     }
-    if (controller.signal.aborted) {
+    if (aborted()) {
       return;
     }
     const source =
@@ -361,6 +368,23 @@ export function openMenu(options: OpenMenuOptions): MenuHandle {
   return handle;
 }
 
+/**
+ * Give the keyboard back to the opener BEFORE a chosen row runs, while the menu still holds it.
+ *
+ * A row that opens a modal dialog (Open Project Settings, a confirmation) calls `showModal()` from
+ * inside its run, and the platform records whatever is focused at that moment as the element to
+ * restore when the dialog closes. Left alone that is the menu ROW, which is gone by the time the
+ * dialog closes, so Escape dropped focus on `<body>` instead of the gear that opened the menu. The
+ * opener is where focus goes when the menu closes anyway ({@link restoreFocus}); doing it first
+ * only makes it the element the dialog remembers. Only when the menu holds focus, for the reason
+ * `restoreFocus` gives.
+ */
+function handBackKeyboard(menu: MenuElement | null, opener: HTMLElement | null): void {
+  if (menu?.contains(document.activeElement) && opener?.isConnected && opener !== document.body) {
+    opener.focus({ preventScroll: true });
+  }
+}
+
 /**
  * Hand the keyboard back to the opener, only when the menu still held it: an outside CLICK has
  * already moved focus somewhere the author chose, and yanking it back would fight them. In a

package/src/surfaces/navigator-dock.ts

@@ -16,14 +16,15 @@
  * @docs studio/interface
  */
 
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import navigatorDockDoc from "./navigator-dock.json";
-import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+import type { JsonObject, JxElement } from "@jxsuite/schema/types";
 import type { JxScope } from "@jxsuite/runtime/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("navigator-dock", navigatorDockDoc as unknown as JxDocument);
+registerSurface("navigator-dock", navigatorDockDoc);
 
 /** The panel showing, as the document draws it. */
 export interface NavigatorPanelView {
@@ -65,19 +66,17 @@ export interface NavigatorDockHandle {
   dispose: () => void;
 }
 
-interface NavigatorDockScope extends Record<string, unknown>, NavigatorDockValues {}
-
 /** The `part` a node was declared with, or the empty string. */
 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 : "";
 }
 
 /** The `$map` item a node was rendered inside, if it was rendered inside one. */
-function mapItem(state: JxScope | undefined): Record<string, unknown> | null {
-  const map = state?.["$map"] as { item?: unknown } | undefined;
-  const item = map?.item;
-  return item !== null && typeof item === "object" ? (item as Record<string, unknown>) : null;
+function mapItem(state: JxScope | undefined): JsonObject | null {
+  const map = state?.["$map"];
+  const item = isJsonObject(map) ? map["item"] : undefined;
+  return isJsonObject(item) ? item : null;
 }
 
 /**
@@ -91,7 +90,7 @@ export function mountNavigatorDock(
   values: NavigatorDockValues,
   options: NavigatorDockOptions,
 ): NavigatorDockHandle {
-  const scope = reactive<NavigatorDockScope>({ panels: values.panels }) as NavigatorDockScope;
+  const scope: NavigatorDockValues = reactive<NavigatorDockValues>({ panels: values.panels });
 
   container.textContent = "";
   // @ts-expect-error -- _$litPart$ is lit's private render-part marker, not in the DOM types
@@ -105,7 +104,7 @@ export function mountNavigatorDock(
         return;
       }
       const key = mapItem(state)?.["key"];
-      if (typeof key === "string") {
+      if (isString(key)) {
         options.onContent(key, element);
       }
     },

package/src/surfaces/new-project.ts

@@ -31,22 +31,17 @@
  * @docs studio/projects/create
  */
 
+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 newProjectDoc from "./new-project.json";
-import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+import type { SurfaceHandle, SurfaceOption } from "../ui/surface";
+import type { JxElement } from "@jxsuite/schema/types";
 
-registerSurface("new-project", newProjectDoc as unknown as JxDocument);
-
-/** One row of a kit `jx-select`, and of the tab strip: a value and what it reads. */
-export interface NewProjectRow {
-  value: string;
-  label: string;
-}
+registerSurface("new-project", newProjectDoc);
 
 /** One card in the starter gallery — including the one that is not a starter. */
 export interface NewProjectCard {
@@ -80,7 +75,7 @@ export interface NewProjectView {
   showTabs: boolean;
   /** The chosen tab's value, and the strip's rows. */
   tab: string;
-  tabs: NewProjectRow[];
+  tabs: SurfaceOption[];
   /** Which body to draw. */
   body: NewProjectBody;
   /** The sentence above a closed AI gate: the two tabs ask for the same thing differently. */
@@ -110,10 +105,10 @@ export interface NewProjectView {
   browsing: boolean;
   browseLabel: string;
   owner: string;
-  owners: NewProjectRow[];
+  owners: SurfaceOption[];
   /** `"private"` or `"public"` — a value rather than a flag, because a select holds one. */
   visibility: string;
-  visibilities: NewProjectRow[];
+  visibilities: SurfaceOption[];
   /** The owner already has a repository of this name. Empty says nothing. */
   repoTaken: string;
   /** `Creates` or `Repository`, and the destination itself. */
@@ -127,12 +122,12 @@ export interface NewProjectView {
   maxDepth: string;
   maxPages: string;
   breakpointMode: string;
-  breakpointModes: NewProjectRow[];
+  breakpointModes: SurfaceOption[];
   breakpointCount: string;
   maxBreakpoints: string;
   breakpointWidths: string;
   breakpointRounding: string;
-  roundings: NewProjectRow[];
+  roundings: SurfaceOption[];
   /** What the chosen mode says will happen. */
   breakpointHint: string;
   aiNaming: boolean;
@@ -233,8 +228,7 @@ interface NewProjectFlags {
   hasInstallUrl: boolean;
 }
 
-interface NewProjectScope
-  extends Record<string, unknown>, NewProjectView, NewProjectFlags, NewProjectActions {}
+interface NewProjectScope extends NewProjectView, NewProjectFlags, NewProjectActions {}
 
 /** The view plus the flags the document renders from. */
 function derive(view: NewProjectView): NewProjectView & NewProjectFlags {
@@ -260,8 +254,8 @@ function derive(view: NewProjectView): NewProjectView & NewProjectFlags {
 
 /** A node's authored `part`, which is how an island announces which one it is. */
 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 : "";
 }
 
 /**
@@ -294,6 +288,10 @@ export function openNewProjectSurface(options: NewProjectSurfaceOptions): NewPro
     closed = true;
     options.actions.closed();
   };
+  /* 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;
 
   /** The island boxes the document has announced, by part. Replaced as the bodies come and go. */
   const boxes = new Map<string, HTMLElement>();
@@ -325,14 +323,14 @@ export function openNewProjectSurface(options: NewProjectSurfaceOptions): NewPro
     }
   };
 
-  const scope = reactive({
+  const scope: NewProjectScope = reactive<NewProjectScope>({
     ...derive(options.view),
     ...options.actions,
     browse: () => {
       options.actions.browse();
     },
     closed: finish,
-  }) as NewProjectScope;
+  });
 
   let mounted: SurfaceHandle | null = null;
   const ready = mountSurface("new-project", scope, slot, {
@@ -345,13 +343,16 @@ export function openNewProjectSurface(options: NewProjectSurfaceOptions): NewPro
     },
   }).then(async (surface) => {
     mounted = surface;
+    /* SAFETY: `new-project.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 +376,7 @@ export function openNewProjectSurface(options: NewProjectSurfaceOptions): NewPro
       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();
@@ -394,8 +395,8 @@ export function openNewProjectSurface(options: NewProjectSurfaceOptions): NewPro
          move. Measurement and a focus move are the two imperative things a surface may still do
          (ui.md §2 rule 5). */
       requestAnimationFrame(() => {
-        element.querySelector('[part="dialog"]')?.scrollTo?.(0, 0);
-        element.querySelector<HTMLElement>('[part="name"] [part="input"]')?.focus?.();
+        element.querySelector('[part="dialog"]')?.scrollTo(0, 0);
+        element.querySelector<HTMLElement>('[part="name"] [part="input"]')?.focus();
       });
     },
     host: slot,