@jxsuite/studio 6.1.2 → 8.0.0

package/src/surfaces/settings-deploy.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioSettingsDeploy",
-  "$description": "Project Settings › Deploy: where the site ships, and what it is built with. One row over `build.adapter`, and the sentence a failed write leaves behind. The adapter (`surfaces/settings-deploy.ts`) hands in the chosen adapter, the enumeration it is chosen from and whatever the last write had to say; the document draws them and hands the change straight back. Nothing here reads `project.json` — a section that re-read the config while drawing would be a second opinion about a file one module already owns.",
+  "$description": "Publish › Hosting's build adapter (studio.md §22.8), which was Project Settings › Deploy: one row over `build.adapter`, and the sentence a failed write leaves behind. It draws no heading of its own: Hosting's \"How it is built\" section heads it, and a second title inside that card would name the same thing twice. The adapter (`surfaces/settings-deploy.ts`) hands in the chosen adapter, the enumeration it is chosen from and whatever the last write had to say; the document draws them and hands the change straight back. Nothing here reads `project.json`: a section that re-read the config while drawing would be a second opinion about a file one module already owns.",
   "tagName": "section",
   "attributes": {
     "part": "deploy"
@@ -11,12 +11,6 @@
     "display": "block",
     "fontFamily": "var(--jx-font-sans)",
     "color": "var(--fg)",
-    "& [part=\"title\"]": {
-      "margin": "0 0 16px",
-      "fontSize": "16px",
-      "fontWeight": "600",
-      "color": "var(--fg)"
-    },
     "& [part=\"section-error\"]": {
       "$description": "A write that failed, said under the section title rather than pinned to the picker: settings save on change, so a silent rejection would read as \"my edit just vanished\", and what failed was the whole file rather than the value. Its size read `--spectrum-font-size-75` with a 12px fallback, which resolved only inside `<sp-theme>` — a document is mounted in the settings pane, where that name is not in scope and the fallback is all it would ever have taken — so the size is the kit's scale and the colour is the studio layer's. It is `section-error` rather than `error` because the adapter picker is a `jx-select`, which draws a permanent `[part=\"error\"]` of its own in this same light-DOM tree: a rule on that name would give the picker's own refusal sentence this 16px margin too.",
       "margin": "0 0 16px",
@@ -29,13 +23,6 @@
     }
   },
   "children": [
-    {
-      "tagName": "h3",
-      "attributes": {
-        "part": "title"
-      },
-      "textContent": "Deploy"
-    },
     {
       "tagName": "div",
       "attributes": {
@@ -67,7 +54,7 @@
       },
       "$props": {
         "span": true,
-        "label": "Platform Adapter",
+        "label": "Build adapter",
         "description": "What the site is built for. Static writes plain files; the others emit a server entry for that runtime."
       },
       "children": [

package/src/surfaces/settings-deploy.ts

@@ -13,7 +13,7 @@
  * the old adapter back — `live()` did this for the lit template, and a binding that never moved
  * would otherwise leave the picker claiming a platform the file does not name.
  *
- * @docs studio/projects/settings
+ * @docs studio/publish/other-hosts
  */
 
 import { reactive } from "../reactivity";

package/src/surfaces/settings-dialog.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioSettingsDialog",
+  "$description": "Project Settings (§17.1): a `jx-dialog` whose body is the settings editor's two columns, the grouped section list and the section body. The dialog owns modality, Escape and focus restoration, and its one footer answer is Close: every section writes as it is edited, so there is nothing to confirm or cancel. The body is an ISLAND: this document draws the slot and nothing in it, and `settings/settings-dialog.ts` mounts `settings-pane.json` there through `onNodeCreated` (studio-ui-guidelines.md §9.4).",
+  "tagName": "jx-dialog",
+  "$props": {
+    "headline": "Project settings",
+    "confirmLabel": "",
+    "cancelLabel": "Close",
+    "size": "xl"
+  },
+  "attributes": {
+    "part": "settings"
+  },
+  "oncancel": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/closed"
+        },
+        "value": []
+      }
+    ]
+  },
+  "onclose": {
+    "$prototype": "Function",
+    "body": [
+      {
+        "operator": "call",
+        "target": {
+          "$ref": "#/state/closed"
+        },
+        "value": []
+      }
+    ]
+  },
+  "children": [
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "pane-slot"
+      },
+      "style": {
+        "$description": "The editor's box is its own (`settings-pane.json`); the slot only gives it the dialog body's width.",
+        "minWidth": "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-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

@@ -42,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. */
@@ -84,6 +86,7 @@ interface OverviewScope {
   urlError: string;
   urlInvalid: boolean;
   favicon: string;
+  faviconSrc: string;
   hasFavicon: boolean;
   faviconError: string;
   hasFaviconError: boolean;
@@ -124,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;
   }
@@ -162,6 +168,7 @@ export function mountOverviewSurface(
     descriptionValue: "",
     favicon: "",
     faviconError: "",
+    faviconSrc: "",
     hasFavicon: false,
     hasFaviconError: false,
     hasSectionError: false,