@jxsuite/studio 6.1.1 → 8.0.0

package/src/surfaces/settings-dialog.ts

@@ -0,0 +1,169 @@
+/// <reference lib="dom" />
+/**
+ * The Project Settings dialog, as a mounted document.
+ *
+ * A `jx-dialog` in the dialog layer whose body is an island: `settings-dialog.json` draws the slot,
+ * and the flow (`settings/settings-dialog.ts`) mounts the settings editor's columns into it through
+ * the `onNodeCreated` seam (`studio-ui-guidelines.md` §9.4). The dialog is only the frame and the
+ * one answer, Close.
+ *
+ * **Mounted once, shown many times.** Every open used to mount this document and the whole editor
+ * into it, and every close disposed both while the dialog was still on the top layer, which made
+ * each close re-style the subtree it was removing. Now a close is the platform's `close()` and the
+ * document stays in the dialog layer, closed (so `display: none`, and inert), until the flow
+ * disposes it; the next open is one `showModal()`.
+ *
+ * **Await the ELEMENT, not just the mount.** `mountSurface` resolving means the document rendered;
+ * a `jx-dialog`'s own template is one `connectedCallback` later, and `showModal` in between finds
+ * no `<dialog>` to open. `whenReady` is shared with `surfaces/dialog.ts`.
+ *
+ * @docs studio/projects/settings
+ */
+
+import { isString } from "@jxsuite/schema/guards";
+import { close, showModal } from "@jxsuite/ui/behaviors/dialog";
+import { reactive } from "../reactivity";
+import { overlayRegion, REGION_ATTR } from "../ui/regions";
+import { mountSurface, registerSurface } from "../ui/surface";
+import { whenReady } from "./dialog";
+import settingsDialogDoc from "./settings-dialog.json";
+import type { JxElement } from "@jxsuite/schema/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("settings-dialog", settingsDialogDoc);
+
+/** The dialog's region: `overlay.dialog:settings`. Section regions are named under it. */
+export const SETTINGS_DIALOG_REGION = overlayRegion("dialog", "settings");
+
+export interface SettingsDialogOptions {
+  /** The dialog layer host, handed in so this module never reaches back into `layers.ts`. */
+  layer: HTMLElement;
+  /** The body slot was created: where the flow mounts the settings editor. Called once. */
+  body: (host: HTMLElement) => void;
+  /** The dialog closed, for any reason: once per time it was shown. */
+  closed: () => void;
+}
+
+/**
+ * The settings frame, mounted once and shown as often as it is asked for.
+ *
+ * Closing it closes the platform's `<dialog>` and leaves the document standing in the dialog layer,
+ * so the next open is one `showModal()` on a frame whose editor is already built, not a mount of
+ * the whole editor. Only {@link SettingsDialogHandle.dispose} takes it down.
+ */
+export interface SettingsDialogHandle {
+  /** 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, if still asked). */
+  ready: Promise<HTMLElement>;
+  /** Show it again after a close. Resolves once it is showing. */
+  show: () => Promise<HTMLElement>;
+  /** Close the dialog (the platform restores focus); the document stays mounted. Idempotent. */
+  close: () => void;
+  /** Close it and take the document and its slot down for good. Idempotent. */
+  dispose: () => void;
+}
+
+interface SettingsDialogScope {
+  closed: () => 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 = isString(def) ? undefined : def.attributes?.["part"];
+  return isString(part) ? part : "";
+}
+
+/**
+ * Mount the dialog and open it. The handle's `ready` resolves once it is showing.
+ *
+ * @param {SettingsDialogOptions} options
+ * @returns {SettingsDialogHandle}
+ */
+export function openSettingsDialogSurface(options: SettingsDialogOptions): SettingsDialogHandle {
+  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
+     changes paint order rather than inheritance, so a modal `<dialog>` in a slot that skipped this
+     is painted above everything and hit-tests to nothing. */
+  slot.style.pointerEvents = "auto";
+  options.layer.append(slot);
+
+  /** Whether the dialog is asked to be showing: true from each open until its close. */
+  let wanted = true;
+  let disposed = false;
+  /** Say this showing is over, once: the platform's own `close` and `close()` can each be first. */
+  const finish = (): void => {
+    if (!wanted) {
+      return;
+    }
+    wanted = false;
+    options.closed();
+  };
+
+  const scope = reactive<SettingsDialogScope>({ closed: finish });
+
+  let mounted: SurfaceHandle | null = null;
+  /** Open the platform's dialog, if it is still asked for. Read through a call after each await. */
+  const open = (element: HTMLElement): HTMLElement => {
+    if (!disposed && wanted) {
+      showModal(element);
+    }
+    return element;
+  };
+  const ready = mountSurface("settings-dialog", scope, slot, {
+    onNodeCreated: (element, _path, def) => {
+      if (!disposed && element instanceof HTMLElement && partOf(def) === "pane-slot") {
+        options.body(element);
+      }
+    },
+  }).then(async (surface) => {
+    /* SAFETY: `settings-dialog.json`'s root definition is a `jx-dialog` element, so the runtime
+       mounts an HTMLElement. */
+    const element = surface.root as HTMLElement;
+    if (disposed) {
+      surface.dispose();
+      return element;
+    }
+    mounted = surface;
+    await whenReady(element);
+    /* The region goes on the platform's own `<dialog>`, the one element here that HAS a box:
+       `jx-dialog` is `display: contents`, and the slot wraps a dialog the top layer takes out of
+       flow, so both measure 0×0, and a region whose box is empty is refused by the screenshot
+       pipeline. The kit's own behaviour sidecar finds that node by exactly this selector. */
+    const box = element.querySelector<HTMLElement>('dialog[part="dialog"]') ?? element;
+    box.setAttribute(REGION_ATTR, SETTINGS_DIALOG_REGION);
+    return open(element);
+  });
+
+  const hide = (): void => {
+    const element = mounted?.root;
+    if (element instanceof HTMLElement) {
+      // The platform's close, so focus goes back where it came from before anything else moves.
+      close(element);
+    }
+    finish();
+  };
+
+  return {
+    close: hide,
+    dispose() {
+      if (disposed) {
+        return;
+      }
+      hide();
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+      slot.remove();
+    },
+    host: slot,
+    ready,
+    show() {
+      if (!disposed) {
+        wanted = true;
+      }
+      return ready.then(open);
+    },
+  };
+}

package/src/surfaces/settings-extensions.ts

@@ -26,10 +26,9 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import extensionsDoc from "./settings-extensions.json";
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("settings-extensions", extensionsDoc as unknown as JxDocument);
+registerSurface("settings-extensions", extensionsDoc);
 
 /** One `project.json` key an extension owns, as the chip repeater reads it. */
 export interface ExtensionSectionView {
@@ -117,7 +116,7 @@ export interface ExtensionsSurfaceHandle {
  * value already in the view, and a view that had to keep them in step would be a second place to
  * get it wrong.
  */
-interface ExtensionsScope extends Record<string, unknown>, ExtensionsView, ExtensionsActions {
+interface ExtensionsScope extends ExtensionsView, ExtensionsActions {
   /** Whether to draw the groups or the sentence that says what this region is for. */
   listState: "empty" | "groups";
   hasError: boolean;
@@ -147,14 +146,14 @@ export function mountExtensionsSurface(
   view: ExtensionsView,
   actions: ExtensionsActions,
 ): ExtensionsSurfaceHandle {
-  const scope = reactive<ExtensionsScope>({
+  const scope: ExtensionsScope = reactive<ExtensionsScope>({
     error: "",
     groups: [],
     hasError: false,
     listState: "empty",
     remove: actions.remove,
     toggle: actions.toggle,
-  }) as ExtensionsScope;
+  });
   project(scope, view);
 
   container.replaceChildren();
@@ -182,7 +181,7 @@ export function mountExtensionsSurface(
       !disposed &&
       (mounted === null
         ? container.childNodes.length === 0
-        : (mounted.root as Node).parentNode === container),
+        : mounted.root.parentNode === container),
     dispose() {
       disposed = true;
       mounted?.dispose();

package/src/surfaces/settings-head.ts

@@ -18,6 +18,7 @@
  * @docs studio/projects/settings
  */
 
+import { isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { projectState } from "../store";
 import { updateSiteConfig } from "../site-context";
@@ -29,24 +30,15 @@ import {
   isGoogleFontEntry,
 } from "../utils/google-fonts";
 import { mountSurface, registerSurface } from "../ui/surface";
+import { HEAD_EDIT_DEBOUNCE } from "../ui/timing";
 import headDoc from "./settings-head.json";
-import type { JxDocument, JxHeadEntry, ProjectConfig } from "@jxsuite/schema/types";
-import type { SurfaceHandle } from "../ui/surface";
+import type { JsonValue, JxHeadEntry, ProjectConfig } from "@jxsuite/schema/types";
+import type { SurfaceHandle, TaggedLabel } from "../ui/surface";
 
-registerSurface("settings-head", headDoc as unknown as JxDocument);
-
-/**
- * How long a keystroke waits before it is written.
- *
- * Every field commit is a `project.json` write, and the two body fields commit on `input` — one
- * write per keystroke without this. The lit editor debounced per ENTRY, with one timer shared by
- * that entry's fields, so editing `rel` and then `href` inside the window cancelled the first write
- * outright; the timers are per field here, which is why each edit lands.
- */
-const EDIT_DEBOUNCE_MS = 300;
+registerSurface("settings-head", headDoc);
 
 /** One `$head` entry as the document draws it: which fields, and what is in them. */
-interface HeadRow extends Record<string, unknown> {
+interface HeadRow {
   id: string;
   /** The tag name, drawn as `<link>` and named in the delete button. */
   tag: string;
@@ -64,18 +56,12 @@ interface HeadRow extends Record<string, unknown> {
 }
 
 /** One Google Fonts stylesheet link, by the family it loads. */
-interface FontRow extends Record<string, unknown> {
+interface FontRow {
   id: string;
   family: string;
 }
 
-/** One of the four tags the section can add, and the button that adds it. */
-interface AddTag extends Record<string, unknown> {
-  tag: string;
-  label: string;
-}
-
-interface HeadScope extends Record<string, unknown> {
+interface HeadScope {
   rows: HeadRow[];
   fonts: FontRow[];
   /**
@@ -85,7 +71,8 @@ interface HeadScope extends Record<string, unknown> {
   fontsState: "empty" | "listed";
   /** What is in the family field. The document reads it back, so clearing it is an assignment. */
   fontDraft: string;
-  tags: AddTag[];
+  /** The four tags the section can add, each with the words on the button that adds it. */
+  tags: TaggedLabel[];
   add: (tag: string) => void;
   remove: (id: string) => void;
   edit: (id: string, key: string, value: string) => void;
@@ -94,7 +81,7 @@ interface HeadScope extends Record<string, unknown> {
   removeFont: (id: string) => void;
 }
 
-const ADD_TAGS: AddTag[] = [
+const ADD_TAGS: TaggedLabel[] = [
   { label: "+ Link", tag: "link" },
   { label: "+ Meta", tag: "meta" },
   { label: "+ Script", tag: "script" },
@@ -137,7 +124,7 @@ let _entries: JxHeadEntry[] = [];
  * between would answer "no entries" and lose the tag that was just added.
  */
 function entries(): JxHeadEntry[] {
-  const config = (projectState?.projectConfig ?? null) as ProjectConfig | null;
+  const config = projectState?.projectConfig ?? null;
   if (config !== _config) {
     _config = config;
     _entries = [];
@@ -150,7 +137,7 @@ function entries(): JxHeadEntry[] {
   }
   const declared = config?.$head;
   if (Array.isArray(declared)) {
-    _entries = declared as JxHeadEntry[];
+    _entries = declared;
   }
   return _entries;
 }
@@ -161,8 +148,8 @@ function entryFor(id: string): JxHeadEntry | undefined {
 }
 
 /** A `$head` attribute as a field's text: anything that is not a string has none to show. */
-function text(value: unknown): string {
-  return typeof value === "string" ? value : "";
+function text(value: JsonValue | undefined): string {
+  return isString(value) ? value : "";
 }
 
 // ─── The projection ───────────────────────────────────────────────────────────
@@ -171,19 +158,21 @@ function text(value: unknown): string {
 function row(entry: JxHeadEntry): HeadRow {
   const attributes = entry.attributes ?? {};
   const src = text(attributes["src"]);
-  const tag = String(entry.tagName ?? "");
-  const kinds: Record<string, HeadRow["kind"]> = {
-    link: "link",
-    meta: "meta",
-    script: src === "" ? "script-inline" : "script",
-    style: "style",
-  };
+  /* `project.json` is read off disk unvalidated, so an entry can arrive without a `tagName`; like
+     an attribute, a tag that is not a string has none to show. */
+  const tag = text(entry.tagName);
+  const kinds = new Map<string, HeadRow["kind"]>([
+    ["link", "link"],
+    ["meta", "meta"],
+    ["script", src === "" ? "script-inline" : "script"],
+    ["style", "style"],
+  ]);
   return {
     body: text(entry.textContent),
     content: text(attributes["content"]),
     href: text(attributes["href"]),
     id: idOf(entry),
-    kind: kinds[tag] ?? "none",
+    kind: kinds.get(tag) ?? "none",
     name: text(attributes["name"]),
     rel: text(attributes["rel"]),
     src,
@@ -212,7 +201,12 @@ function save(): void {
   void updateSiteConfig({ $head: entries() });
 }
 
-/** Field edits waiting out {@link EDIT_DEBOUNCE_MS}, one per field. */
+/**
+ * Field edits waiting out {@link HEAD_EDIT_DEBOUNCE}, one per field. The two body fields commit on
+ * `input`, so without the wait every keystroke would be a `project.json` write; the lit editor
+ * shared one timer per ENTRY, so editing `rel` and then `href` inside the window cancelled the
+ * first write outright.
+ */
 const _pending = new Map<string, { commit: () => void; timer: ReturnType<typeof setTimeout> }>();
 
 /**
@@ -302,7 +296,7 @@ function state(): HeadScope {
         _pending.delete(token);
         write(id, key, value);
       };
-      _pending.set(token, { commit, timer: setTimeout(commit, EDIT_DEBOUNCE_MS) });
+      _pending.set(token, { commit, timer: setTimeout(commit, HEAD_EDIT_DEBOUNCE) });
     },
     fonts: [],
     fontDraft: "",
@@ -339,7 +333,7 @@ function state(): HeadScope {
     },
     rows: [],
     tags: ADD_TAGS,
-  }) as HeadScope;
+  });
   return _scope;
 }
 

package/src/surfaces/settings-locales.ts

@@ -24,28 +24,16 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import localesDoc from "./settings-locales.json";
-import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle, SurfaceOption, TaggedLabel } from "../ui/surface";
 
-registerSurface("settings-locales", localesDoc as unknown as JxDocument);
-
-/** One declared language: the tag as the author wrote it, and the name that language calls itself. */
-export interface LocaleRow {
-  tag: string;
-  label: string;
-}
-
-/** One row of a picker. */
-export interface LocaleChoice {
-  value: string;
-  label: string;
-}
+registerSurface("settings-locales", localesDoc);
 
 /** What the section shows — the flow's projection of `project.json` and of the form beside it. */
 export interface LocalesView {
-  locales: LocaleRow[];
-  localeOptions: LocaleChoice[];
-  routings: LocaleChoice[];
+  /** Each declared language: the tag as the author wrote it, and the name it calls itself. */
+  locales: TaggedLabel[];
+  localeOptions: SurfaceOption[];
+  routings: SurfaceOption[];
   defaultLocale: string;
   routing: string;
   /** The tag being typed, kept so an outside redraw does not take it away. */
@@ -80,7 +68,7 @@ interface LocalesFlags {
   hasError: boolean;
 }
 
-interface LocalesScope extends Record<string, unknown>, LocalesView, LocalesActions, LocalesFlags {}
+interface LocalesScope extends LocalesView, LocalesActions, LocalesFlags {}
 
 interface Mounted {
   scope: LocalesScope;
@@ -124,7 +112,7 @@ export function renderLocalesSurface(
   }
   existing?.handle?.dispose();
   host.textContent = "";
-  const scope = reactive({ ...derive(view), ...actions }) as LocalesScope;
+  const scope: LocalesScope = reactive<LocalesScope>({ ...derive(view), ...actions });
   const record: Mounted = { handle: null, scope };
   mounts.set(host, record);
   /* No race to arbitrate: a redraw arriving while this is in flight takes the branch above — a

package/src/surfaces/settings-overview.json

@@ -278,7 +278,7 @@
                   "tagName": "img",
                   "attributes": {
                     "part": "favicon",
-                    "src": "${state.favicon}",
+                    "src": "${state.faviconSrc}",
                     "alt": "Current favicon"
                   }
                 },
@@ -372,7 +372,7 @@
       "$props": {
         "span": true,
         "label": "Global Styles",
-        "description": "Design tokens and the default element styles that apply across every page. Opens Project Styles over this same document."
+        "description": "The CSS variables and the default element styles that apply across every page live in the Styles workspace, which edits this same file."
       },
       "attributes": {
         "part": "row",
@@ -411,7 +411,7 @@
               "children": [
                 {
                   "tagName": "span",
-                  "textContent": "Edit Global Styles"
+                  "textContent": "Go to Styles"
                 }
               ]
             }

package/src/surfaces/settings-overview.ts

@@ -24,10 +24,9 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import overviewDoc from "./settings-overview.json";
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("settings-overview", overviewDoc as unknown as JxDocument);
+registerSurface("settings-overview", overviewDoc);
 
 /** Which control a failure belongs under. `"section"` puts it at the top of the section. */
 export type OverviewErrorField = "name" | "description" | "url" | "favicon" | "section";
@@ -43,9 +42,11 @@ export interface OverviewValues {
   name: string;
   description: string;
   url: string;
-  /** The configured favicon path, or `""` for none. */
+  /** The configured favicon path, as `$head` names it, or `""` for none. */
   favicon: string;
-  /** The `styles.open` record's own title, which is the button's tooltip. */
+  /** The src the parent realm loads to preview {@link favicon}: the authored value, resolved. */
+  faviconSrc: string;
+  /** The `workspace.focus.styles` record's own title (Go to Styles), the button's tooltip. */
   stylesTitle: string;
   stylesDisabled: boolean;
   /** The last failure, or `null` when the last write succeeded. */
@@ -74,7 +75,7 @@ export interface OverviewSurfaceHandle {
  * The scope the document reads: one field per binding, because `$switch` is the only conditional a
  * document has and `error.field === "name"` is not a value it can switch on.
  */
-interface OverviewScope extends Record<string, unknown> {
+interface OverviewScope {
   nameValue: string;
   nameError: string;
   nameInvalid: boolean;
@@ -85,6 +86,7 @@ interface OverviewScope extends Record<string, unknown> {
   urlError: string;
   urlInvalid: boolean;
   favicon: string;
+  faviconSrc: string;
   hasFavicon: boolean;
   faviconError: string;
   hasFaviconError: boolean;
@@ -125,6 +127,9 @@ function project(scope: OverviewScope, patch: Partial<OverviewValues>): void {
     scope.favicon = patch.favicon;
     scope.hasFavicon = patch.favicon !== "";
   }
+  if (patch.faviconSrc !== undefined) {
+    scope.faviconSrc = patch.faviconSrc;
+  }
   if (patch.stylesTitle !== undefined) {
     scope.stylesTitle = patch.stylesTitle;
   }
@@ -157,12 +162,13 @@ export function mountOverviewSurface(
   values: OverviewValues,
   actions: OverviewActions,
 ): OverviewSurfaceHandle {
-  const scope = reactive<OverviewScope>({
+  const scope: OverviewScope = reactive<OverviewScope>({
     descriptionError: "",
     descriptionInvalid: false,
     descriptionValue: "",
     favicon: "",
     faviconError: "",
+    faviconSrc: "",
     hasFavicon: false,
     hasFaviconError: false,
     hasSectionError: false,
@@ -180,7 +186,7 @@ export function mountOverviewSurface(
     urlError: "",
     urlInvalid: false,
     urlValue: "",
-  }) as OverviewScope;
+  });
   project(scope, values);
 
   container.replaceChildren();
@@ -208,7 +214,7 @@ export function mountOverviewSurface(
       !disposed &&
       (mounted === null
         ? container.childNodes.length === 0
-        : (mounted.root as Node).parentNode === container),
+        : mounted.root.parentNode === container),
     dispose() {
       disposed = true;
       mounted?.dispose();

package/src/surfaces/settings-packages.ts

@@ -32,9 +32,8 @@ import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import packagesDoc from "./settings-packages.json";
 import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
 
-registerSurface("settings-packages", packagesDoc as unknown as JxDocument);
+registerSurface("settings-packages", packagesDoc);
 
 /** One dependency, as the table draws it. Every field is already a string the row can print. */
 export interface PackageRow {
@@ -79,7 +78,7 @@ export interface PackagesActions {
 }
 
 /** One row plus the flag its buttons switch on. */
-interface RowScope extends Record<string, unknown>, PackageRow {
+interface RowScope extends PackageRow {
   /** Whether to draw the update button — `upgrade` said as something a `$switch` can read. */
   canUpdate: boolean;
 }
@@ -96,11 +95,13 @@ interface PackagesFlags {
   hasUpdates: boolean;
 }
 
-interface PackagesScope
-  extends Record<string, unknown>, Omit<PackagesView, "rows">, PackagesActions, PackagesFlags {
+/** Everything {@link derive} computes from a view: the scope minus the reader's actions. */
+interface PackagesDerived extends Omit<PackagesView, "rows">, PackagesFlags {
   rows: RowScope[];
 }
 
+interface PackagesScope extends PackagesDerived, PackagesActions {}
+
 interface Mounted {
   scope: PackagesScope;
   /** `null` while the mount is still in flight — which is a standing surface, not a missing one. */
@@ -110,7 +111,7 @@ interface Mounted {
 const mounts = new WeakMap<HTMLElement, Mounted>();
 
 /** The view plus the flags the document switches on. */
-function derive(view: PackagesView): Omit<PackagesScope, keyof PackagesActions> {
+function derive(view: PackagesView): PackagesDerived {
   const rows = view.rows.map((row): RowScope => ({ ...row, canUpdate: row.upgrade !== "" }));
   return {
     addName: view.addName,
@@ -145,7 +146,7 @@ export function renderPackagesSurface(
   }
   existing?.handle?.dispose();
   host.textContent = "";
-  const scope = reactive({ ...derive(view), ...actions }) as PackagesScope;
+  const scope: PackagesScope = reactive<PackagesScope>({ ...derive(view), ...actions });
   const record: Mounted = { handle: null, scope };
   mounts.set(host, record);
   /* No race to arbitrate: a redraw arriving while this is in flight takes the branch above — a