@jxsuite/studio 10.1.0 → 10.2.0

package/src/settings/settings-dialog.ts

@@ -1,192 +0,0 @@
-/// <reference lib="dom" />
-/**
- * Project Settings as a dialog (§17.1): the flow that opens it, mounts the settings editor into it,
- * and takes both down.
- *
- * Project Settings was a document in the pane, the `project.json` tab under a `settings` editor
- * mode. The five workspaces made that the wrong home: a tab belongs to exactly one workspace, and
- * configuration belongs to all of them, so a settings TAB either pulled the author out of the
- * workspace they were in or had to be special-cased in every one. A dialog is reachable from every
- * workspace and leaves the one underneath where it was. What made the old modal a problem (a form
- * that hid the canvas it was tuning) left with the design tokens, which are the Styles workspace's
- * now; every section still here writes `project.json` as it is edited, through the one chokepoint
- * (`tabs/project-config.ts`), so the dialog has nothing to confirm and its one answer is Close.
- *
- * **Which section shows is the registry's, not this module's.** `settings/section-registry.ts`
- * holds the requested and the displayed section and outlives the dialog, which is what makes the
- * dialog reopen where the author left it for the rest of the session.
- *
- * Modality, Escape and focus restoration are the platform's: a `jx-dialog` in the dialog layer,
- * opened with `showModal()`, which puts focus back on whatever opened it when it closes.
- *
- * **The frame and the editor are built once per session** and kept, closed, in the dialog layer. A
- * close suspends the editor (it stops following the section registry) and closes the platform's
- * dialog; an open resumes it, which redraws the current section, and shows the same dialog again.
- * Rebuilding both on every open was most of what opening Settings cost, and disposing them inside
- * the dialog's own `cancel` handler removed a subtree that still held focus from the top layer,
- * which the browser re-styled on the way out. {@link disposeSettingsDialog} is the teardown, and a
- * frame whose layer was replaced under it is rebuilt rather than shown.
- *
- * @docs studio/projects/settings
- */
-
-import { activeRegistry } from "../commands/active-registry";
-import { runActiveReported } from "../commands/run-reported";
-import { mountSettingsPane } from "../panels/settings-pane";
-import { openSettingsDialogSurface } from "../surfaces/settings-dialog";
-import { layerHost } from "../ui/layers";
-import type { SettingsPaneMount } from "../panels/settings-pane";
-import type { SettingsDialogHandle } from "../surfaces/settings-dialog";
-import type { InspectorTabId } from "../shell";
-import type { WorkspaceId } from "../workspace/workspace-ids";
-import type { StylesView } from "../style/project-styles";
-import type { PublishTab } from "../publish/publish-ids";
-
-/** The frame, built on the first open and kept across closes; `null` before then. */
-interface SettingsFrame {
-  dialog: SettingsDialogHandle;
-  /** The editor in the frame's body, once the body has been created. */
-  pane: SettingsPaneMount | null;
-}
-
-let _frame: SettingsFrame | null = null;
-
-/** Whether the dialog is asked to be up: true from an open until the close that ends it. */
-let _open = false;
-
-/** {@link _open}, read through a call so a check after an `await` is not narrowed to before it. */
-function isOpen(): boolean {
-  return _open;
-}
-
-/** Build the frame (it opens itself once mounted). */
-function buildFrame(): SettingsFrame {
-  const frame: SettingsFrame = {
-    dialog: openSettingsDialogSurface({
-      body: (host) => {
-        frame.pane = mountSettingsPane(host, {
-          openMoved: (workspace, inspector, view, publishTab) => {
-            void openMoved(workspace, inspector, view, publishTab);
-          },
-        });
-      },
-      /* Escape or Close: the platform closed the dialog, so the flow follows. `close()` is
-         idempotent, so the flow's own close running first is fine. */
-      closed: () => {
-        if (_frame === frame) {
-          closeSettingsDialog();
-        }
-      },
-      layer: layerHost("dialog"),
-    }),
-    pane: null,
-  };
-  return frame;
-}
-
-/**
- * Leave Settings for the workspace something moved to: the Moved footnote's buttons.
- *
- * Closed FIRST, so the workspace the author asked for is what they see and focus returns to the
- * frame rather than to a row that is going away. A refusal (the switch is gated on an open project)
- * is filed in Problems under this surface's name instead of being dropped.
- *
- * A row that names an Inspector tab ("Head and SEO defaults → Page tab") also shows the Inspector
- * on that tab, AFTER the switch, because entering a workspace applies its frame preset and would
- * otherwise put the dock back as the preset has it. The tab is a document-level view, so with no
- * document open there is no tab to show and asking would only file a refusal; the dock is still
- * opened, which is where the tab appears once one is.
- *
- * A row that names a Styles view ("Colors and fonts → Styles › Variables") runs `styles.open` with
- * that view instead, which is the same workspace switch followed by the view.
- *
- * @param {WorkspaceId} workspace
- * @param {InspectorTabId} [inspector]
- * @param {StylesView} [view]
- * @returns {Promise<void>} Settles once every command the row runs has settled
- */
-async function openMoved(
-  workspace: WorkspaceId,
-  inspector?: InspectorTabId,
-  view?: StylesView,
-  publishTab?: PublishTab,
-): Promise<void> {
-  closeSettingsDialog();
-  if (view !== undefined) {
-    await runActiveReported("styles.open", { view }, "Settings");
-    return;
-  }
-  // Hosting is a Publish sub-tab, not the workspace's first: the button says where it lands.
-  if (publishTab !== undefined) {
-    await runActiveReported("publish.open", { tab: publishTab }, "Settings");
-    return;
-  }
-  await runActiveReported("view.setWorkspace", { workspace }, "Settings");
-  if (inspector === undefined) {
-    return;
-  }
-  await runActiveReported("view.setRightPanel", { open: true }, "Settings");
-  if (activeRegistry()?.isEnabled("view.setRightTab") === true) {
-    await runActiveReported("view.setRightTab", { tab: inspector }, "Settings");
-  }
-}
-
-/**
- * Open Project Settings, or leave it up when it already is.
- *
- * Re-opening while it is up does not stack a second dialog: the section the caller asked for has
- * already been written to the registry, which redraws the editor that is showing.
- *
- * @returns {Promise<void>} Settles once the dialog is showing and the current section's row holds
- *   the keyboard
- */
-export async function openSettingsDialog(): Promise<void> {
-  if (_open && _frame) {
-    await _frame.dialog.ready;
-    return;
-  }
-  _open = true;
-  // A frame whose layer went away (a shell remount) is dead weight, not something to show.
-  if (_frame && !_frame.dialog.host.isConnected) {
-    disposeSettingsDialog();
-    _open = true;
-  }
-  let frame = _frame;
-  if (frame) {
-    frame.pane?.resume();
-    await frame.dialog.show();
-  } else {
-    frame = buildFrame();
-    _frame = frame;
-    await frame.dialog.ready;
-  }
-  /* Read after the wait, from the frame: the body is created while the dialog mounts, and a close
-     in between leaves the editor built but not to be focused. */
-  const mounted = frame.pane;
-  if (mounted === null || _frame !== frame || !isOpen()) {
-    return;
-  }
-  await mounted.ready;
-  if (_frame === frame && isOpen()) {
-    mounted.focusActive();
-  }
-}
-
-/** Close Project Settings if it is open. Idempotent. The frame stays built for the next open. */
-export function closeSettingsDialog(): void {
-  if (!_open) {
-    return;
-  }
-  _open = false;
-  _frame?.pane?.suspend();
-  _frame?.dialog.close();
-}
-
-/** Close Project Settings and take its frame and editor down. Idempotent. */
-export function disposeSettingsDialog(): void {
-  _open = false;
-  const frame = _frame;
-  _frame = null;
-  frame?.pane?.dispose();
-  frame?.dialog.dispose();
-}

package/src/surfaces/settings-dialog.json

@@ -1,51 +0,0 @@
-{
-  "$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

@@ -1,169 +0,0 @@
-/// <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);
-    },
-  };
-}