@jxsuite/studio 6.1.1 → 8.0.0

package/src/surfaces/inspector-dock.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioInspectorDock",
-  "$description": "The Inspector dock's own chrome, as a Jx document over the kit: a header naming what the dock is pointed at, a real `tablist` of four tabs, and four `tabpanel`s. It draws no tab BODY — all four are mounted documents of their own (`surfaces/properties-panel.json`, `surfaces/style-panel.json`, `surfaces/logic-panel.json`, and the assistant's) — so each panel carries one empty `[part=\"panel-body\"]` island the adapter announces through `onNodeCreated` (studio-ui-guidelines.md §9.4). The four panels are keyed on the tab id and the id list never changes, so a body host is created ONCE and lives as long as the dock: that is what the old module's hand-built permanent containers were for, and it is now a property of a keyed `$map` rather than a rule someone has to keep. `panels/right-panel.ts` keeps every decision — which tab is selected, per document or detached; what the target's name is; and which of the four seams a host is handed to.",
+  "$description": "The Inspector dock's own chrome, as a Jx document over the kit: a header naming the tab and what the dock is pointed at, a real `tablist` of three tabs (Page · Element · Assistant, specs/studio.md §6), and a `tabpanel` per tab. It draws no tab BODY: each of the five leaves (the Page tab's body, Element's Content, Style and Logic, and the Assistant) is a mounted document of its own, so each leaf carries one empty `[part=\"panel-body\"]` island the adapter announces through `onNodeCreated` (studio-ui-guidelines.md §9.4). Element hosts three leaves behind a sub-switch, a single-select `jx-action-group` inside its panel; the other two tabs host one leaf each and draw no switch. Tabs and leaves are keyed on their ids and neither list ever changes, so a body host is created ONCE and lives as long as the dock: the hidden leaves stay mounted, which is what keeps a half-typed value and the Assistant's transcript alive across a switch. `panels/right-panel.ts` keeps every decision — which leaf is selected, per document or detached; what the Page tab is called for this document; what the target's name is; and which seam a host is handed to.",
   "tagName": "div",
   "attributes": {
     "part": "inspector-dock"
@@ -42,7 +42,7 @@
       }
     },
     "& [part=\"tabs\"]": {
-      "$description": "Four words in a 280px dock, allowed to compress rather than to become anonymous — which is why the tabs are not icons (§6). The kit tab's own 220px cap would let one tab push the last off the strip, so each takes an equal quarter.",
+      "$description": "Three words in a 280px dock, allowed to compress rather than to become anonymous, which is why the tabs are not icons (§6). The kit tab's own 220px cap would let one tab push the last off the strip, so each takes an equal third.",
       "flex": "0 0 auto",
       "gap": "0",
       "fontSize": "var(--jx-text-sm)"
@@ -55,26 +55,55 @@
       "padding": "var(--jx-space-1) var(--jx-space-2)"
     },
     "& [part=\"panel\"]": {
-      "$description": "`#right-panel > .panel-body { flex: 1; min-height: 0; overflow-y: auto }`. The kit's tab panel pads itself for a dialog; a dock's tab is the whole column and each body pads its own content.",
+      "$description": "`#right-panel > .panel-body { flex: 1; min-height: 0; overflow-y: auto }`, now a flex column: Element's sub-switch sits above its leaves and must not scroll away with them. The kit's tab panel pads itself for a dialog; a dock's tab is the whole column and each body pads its own content.",
+      "display": "flex",
+      "flexDirection": "column",
       "flex": "1",
       "minHeight": "0",
       "padding": "0",
-      "overflowY": "auto"
-    },
-    "& [part=\"panel\"][data-tab=\"assistant\"]": {
-      "$description": "The chat owns its own scrolling, so its panel is a nested flex column that does not scroll.",
-      "display": "flex",
-      "flexDirection": "column",
       "overflow": "hidden"
     },
     "& [part=\"panel\"][hidden]": {
-      "display": "none"
+      "$description": "Out of sight, out of the layout and out of the accessibility tree, but not `display: none`: a panel that left the box tree is restyled whole when it comes back, and the Inspector shows its Page panel on every deselect and on every close of the Assistant (§6), which made each of those a 300-element style recalculation. `content-visibility: hidden` skips the subtree while keeping its computed style, so a return restyles only what changed while it was away; `visibility: hidden` keeps it unfocusable and unexposed, as `hidden` means.",
+      "display": "flex",
+      "flex": "0 0 0",
+      "contentVisibility": "hidden",
+      "visibility": "hidden"
     },
     "& [part=\"panel-body\"]": {
       "display": "flex",
       "flex": "1",
       "flexDirection": "column",
-      "minHeight": "0"
+      "minHeight": "0",
+      "overflowY": "auto"
+    },
+    "& [part=\"subtabs\"]": {
+      "$description": "Element's Content · Style · Logic switch. It is not a second tab strip: three views of the one selected node, so it is a single-select group inside the tab's body, and it does not count against the dock's four-tab cap (studio-ui-guidelines.md §12.2).",
+      "flex": "0 0 auto",
+      "padding": "var(--jx-space-2) var(--jx-space-3)",
+      "borderBottom": "1px solid var(--border)"
+    },
+    "& [part=\"subtab\"]": {
+      "flex": "1 1 0",
+      "justifyContent": "center"
+    },
+    "& [part=\"leaf-empty\"]": {
+      "margin": "0",
+      "padding": "var(--jx-space-6) var(--jx-space-4)",
+      "textAlign": "center",
+      "lineHeight": "1.5",
+      "fontSize": "var(--jx-text-md)",
+      "color": "var(--fg-dim)"
+    },
+    "& [part=\"panel-body\"][data-tab=\"assistant\"]": {
+      "$description": "The chat owns its own scrolling, so its body is a flex column that does not scroll.",
+      "overflow": "hidden"
+    },
+    "& [part=\"panel-body\"][data-active=\"false\"]": {
+      "$description": "A leaf that is not the one showing stays MOUNTED and is only taken out of the layout: it is a document with its own state, and rebuilding it on every switch would drop whatever it was holding. Hidden the way a hidden panel is (above), so switching back to it does not restyle it whole.",
+      "flex": "0 0 0",
+      "contentVisibility": "hidden",
+      "visibility": "hidden"
     }
   },
   "children": [
@@ -173,11 +202,130 @@
         },
         "children": [
           {
-            "$description": "The island. Every one of the four tabs is a mounted document of its own, so this stays EMPTY for the life of the dock — `panels/right-panel.ts` is handed it through `onNodeCreated` and passes it to that tab's binder exactly once. It is a slotted child rather than the panel element itself because `jx-tab-panel` distributes its own slot, and a second owner of that child list would fight it.",
             "tagName": "div",
             "attributes": {
-              "part": "panel-body",
-              "data-jx-region": "${$map.item.region}"
+              "part": "subtabs-slot",
+              "role": "none"
+            },
+            "style": {
+              "display": "contents"
+            },
+            "$switch": {
+              "$ref": "$map/item/hasLeaves"
+            },
+            "cases": {
+              "true": {
+                "tagName": "jx-action-group",
+                "attributes": {
+                  "part": "subtabs"
+                },
+                "$props": {
+                  "selects": "single",
+                  "compact": true,
+                  "label": "${$map.item.title} view"
+                },
+                "children": [
+                  {
+                    "$prototype": "Array",
+                    "items": {
+                      "$ref": "$map/item/leaves"
+                    },
+                    "key": {
+                      "$ref": "$map/item/key"
+                    },
+                    "map": {
+                      "tagName": "jx-action-button",
+                      "attributes": {
+                        "part": "subtab",
+                        "data-tab": "${$map.item.key}"
+                      },
+                      "$props": {
+                        "size": "sm",
+                        "emphasized": true,
+                        "checked": {
+                          "$ref": "$map/item/shown"
+                        }
+                      },
+                      "onclick": {
+                        "$prototype": "Function",
+                        "body": [
+                          {
+                            "operator": "call",
+                            "target": {
+                              "$ref": "#/state/selectTab"
+                            },
+                            "value": [
+                              {
+                                "$ref": "$map/item/key"
+                              }
+                            ]
+                          }
+                        ]
+                      },
+                      "children": [
+                        {
+                          "tagName": "span",
+                          "textContent": "${$map.item.title}"
+                        }
+                      ]
+                    }
+                  }
+                ]
+              }
+            }
+          },
+          {
+            "$prototype": "Array",
+            "items": {
+              "$ref": "$map/item/leaves"
+            },
+            "key": {
+              "$ref": "$map/item/key"
+            },
+            "map": {
+              "tagName": "div",
+              "attributes": {
+                "part": "leaf",
+                "role": "none",
+                "data-tab": "${$map.item.key}"
+              },
+              "style": {
+                "display": "contents"
+              },
+              "children": [
+                {
+                  "tagName": "div",
+                  "attributes": {
+                    "part": "leaf-empty-slot",
+                    "role": "none"
+                  },
+                  "style": {
+                    "display": "contents"
+                  },
+                  "$switch": {
+                    "$ref": "$map/item/hasEmpty"
+                  },
+                  "cases": {
+                    "true": {
+                      "tagName": "p",
+                      "attributes": {
+                        "part": "leaf-empty"
+                      },
+                      "textContent": "${$map.item.empty}"
+                    }
+                  }
+                },
+                {
+                  "$description": "The island. Every leaf is a mounted document of its own, so this stays EMPTY for the life of the dock — `panels/right-panel.ts` is handed it through `onNodeCreated` and passes it to that leaf's binder exactly once.",
+                  "tagName": "div",
+                  "attributes": {
+                    "part": "panel-body",
+                    "data-tab": "${$map.item.key}",
+                    "data-active": "${$map.item.shown}",
+                    "data-jx-region": "${$map.item.region}"
+                  }
+                }
+              ]
             }
           }
         ]

package/src/surfaces/inspector-dock.ts

@@ -2,17 +2,18 @@
 /**
  * The Inspector dock's chrome as a mounted document.
  *
- * `panels/right-panel.ts` is the flow — which tab is selected (per document, or detached when
- * nothing is open), what the selection is called, and which of the four seams a body host is handed
- * to — and this is the surface it draws into.
+ * `panels/right-panel.ts` is the flow — which leaf is selected (per document, or detached when
+ * nothing is open), what the Page tab and the selection are called, and which of the five seams a
+ * body host is handed to — and this is the surface it draws into.
  *
- * **The four bodies are islands, and they are created once.** `inspector-dock.json` keys its tab
- * panels on the tab id, and that list is `INSPECTOR_TABS`: a constant. A keyed `$map` over a
- * constant list creates every row on the first render and never tears one down, so the empty
- * `[part="panel-body"]` inside each panel is exactly the permanent container the old module built
- * by hand — without a second module having to promise it will not rebuild them. Each is announced
- * through `onNodeCreated` as it is CREATED, one reconcile step before it is in the page, so
- * connectedness is deliberately not consulted here (studio-ui-guidelines.md §9.4).
+ * **Three tabs, five bodies, and every body is an island created once.** The strip is Page ·
+ * Element · Assistant (§6), and Element hosts three leaves (Content, Style, Logic) behind a
+ * sub-switch. `inspector-dock.json` keys the tab panels on the strip id and each panel's leaves on
+ * the leaf id, and both lists are CONSTANTS (`INSPECTOR_STRIP`, `INSPECTOR_TABS`). A keyed `$map`
+ * over a constant list creates every row on the first render and never tears one down, so the empty
+ * `[part="panel-body"]` of each leaf is exactly the permanent container the old module built by
+ * hand. Each is announced through `onNodeCreated` as it is CREATED, one reconcile step before it is
+ * in the page, so connectedness is deliberately not consulted here (studio-ui-guidelines.md §9.4).
  *
  * **No scheduler.** `panels/panel-scheduler.ts` withheld a repaint while a text field in the dock
  * had focus, because a lit repaint replaces the node the caret is in. This document paints a title,
@@ -23,51 +24,78 @@
  * @docs studio/interface
  */
 
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import inspectorDockDoc from "./inspector-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("inspector-dock", inspectorDockDoc as unknown as JxDocument);
+registerSurface("inspector-dock", inspectorDockDoc);
 
-/** One tab of the dock, as the document draws it. Every field is a value. */
+/** One leaf of a tab — a body the dock can show. Every field is a value. */
+export interface InspectorLeafView {
+  /** The leaf id (`shell.ts`'s `INSPECTOR_TAB_IDS`) — the row's identity, and `data-tab`. */
+  key: string;
+  /** The sub-switch label: Content, Style, Logic. Unused on a tab with one leaf. */
+  title: string;
+  /** `inspector/tab:<id>` — stamped on the body host the screenshot pipeline crops. */
+  region: string;
+  /** Whether this is the leaf on screen. Exactly one, across every tab, is true. */
+  active: boolean;
+  /**
+   * {@link InspectorLeafView.active} as the `data-active` string the style block keys on. A boolean
+   * renders as a bare attribute, which `[data-active="false"]` cannot match. It is also the
+   * sub-switch segment's `checked`: the kit's radio segment takes the STRING `"true"`/`"false"`,
+   * and a boolean there leaves an unselected segment a plain button inside the radiogroup.
+   */
+  shown: "true" | "false";
+  /** The sentence the leaf shows instead of a body, or empty when it has a body to show. */
+  empty: string;
+  hasEmpty: boolean;
+}
+
+/** One tab of the strip, as the document draws it. Every field is a value. */
 export interface InspectorTabView {
-  /** The tab id — the row's identity, the strip's `selected` value, and `data-tab`. */
+  /** The strip id — the row's identity, the strip's `selected` value, and `data-tab`. */
   key: string;
   title: string;
   /** The tab element's own id, which is also its panel's `aria-labelledby`. */
   tabId: string;
   /** The tab panel element's own id, which is also the tab's `aria-controls`. */
   panelId: string;
-  /** `inspector/tab:<id>` — stamped on the body host the screenshot pipeline crops. */
-  region: string;
   /** Whether this is the tab on screen. Exactly one is true. */
   active: boolean;
+  /** Whether the tab draws a sub-switch — Element alone, which hosts three leaves. */
+  hasLeaves: boolean;
+  leaves: InspectorLeafView[];
 }
 
 /** What the dock says right now. */
 export interface InspectorDockValues {
-  /** The selected tab's title, drawn in the header. */
+  /** The showing tab's title, drawn in the header: contextual for Page (§6). */
   title: string;
   /** What the tab is pointed at, in the fewest words that are true. */
   target: string;
-  /** The selected tab id — what `jx-tabs` compares each tab's `value` against. */
+  /** The showing STRIP id — what `jx-tabs` compares each tab's `value` against. */
   tab: string;
   tabs: InspectorTabView[];
 }
 
 export interface InspectorDockActions {
-  /** A tab was activated. The flow decides whether that is a per-document or a detached write. */
+  /**
+   * A tab or a sub-switch leaf was activated: a strip id (`page`, `element`, `assistant`) from the
+   * strip, a leaf id from Element's switch. The flow decides what each means.
+   */
   selectTab: (id: string) => void;
 }
 
 export interface InspectorDockOptions {
   /**
-   * One tab's body host, announced once, as it is created.
+   * One leaf's body host, announced once, as it is created.
    *
-   * @param tabId The tab the host belongs to
+   * @param tabId The leaf the host belongs to
    * @param host The empty `[part="panel-body"]`
    */
   onBody: (tabId: string, host: HTMLElement) => void;
@@ -81,7 +109,7 @@ export interface InspectorDockHandle {
 }
 
 /** The scope the document reads. */
-interface InspectorDockScope extends Record<string, unknown>, InspectorDockValues {
+interface InspectorDockScope extends InspectorDockValues {
   selectTab: (id: string) => void;
 }
 
@@ -95,15 +123,15 @@ function project(scope: InspectorDockScope, values: InspectorDockValues): void {
 
 /** 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;
 }
 
 /**
@@ -119,10 +147,10 @@ export function mountInspectorDock(
   actions: InspectorDockActions,
   options: InspectorDockOptions,
 ): InspectorDockHandle {
-  const scope = reactive<InspectorDockScope>({
+  const scope: InspectorDockScope = reactive<InspectorDockScope>({
     ...values,
     selectTab: actions.selectTab,
-  }) as InspectorDockScope;
+  });
 
   container.textContent = "";
   // @ts-expect-error -- _$litPart$ is lit's private render-part marker, not in the DOM types
@@ -136,7 +164,7 @@ export function mountInspectorDock(
         return;
       }
       const key = mapItem(state)?.["key"];
-      if (typeof key === "string" && key !== "") {
+      if (isString(key) && key !== "") {
         options.onBody(key, element);
       }
     },

package/src/surfaces/jump-bar.ts

@@ -23,10 +23,9 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import jumpBarDoc from "./jump-bar.json";
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("jump-bar", jumpBarDoc as unknown as JxDocument);
+registerSurface("jump-bar", jumpBarDoc);
 
 /**
  * One step of the address, as the document reads it.
@@ -35,7 +34,7 @@ registerSurface("jump-bar", jumpBarDoc as unknown as JxDocument);
  * and a `$switch` chooses on one: a step that omitted `title` would leave the readout case reading
  * an absent path.
  */
-export interface ProjectedStep extends Record<string, unknown> {
+export interface ProjectedStep {
   /** Unique within one bar: the repeater's key, and the argument `run` and `choose` receive. */
   key: string;
   /** `project` | `file` | `editor` | `node` — stamped so a test names a step without its text. */
@@ -73,7 +72,7 @@ export interface JumpBarSurface {
 }
 
 /** The scope `jump-bar.json` reads. */
-interface JumpBarScope extends Record<string, unknown>, JumpBarActions {
+interface JumpBarScope extends JumpBarActions {
   region: string;
   segments: ProjectedStep[];
   empty: boolean;
@@ -95,12 +94,12 @@ export function mountJumpBarSurface(
   region: string,
   actions: JumpBarActions,
 ): JumpBarSurface {
-  const scope = reactive<JumpBarScope>({
+  const scope: JumpBarScope = reactive<JumpBarScope>({
     ...actions,
     empty: true,
     region,
     segments: [],
-  }) as JumpBarScope;
+  });
 
   host.replaceChildren();
   let mounted: SurfaceHandle | null = null;

package/src/surfaces/jxsuite-update.ts

@@ -24,13 +24,12 @@
 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 jxsuiteUpdateDoc from "./jxsuite-update.json";
-import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
+import type { DialogLayerHandle, SurfaceHandle } from "../ui/surface";
 
-registerSurface("jxsuite-update", jxsuiteUpdateDoc as unknown as JxDocument);
+registerSurface("jxsuite-update", jxsuiteUpdateDoc);
 
 /** One package the offer would move. Every field is already the string the row prints. */
 export interface JxsuiteUpdateRow {
@@ -55,16 +54,7 @@ export interface JxsuiteUpdateSurfaceOptions {
   onClosed: () => void;
 }
 
-export interface JxsuiteUpdateSurfaceHandle {
-  /** 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. */
-  ready: Promise<HTMLElement>;
-  /** Close the dialog (the platform restores focus) and dispose the document. Idempotent. */
-  close: () => void;
-}
-
-interface JxsuiteUpdateScope extends Record<string, unknown> {
+interface JxsuiteUpdateScope {
   packages: JxsuiteUpdateRow[];
   confirm: () => void;
   cancel: () => void;
@@ -72,9 +62,7 @@ interface JxsuiteUpdateScope extends Record<string, unknown> {
 }
 
 /** Open the offer. The handle's `ready` resolves once the dialog is showing. */
-export function openJxsuiteUpdateSurface(
-  options: JxsuiteUpdateSurfaceOptions,
-): JxsuiteUpdateSurfaceHandle {
+export function openJxsuiteUpdateSurface(options: JxsuiteUpdateSurfaceOptions): DialogLayerHandle {
   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
@@ -98,8 +86,12 @@ export function openJxsuiteUpdateSurface(
     closed = true;
     options.onClosed();
   };
+  /* 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;
 
-  const scope = reactive<JxsuiteUpdateScope>({
+  const scope: JxsuiteUpdateScope = reactive<JxsuiteUpdateScope>({
     cancel: () => {
       options.onCancel();
     },
@@ -108,18 +100,20 @@ export function openJxsuiteUpdateSurface(
       options.onConfirm();
     },
     packages: options.packages,
-  }) as JxsuiteUpdateScope;
+  });
 
   let mounted: SurfaceHandle | null = null;
   const ready = mountSurface("jxsuite-update", scope, slot).then(async (surface) => {
     mounted = surface;
+    /* SAFETY: `jxsuite-update.json`'s root definition is a `jx-dialog` element, 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;
     }
     showModal(element);
@@ -135,7 +129,7 @@ export function openJxsuiteUpdateSurface(
       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();