@jxsuite/studio 4.1.0 → 5.1.0

package/src/surfaces/inspector-dock.json

@@ -0,0 +1,187 @@
+{
+  "$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.",
+  "tagName": "div",
+  "attributes": {
+    "part": "inspector-dock"
+  },
+  "style": {
+    "$description": "`styles/inspector.css`'s dock rules, carried in. Three of them were `#right-panel > .panel-*` — a direct-child selector that only held while this module rendered flat into the shell cell — and they are `[part]` rules on the document's own children now, which is the same statement without depending on how deep the dock is mounted. The header's typography is `panels.css`'s `.panel-header*`, at the same values: `--spectrum-font-size-50` resolved only inside `<sp-theme>` and a document mounts outside it, so it is `--jx-text-sm` (11px) here.",
+    "display": "flex",
+    "flexDirection": "column",
+    "height": "100%",
+    "minHeight": "0",
+    "fontFamily": "var(--jx-font-sans)",
+    "color": "var(--fg)",
+    "& [part=\"header\"]": {
+      "display": "flex",
+      "flex": "0 0 auto",
+      "alignItems": "baseline",
+      "gap": "var(--jx-space-2)",
+      "padding": "6px var(--jx-space-3)",
+      "borderBottom": "1px solid var(--border)"
+    },
+    "& [part=\"header-title\"]": {
+      "fontSize": "var(--jx-text-sm)",
+      "fontWeight": "700",
+      "letterSpacing": "0.06em",
+      "textTransform": "uppercase",
+      "color": "var(--fg)"
+    },
+    "& [part=\"header-target\"]": {
+      "overflow": "hidden",
+      "fontSize": "var(--jx-text-sm)",
+      "color": "var(--fg-dim)",
+      "textOverflow": "ellipsis",
+      "whiteSpace": "nowrap",
+      "::before": {
+        "$description": "The separator between the tab's name and its target, drawn rather than written into the string — `panels/right-panel.ts` states what the dock is pointed at and nothing about punctuation.",
+        "content": "\"·\"",
+        "marginRight": "var(--jx-space-2)"
+      }
+    },
+    "& [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 (§3.2 ⑨). The kit tab's own 220px cap would let one tab push the last off the strip, so each takes an equal quarter.",
+      "flex": "0 0 auto",
+      "gap": "0",
+      "fontSize": "var(--jx-text-sm)"
+    },
+    "& [part=\"tab\"]": {
+      "flex": "1 1 0",
+      "justifyContent": "center",
+      "minWidth": "0",
+      "maxWidth": "none",
+      "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.",
+      "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"
+    },
+    "& [part=\"panel-body\"]": {
+      "display": "flex",
+      "flex": "1",
+      "flexDirection": "column",
+      "minHeight": "0"
+    }
+  },
+  "children": [
+    {
+      "tagName": "header",
+      "attributes": {
+        "part": "header"
+      },
+      "children": [
+        {
+          "tagName": "span",
+          "attributes": {
+            "part": "header-title"
+          },
+          "textContent": "${state.title}"
+        },
+        {
+          "tagName": "span",
+          "attributes": {
+            "part": "header-target"
+          },
+          "textContent": "${state.target}"
+        }
+      ]
+    },
+    {
+      "tagName": "jx-tabs",
+      "attributes": {
+        "part": "tabs",
+        "selected": "${state.tab}"
+      },
+      "$props": {
+        "label": "Inspector"
+      },
+      "onchange": {
+        "$prototype": "Function",
+        "body": [
+          {
+            "operator": "call",
+            "target": {
+              "$ref": "#/state/selectTab"
+            },
+            "value": [
+              {
+                "$ref": "event#/detail"
+              }
+            ]
+          }
+        ]
+      },
+      "children": [
+        {
+          "$prototype": "Array",
+          "items": {
+            "$ref": "#/state/tabs"
+          },
+          "key": {
+            "$ref": "$map/item/key"
+          },
+          "map": {
+            "tagName": "jx-tab",
+            "attributes": {
+              "part": "tab",
+              "id": "${$map.item.tabId}",
+              "data-tab": "${$map.item.key}",
+              "value": "${$map.item.key}",
+              "label": "${$map.item.title}",
+              "panel": "${$map.item.panelId}"
+            }
+          }
+        }
+      ]
+    },
+    {
+      "$prototype": "Array",
+      "items": {
+        "$ref": "#/state/tabs"
+      },
+      "key": {
+        "$ref": "$map/item/key"
+      },
+      "map": {
+        "tagName": "jx-tab-panel",
+        "attributes": {
+          "part": "panel",
+          "id": "${$map.item.panelId}",
+          "data-tab": "${$map.item.key}"
+        },
+        "$props": {
+          "active": {
+            "$ref": "$map/item/active"
+          },
+          "labelledby": {
+            "$ref": "$map/item/tabId"
+          }
+        },
+        "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}"
+            }
+          }
+        ]
+      }
+    }
+  ]
+}

package/src/surfaces/inspector-dock.ts

@@ -0,0 +1,161 @@
+/// <reference lib="dom" />
+/**
+ * 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.
+ *
+ * **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).
+ *
+ * **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,
+ * a target and a tab selection, and the runtime skips a binding whose value did not move — so there
+ * is no repaint to withhold, and the tab bodies were already mounted documents that never went
+ * through it.
+ *
+ * @docs studio/interface
+ */
+
+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 { JxScope } from "@jxsuite/runtime/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("inspector-dock", inspectorDockDoc as unknown as JxDocument);
+
+/** One tab of the dock, 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`. */
+  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;
+}
+
+/** What the dock says right now. */
+export interface InspectorDockValues {
+  /** The selected tab's title, drawn in the header. */
+  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. */
+  tab: string;
+  tabs: InspectorTabView[];
+}
+
+export interface InspectorDockActions {
+  /** A tab was activated. The flow decides whether that is a per-document or a detached write. */
+  selectTab: (id: string) => void;
+}
+
+export interface InspectorDockOptions {
+  /**
+   * One tab's body host, announced once, as it is created.
+   *
+   * @param tabId The tab the host belongs to
+   * @param host The empty `[part="panel-body"]`
+   */
+  onBody: (tabId: string, host: HTMLElement) => void;
+}
+
+export interface InspectorDockHandle {
+  /** Bring the mounted document up to date with a whole projection. */
+  update: (values: InspectorDockValues) => void;
+  /** Take the document down. Idempotent. */
+  dispose: () => void;
+}
+
+/** The scope the document reads. */
+interface InspectorDockScope extends Record<string, unknown>, InspectorDockValues {
+  selectTab: (id: string) => void;
+}
+
+/** Write a projection in, assignment by assignment, so an unchanged field is inert. */
+function project(scope: InspectorDockScope, values: InspectorDockValues): void {
+  scope.title = values.title;
+  scope.target = values.target;
+  scope.tab = values.tab;
+  scope.tabs = values.tabs;
+}
+
+/** 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 : "";
+}
+
+/** 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;
+}
+
+/**
+ * Mount the Inspector dock into `container`, which is the shell's `#right-panel` cell.
+ *
+ * The container is CLEARED first, unlike a Navigator panel's: this dock owns its cell outright and
+ * nothing else ever paints there, so a remount that appended would leave two docks and every
+ * `querySelector` would silently pick the stale one.
+ */
+export function mountInspectorDock(
+  container: HTMLElement,
+  values: InspectorDockValues,
+  actions: InspectorDockActions,
+  options: InspectorDockOptions,
+): InspectorDockHandle {
+  const scope = 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
+  delete container["_$litPart$"];
+
+  let mounted: SurfaceHandle | null = null;
+  let disposed = false;
+  void mountSurface("inspector-dock", scope, container, {
+    onNodeCreated: (element, _path, def, state) => {
+      if (!(element instanceof HTMLElement) || partOf(def) !== "panel-body") {
+        return;
+      }
+      const key = mapItem(state)?.["key"];
+      if (typeof key === "string" && key !== "") {
+        options.onBody(key, element);
+      }
+    },
+  }).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+      return;
+    }
+    mounted = surface;
+  });
+
+  return {
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+    },
+    update: (next) => {
+      project(scope, next);
+    },
+  };
+}

package/src/surfaces/jump-bar.json

@@ -0,0 +1,243 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioJumpBar",
+  "$description": "⑥ The jump bar: one pane's address, outermost step first, every step a command the adapter has already resolved against the registry. A step is a button when its command can run and a readout when it cannot — an address with a hole in it is a lie about containment, so a step never disappears. A step with more than one place to go carries the chevron that opens its siblings; one alternative is not a choice and draws no control. Nothing here decides what the bar says, which step is where you are, or what a chevron opens.",
+  "tagName": "nav",
+  "attributes": {
+    "part": "bar",
+    "aria-label": "Location",
+    "data-jx-region": "${state.region}",
+    "hidden": "${state.empty ? '' : null}"
+  },
+  "style": {
+    "$description": "The `.jump-bar` rules the bar used to take from `styles/shell.css`, brought here and re-valued onto the kit's own layer. It scrolls rather than wraps — a deep selection must not push the stage down by a second line — and the overflow is taken at the START, because the leaf is the part being read. The height is the one number this file shares with its adapter: the stage's `--jump-bar-h` offset must be the box this rule draws.",
+    "display": "flex",
+    "alignItems": "center",
+    "gap": "1px",
+    "height": "24px",
+    "padding": "0 var(--jx-space-3)",
+    "minWidth": "0",
+    "overflowX": "auto",
+    "scrollbarWidth": "none",
+    "whiteSpace": "nowrap",
+    "boxSizing": "border-box",
+    "fontFamily": "var(--jx-font-sans)",
+    "fontSize": "var(--jx-text-xs)",
+    "color": "var(--jx-fg-dim)",
+    "background": "var(--jx-bg-panel)",
+    "borderBottom": "1px solid var(--jx-border)",
+    "&[hidden]": {
+      "display": "none"
+    },
+    "&::-webkit-scrollbar": {
+      "display": "none"
+    },
+    "& [part=\"step\"]": {
+      "display": "flex",
+      "alignItems": "center",
+      "flexShrink": "0"
+    },
+    "& [part=\"separator\"]": {
+      "flexShrink": "0",
+      "padding": "0 1px",
+      "color": "var(--jx-fg-dim)",
+      "opacity": "0.6"
+    },
+    "& [part=\"crumb\"]": {
+      "maxWidth": "28ch",
+      "overflow": "hidden",
+      "margin": "0",
+      "padding": "0 var(--jx-space-2)",
+      "border": "none",
+      "borderRadius": "var(--jx-radius-xs)",
+      "background": "transparent",
+      "color": "inherit",
+      "font": "inherit",
+      "lineHeight": "1",
+      "whiteSpace": "nowrap",
+      "textOverflow": "ellipsis"
+    },
+    "& button[part=\"crumb\"]": {
+      "cursor": "pointer",
+      ":hover:not(:disabled)": {
+        "color": "var(--jx-fg)",
+        "background": "var(--jx-hover-bg)"
+      },
+      ":disabled": {
+        "cursor": "default",
+        "opacity": "0.6"
+      },
+      ":focus-visible": {
+        "outline": "var(--jx-focus-ring)",
+        "outlineOffset": "-2px"
+      }
+    },
+    "& [part=\"crumb\"][aria-current]": {
+      "$description": "Where you ARE is stated by weight, not by taking the control away: the leaf still selects, which is how a stray click in the canvas is undone without leaving the bar.",
+      "color": "var(--jx-fg)"
+    },
+    "& span[part=\"crumb\"]": {
+      "$description": "A step with no runnable command is a readout, not a dead button. No hover, no pointer, no promise.",
+      "cursor": "default"
+    },
+    "& [part=\"alternatives\"]": {
+      "padding": "0 1px",
+      "border": "none",
+      "borderRadius": "var(--jx-radius-xs)",
+      "background": "transparent",
+      "color": "inherit",
+      "font": "inherit",
+      "lineHeight": "1",
+      "cursor": "pointer",
+      ":hover": {
+        "color": "var(--jx-fg)",
+        "background": "var(--jx-hover-bg)"
+      },
+      ":focus-visible": {
+        "outline": "var(--jx-focus-ring)",
+        "outlineOffset": "-2px"
+      }
+    }
+  },
+  "children": [
+    {
+      "$prototype": "Array",
+      "items": {
+        "$ref": "#/state/segments"
+      },
+      "key": {
+        "$ref": "$map/item/key"
+      },
+      "map": {
+        "tagName": "span",
+        "attributes": {
+          "part": "step",
+          "data-jump-kind": "${$map.item.kind}"
+        },
+        "children": [
+          {
+            "tagName": "span",
+            "attributes": {
+              "part": "separator-slot",
+              "role": "none"
+            },
+            "style": {
+              "display": "contents"
+            },
+            "$switch": {
+              "$ref": "$map/item/leading"
+            },
+            "cases": {
+              "false": {
+                "tagName": "span",
+                "attributes": {
+                  "part": "separator",
+                  "aria-hidden": "true"
+                },
+                "textContent": "›"
+              }
+            }
+          },
+          {
+            "tagName": "span",
+            "attributes": {
+              "part": "crumb-slot",
+              "role": "none"
+            },
+            "style": {
+              "display": "contents"
+            },
+            "$switch": {
+              "$ref": "$map/item/control"
+            },
+            "cases": {
+              "button": {
+                "tagName": "button",
+                "attributes": {
+                  "part": "crumb",
+                  "type": "button",
+                  "title": "${$map.item.title}",
+                  "aria-current": "${$map.item.current ? 'true' : null}",
+                  "disabled": {
+                    "$ref": "$map/item/disabled"
+                  }
+                },
+                "textContent": "${$map.item.label}",
+                "onclick": {
+                  "$prototype": "Function",
+                  "body": [
+                    {
+                      "operator": "call",
+                      "target": {
+                        "$ref": "#/state/run"
+                      },
+                      "value": [
+                        {
+                          "$ref": "$map/item/key"
+                        }
+                      ]
+                    }
+                  ]
+                }
+              },
+              "readout": {
+                "tagName": "span",
+                "attributes": {
+                  "part": "crumb",
+                  "title": "${$map.item.title}",
+                  "aria-current": "${$map.item.current ? 'true' : null}"
+                },
+                "textContent": "${$map.item.label}"
+              }
+            }
+          },
+          {
+            "tagName": "span",
+            "attributes": {
+              "part": "alternatives-slot",
+              "role": "none"
+            },
+            "style": {
+              "display": "contents"
+            },
+            "$switch": {
+              "$ref": "$map/item/hasChoices"
+            },
+            "cases": {
+              "true": {
+                "tagName": "button",
+                "attributes": {
+                  "part": "alternatives",
+                  "type": "button",
+                  "aria-haspopup": "menu",
+                  "aria-label": "${$map.item.altsLabel}",
+                  "title": "${$map.item.altsLabel}"
+                },
+                "textContent": "⌄",
+                "onclick": {
+                  "$prototype": "Function",
+                  "body": [
+                    {
+                      "operator": "call",
+                      "target": {
+                        "$ref": "#/state/choose"
+                      },
+                      "value": [
+                        {
+                          "$ref": "$map/item/key"
+                        },
+                        {
+                          "$ref": "event#/currentTarget"
+                        }
+                      ]
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        ]
+      }
+    }
+  ]
+}