@jxsuite/studio 4.0.0 → 5.0.0

package/src/panels/settings-pane.ts

@@ -8,6 +8,12 @@
  * frame (`overlay.dialog:settings` → `pane.primary`) without one manifest STEP changing, which is
  * §13.7's proof that the command boundary was drawn in the right place.
  *
+ * **This file is the FLOW; the markup is a document.** `surfaces/settings-pane.json` owns the two
+ * columns, the list's ARIA and keyboard, and every value in their style;
+ * `surfaces/settings-pane.ts` mounts one per pane (studio-ui-guidelines.md §6, §9.3). What stays
+ * here is the part that is a decision: which sections there are, which one is current, and which
+ * renderer gets the body.
+ *
  * Mounting follows `grid/grid-panel.ts`: `canvas/canvas-render.ts` calls {@link renderSettingsPane}
  * when the tab enters this mode, and this module owns its reactivity from there — a subscription to
  * the section registry and to the chosen section, so an extension's section appearing a tick later
@@ -25,9 +31,6 @@
  * @docs studio/projects/settings
  */
 
-import { html, render as litRender } from "lit-html";
-import { classMap } from "lit-html/directives/class-map.js";
-import { ref } from "lit-html/directives/ref.js";
 import {
   onSettingsDocumentChanged,
   settingsSection,
@@ -35,8 +38,13 @@ import {
   setSettingsSection,
   sortedSettingsSections,
 } from "../settings/section-registry";
+import { mountSettingsPaneSurface } from "../surfaces/settings-pane";
+import type { SettingsPaneHandle } from "../surfaces/settings-pane";
 import type { CanvasSurface } from "../canvas/canvas-surface";
 
+/** What the body says when the section that is current is registered by nobody. */
+const NO_SECTIONS = "No settings sections.";
+
 /**
  * One mounted editor per PANE.
  *
@@ -47,61 +55,40 @@ import type { CanvasSurface } from "../canvas/canvas-surface";
  */
 interface ActiveSettingsPane {
   host: HTMLElement;
-  /** The section body container, handed to whichever section renderer is current. */
+  /** The mounted chrome. */
+  surface: SettingsPaneHandle;
+  /**
+   * The document's `[part="body"]` island, as {@link draw} last read it off the surface.
+   *
+   * Held here as well so a CHANGE of element can reset {@link ActiveSettingsPane.rendered}: the body
+   * is what a section was drawn into, and a body that has been replaced holds nothing. A mount is
+   * asynchronous, so it is null for the first tick and `draw` returns at that —
+   * {@link renderSettingsPane} redraws once the mount settles.
+   */
   body: HTMLElement | null;
+  /**
+   * The element the ACTIVE section was drawn into, inside {@link ActiveSettingsPane.body}.
+   *
+   * Sections no longer share one container, and they cannot: a converted section mounts a document
+   * and clears what it is given, which destroys lit's `_$litPart$` markers — so the next lit
+   * section rendering into that same element throws on a part whose markers have left the document.
+   * It fails the other way too: lit renders BESIDE foreign nodes rather than replacing them, so a
+   * lit section drawn after a document one left both on screen at once. A fresh host per section is
+   * what makes the two kinds coexist, which is the whole of §9.3's surface-level rule applied to
+   * one dispatcher.
+   */
+  sectionHost: HTMLElement | null;
   /** The section the body currently holds, so an idle re-render does not rebuild it. */
   rendered: string | null;
   /** Unsubscribe from the document's change notifications. */
   off: (() => void) | null;
-  /**
-   * The body's `ref` callback, allocated ONCE per record.
-   *
-   * Lit re-invokes a `ref` whose callback IDENTITY changed — the old one with `undefined`, the new
-   * one with the element. Built inline in the template it was a fresh closure every render, so
-   * every render ran `panel.body = null; panel.rendered = null` and then re-bound: `rendered` was
-   * null again by the time the guard in {@link draw} read it, on every single pass. The guard could
-   * not fire and `force` decided nothing.
-   *
-   * What that did NOT cost, despite appearances: the mid-keystroke rebuild. `canvas-render.ts`
-   * returns at its own fast path (`canvasMode === "settings" && settingsPaneMounted(surface) &&
-   * !modeChanged`) before it ever calls back in, and on a real mode change it detaches this record
-   * first — so `draw(paneId, false)` over a SURVIVING record has no caller in the app. That fast
-   * path is what keeps an open inline form alive today; this guard is the second line, and it was
-   * vacuous. Do not read the two as redundant and delete either.
-   *
-   * Per RECORD, not per pane id: a same-host remount after `detachSettingsPane` needs the identity
-   * to change so lit re-binds the element onto the new record.
-   */
-  bindBody: (el: Element | undefined) => void;
 }
 
 const _active = new Map<string, ActiveSettingsPane>();
 
-/**
- * Build one record's body binder.
- *
- * The guard is an IDENTITY test, not a presence test, and that distinction is the whole of it. A
- * binder outlives its record — lit calls the previous one with `undefined` whenever the callback
- * changes, and again when the part disconnects — so by the time it runs, `_active` may hold no
- * record at all, or a DIFFERENT one for the same pane. Writing into whatever `_active` happens to
- * return would be worse than doing nothing: it would null the live record's `body`, and since a
- * stable callback over an unchanged element is never re-invoked, nothing would ever re-bind it —
- * `draw` would return at `!panel.body` forever, `force` included. A superseded binder therefore
- * touches nothing; its own record is detached and no one reads it.
- */
-function bodyBinder(paneId: string): (el: Element | undefined) => void {
-  const self = (el: Element | undefined) => {
-    const panel = _active.get(paneId);
-    if (panel?.bindBody !== self) {
-      return;
-    }
-    const next = (el as HTMLElement | undefined) ?? null;
-    if (next !== panel.body) {
-      panel.body = next;
-      panel.rendered = null;
-    }
-  };
-  return self;
+/** A section row's element id — minted from the key, so the panel can name the row that chose it. */
+function tabIdFor(key: string): string {
+  return `settings-nav-${key}`;
 }
 
 /**
@@ -114,17 +101,30 @@ function bodyBinder(paneId: string): (el: Element | undefined) => void {
  */
 export function renderSettingsPane(surface: CanvasSurface): void {
   const { paneId, wrap: host } = surface;
-  let panel = _active.get(paneId);
-  if (panel?.host !== host) {
+  if (_active.get(paneId)?.host !== host) {
     detachSettingsPane(paneId);
-    panel = {
-      bindBody: bodyBinder(paneId),
+    const record: ActiveSettingsPane = {
       body: null,
       host,
       off: onSettingsDocumentChanged(() => draw(paneId, true)),
       rendered: null,
+      sectionHost: null,
+      surface: mountSettingsPaneSurface(host, values(), {
+        selectSection: (key: string) => {
+          setSettingsSection(key);
+        },
+      }),
     };
-    _active.set(paneId, panel);
+    _active.set(paneId, record);
+    /* A mount is asynchronous and the island does not exist until it lands, so the `draw` below
+       returns at `!panel.body`. THIS is the pass that first reaches a section renderer — and it
+       only runs while this record is still the pane's, because a mode change can detach it while
+       the mount is in flight. */
+    void record.surface.ready.then(() => {
+      if (_active.get(paneId) === record) {
+        draw(paneId, true);
+      }
+    });
   }
   draw(paneId, false);
 }
@@ -136,6 +136,7 @@ export function detachSettingsPane(paneId: string): void {
     return;
   }
   panel.off?.();
+  panel.surface.dispose();
   _active.delete(paneId);
 }
 
@@ -149,8 +150,25 @@ export function settingsPaneMounted(surface: CanvasSurface): boolean {
   return _active.get(surface.paneId)?.host === surface.wrap;
 }
 
+/** Everything the document draws, decided here so the document decides nothing. */
+function values() {
+  const active = settingsDocumentSection();
+  return {
+    active,
+    activeTabId: tabIdFor(active),
+    empty: NO_SECTIONS,
+    hasSection: settingsSection(active) !== undefined,
+    navLabel: "Project Settings sections",
+    sections: sortedSettingsSections().map((section) => ({
+      key: section.key,
+      label: section.label,
+      tabId: tabIdFor(section.key),
+    })),
+  };
+}
+
 /**
- * Draw the nav, then the body.
+ * Update the nav, then the body.
  *
  * @param {boolean} force - Re-run the section renderer even when the section has not changed. True
  *   for a real state change (a nav click, a section registering, an entry being selected by
@@ -162,42 +180,40 @@ function draw(paneId: string, force: boolean): void {
     return;
   }
   const active = settingsDocumentSection();
-  const sections = sortedSettingsSections();
-
-  const tpl = html`
-    <div class="settings-doc">
-      <nav class="settings-doc-nav" aria-label="Project Settings sections">
-        ${sections.map(
-          (section) => html`
-            <button
-              class=${classMap({
-                active: active === section.key,
-                "settings-nav-item": true,
-              })}
-              aria-current=${active === section.key ? "page" : "false"}
-              @click=${() => setSettingsSection(section.key)}
-            >
-              ${section.label}
-            </button>
-          `,
-        )}
-      </nav>
-      <div class="settings-doc-content" ${ref(panel.bindBody)}></div>
-    </div>
-  `;
+  panel.surface.update(values());
 
-  litRender(tpl, panel.host);
-
-  if (!panel.body || (!force && panel.rendered === active)) {
+  /* The island the document is holding right now. A body that has been REPLACED holds nothing, so
+     the section it was said to be showing has to be re-drawn — which is the one thing the lit
+     `ref` this replaced was ever really tracking. */
+  const body = panel.surface.body();
+  if (body !== panel.body) {
+    panel.body = body;
+    panel.rendered = null;
+  }
+  if (!body || (!force && panel.rendered === active)) {
     return;
   }
+  /* Read BEFORE the write: whether the section is changing is what decides the host, and
+     `panel.rendered` is about to stop saying so. */
+  const changed = panel.rendered !== active;
   panel.rendered = active;
   const section = settingsSection(active);
-  if (section) {
-    section.render(panel.body);
+  if (!section) {
+    /* Every section unregistered at once — a project closing while the editor is open. The
+       document says so itself (`hasSection`), and the island is emptied so a renderer's leftovers
+       do not sit under the sentence explaining that there is nothing to draw. */
+    panel.sectionHost = null;
+    body.replaceChildren();
     return;
   }
-  /* Every section unregistered at once — a project closing while the editor is open. A blank
-     content area beside a nav reads as a broken pane, so it says which it is. */
-  litRender(html`<div class="settings-empty-state">No settings sections.</div>`, panel.body);
+  /* A FRESH host whenever the section changes, and the same one for a forced redraw of the section
+     already showing — remounting that one would take the caret out of whatever field the reader is
+     typing in. The freshness is what lets the two kinds coexist: a lit section left its render part
+     on the element it drew into, and a document section clears the element it is given, so handing
+     either one the other's element is a throw or a double render. */
+  if (changed || !panel.sectionHost || panel.sectionHost.parentElement !== body) {
+    panel.sectionHost = document.createElement("div");
+    body.replaceChildren(panel.sectionHost);
+  }
+  section.render(panel.sectionHost);
 }