@jxsuite/studio 4.1.0 → 5.1.0

package/src/surfaces/menu.ts

@@ -0,0 +1,375 @@
+/**
+ * The menu surface: a `jx-menu` of command-record projections, mounted into a popover layer slot.
+ *
+ * This is the first Studio surface rendered as a Jx document (specs/studio-ui-guidelines.md §6,
+ * §9.3): `menu.json` is the markup, ARIA and style, and this adapter is the decisions — which
+ * records, what they print, where the panel opens, what runs on select. The kit owns the menu
+ * contract (roving focus, typeahead, submenus, light dismissal, Escape) through the platform's own
+ * popover, so nothing here binds a key or a document listener.
+ *
+ * Every menu opens in a `getLayerSlot("popover", id)` slot, which is what carries the
+ * `overlay.menu:<id>` region the screenshot pipeline addresses, and is torn down when the popover
+ * closes — by a row, by a key, or by a click outside — through the one `toggle` event the platform
+ * fires for all three.
+ *
+ * The rows are HOST STATE: the scope is reactive, so `setRows()` reconciles the open menu through
+ * the document's keyed `$map` — a row whose id survives keeps its node and the caret, a new one is
+ * inserted, a gone one removed — which is how a settings section registering while the gear menu is
+ * up appears in it without the menu closing.
+ *
+ * @docs studio/interface/canvas
+ * @docs studio/interface/preferences
+ */
+import type { JxDocument } from "@jxsuite/schema/types";
+import type { JxScope } from "@jxsuite/runtime/types";
+import { ensureCaret } from "@jxsuite/ui/behaviors/menu";
+import { reactive } from "../reactivity";
+import { clearLayerSlot, getLayerSlot } from "../ui/layers";
+import { mountSurface, registerSurface } from "../ui/surface";
+import { rectOf } from "../utils/geometry";
+import menuDoc from "./menu.json";
+
+registerSurface("menu", menuDoc as unknown as JxDocument);
+
+/**
+ * What a row prints: a projection of one command record, decided by the adapter that opens the
+ * menu.
+ */
+export interface MenuRowProjection {
+  /** The command id; the row's `value`, what `run` receives, and the row's identity across updates. */
+  id: string;
+  title: string;
+  /** The formatted chord, if the row should teach one. */
+  chord?: string;
+  disabled: boolean;
+  /** The one-sentence reason a disabled row cannot act. */
+  requires?: string;
+  destructive: boolean;
+  /** A group boundary: a divider is drawn above this row. */
+  dividerAbove: boolean;
+  /** `"true"` or `"false"` for a checkbox row; absent for a plain one. */
+  checked?: "true" | "false";
+  /**
+   * The rows of this row's submenu, one level deep. The row still runs its own command — a submenu
+   * is a second way in, never a replacement (studio-ui-guidelines.md §8.4).
+   */
+  children?: readonly MenuRowProjection[];
+  /** The submenu's accessible name; the row's title by default. */
+  submenuLabel?: string;
+  /** What this row runs, instead of the menu-wide `run(id)`. */
+  run?: () => void;
+}
+
+export interface OpenMenuOptions {
+  rows: readonly MenuRowProjection[];
+  /** The menu's accessible name. */
+  label: string;
+  /** Where the panel opens, in viewport pixels, when `place` is not given. */
+  origin?: { x: number; y: number };
+  /**
+   * Where the panel opens as a function of its measured box: run once the popover is shown and
+   * again a frame later, so a menu that hangs off a control can put its bottom flush with a floor.
+   */
+  place?: (box: DOMRect) => { x: number; y: number };
+  /** The lowest edge the menu and its submenus may reach; the viewport by default. */
+  floor?: () => number;
+  /**
+   * Where the menu hangs relative to `opener`, as a CSS `position-area` value, on an engine with
+   * anchor positioning (ui.md §5.1). Derived when omitted: a menu with an `opener` and neither a
+   * `place` nor a `floor` hangs `block-end span-inline-end` — below it, leading edges aligned,
+   * which is what every such caller's `origin` computes — and every other menu is placed by its
+   * coordinates: a context menu at the pointer, a menu whose `place` right-aligns it, a menu that
+   * sits on a floor. Pass the empty string to keep a menu with an opener on its coordinates.
+   */
+  placement?: string;
+  /**
+   * The popover slot id; the region becomes `overlay.menu:<id>`, so the context menu passes
+   * `context`.
+   */
+  region: string;
+  /**
+   * Runs the selected row's command, for rows without a `run` of their own. Called before the menu
+   * closes.
+   */
+  run?: (id: string) => void;
+  /**
+   * What held the keyboard before the menu took it, handed back when the menu closes — and, when it
+   * is a control, the popover's invoker, so a mousedown on it does not light-dismiss the menu its
+   * own click is about to toggle.
+   */
+  opener?: HTMLElement | null;
+  /** Called once, however the menu closed. */
+  onClosed?: (handle: MenuHandle) => void;
+}
+
+export interface MenuHandle {
+  /** The layer slot the menu is mounted in. */
+  readonly host: HTMLElement;
+  /** Settles once the document is mounted and the popover shown, or the menu was closed first. */
+  readonly ready: Promise<void>;
+  /** Close the menu now, synchronously: the slot is emptied before this returns. */
+  readonly close: () => void;
+  /** Replace the rows; the open menu reconciles in place and the caret is kept on a row. */
+  readonly setRows: (rows: readonly MenuRowProjection[]) => void;
+}
+
+type MenuElement = HTMLElement & {
+  open?: boolean;
+  x?: number;
+  y?: number;
+  showPopover: (options?: { source?: Element }) => void;
+};
+
+/**
+ * A row as the document reads it: the projection with every optional filled in, plus the flags its
+ * bindings need.
+ */
+type ProjectedRow = Omit<
+  MenuRowProjection,
+  "checked" | "children" | "chord" | "requires" | "submenuLabel"
+> & {
+  chord: string;
+  requires: string;
+  checked: "true" | "false" | "";
+  enabled: boolean;
+  noChord: boolean;
+  noDivider: boolean;
+  haspopup: boolean;
+  submenuLabel: string;
+  children: ProjectedRow[];
+};
+
+/** The scope shape `menu.json` reads. */
+interface MenuScope extends Record<string, unknown> {
+  rows: ProjectedRow[];
+  label: string;
+  x: number;
+  y: number;
+  floor: number;
+  placement: string;
+  select: (scope: JxScope, event: Event) => void;
+}
+
+/** The default hang of a menu from its opener, which every `origin` of such a caller computes. */
+const BELOW_OPENER = "block-end span-inline-end";
+
+/** What {@link OpenMenuOptions.placement} means once the derivation has been applied. */
+export function placementOf(
+  options: Pick<OpenMenuOptions, "floor" | "opener" | "origin" | "place" | "placement">,
+): string {
+  if (options.placement !== undefined) {
+    return options.placement;
+  }
+  return options.opener && !options.origin && !options.place && !options.floor ? BELOW_OPENER : "";
+}
+
+/**
+ * Where a menu with no coordinates of its own opens on an engine that cannot anchor it: below its
+ * opener, leading edges aligned — the same corner the placement names.
+ */
+function belowOpener(opener: HTMLElement | null | undefined): { x: number; y: number } {
+  if (!opener) {
+    return { x: 0, y: 0 };
+  }
+  const box = rectOf(opener);
+  return { x: Math.round(box.left), y: Math.round(box.bottom) };
+}
+
+function project(row: MenuRowProjection, depth = 0): ProjectedRow {
+  const children = depth === 0 ? (row.children ?? []).map((child) => project(child, 1)) : [];
+  return {
+    ...row,
+    checked: row.checked ?? "",
+    children,
+    chord: row.chord ?? "",
+    enabled: !row.disabled,
+    haspopup: children.length > 0,
+    noChord: !row.chord,
+    noDivider: !row.dividerAbove,
+    requires: row.requires ?? "",
+    submenuLabel: row.submenuLabel ?? row.title,
+  };
+}
+
+/** The row, at either level, a select event's detail names. */
+function rowById(rows: readonly ProjectedRow[], id: string): ProjectedRow | undefined {
+  for (const row of rows) {
+    if (row.id === id) {
+      return row;
+    }
+    const child = row.children.find((c) => c.id === id);
+    if (child) {
+      return child;
+    }
+  }
+  return undefined;
+}
+
+const ZERO_BOX = {
+  bottom: 0,
+  height: 0,
+  left: 0,
+  right: 0,
+  top: 0,
+  width: 0,
+  x: 0,
+  y: 0,
+} as DOMRect;
+
+/**
+ * Open a menu.
+ *
+ * @param {OpenMenuOptions} options
+ * @returns {MenuHandle}
+ */
+export function openMenu(options: OpenMenuOptions): MenuHandle {
+  const slot = getLayerSlot("popover", options.region);
+  const controller = new AbortController();
+  let menu: MenuElement | null = null;
+  let dispose: (() => void) | null = null;
+  let closed = false;
+
+  const finish = (): void => {
+    if (closed) {
+      return;
+    }
+    closed = true;
+    controller.abort();
+    dispose?.();
+    dispose = null;
+    clearLayerSlot("popover", options.region);
+    restoreFocus(options.opener ?? null);
+    options.onClosed?.(handle);
+  };
+
+  const initial = options.place
+    ? options.place(ZERO_BOX)
+    : (options.origin ?? belowOpener(options.opener));
+  const scope: MenuScope = reactive({
+    floor: options.floor?.() ?? 0,
+    label: options.label,
+    placement: placementOf(options),
+    rows: options.rows.map((row) => project(row)),
+    select: (_scope: JxScope, event: Event) => {
+      const id = String((event as CustomEvent).detail);
+      const row = rowById(scope.rows, id);
+      if (!row) {
+        return;
+      }
+      // Run BEFORE closing: a command reads its target synchronously on entry, and closing the
+      // Menu is what clears it.
+      if (row.run) {
+        row.run();
+      } else {
+        options.run?.(id);
+      }
+      handle.close();
+    },
+    x: initial.x,
+    y: initial.y,
+  }) as MenuScope;
+
+  /** Put the panel where `place` says, from its box as laid out now. */
+  const place = (): void => {
+    if (closed || !menu || !options.place) {
+      return;
+    }
+    const at = options.place(rectOf(menu));
+    scope.x = at.x;
+    scope.y = at.y;
+  };
+
+  const ready = (async () => {
+    const mounted = await mountSurface("menu", scope, slot, { signal: controller.signal });
+    if (controller.signal.aborted) {
+      // Closed before the document finished mounting; the runtime already disposed it.
+      return;
+    }
+    ({ dispose } = mounted);
+    // The document's root IS the menu, and a custom element connects asynchronously: `jx-ready` is
+    // The menu saying its `popover` attribute is on and it may be shown.
+    menu = mounted.root as MenuElement;
+    menu.addEventListener("toggle", (event) => {
+      if ((event as { newState?: string }).newState === "closed") {
+        finish();
+      }
+    });
+    if (!menu.hasAttribute("popover")) {
+      await new Promise<void>((resolve) => {
+        menu!.addEventListener("jx-ready", () => resolve(), { once: true });
+      });
+    }
+    if (controller.signal.aborted) {
+      return;
+    }
+    const source =
+      options.opener instanceof HTMLElement && options.opener !== document.body
+        ? options.opener
+        : undefined;
+    menu.showPopover(source ? { source } : undefined);
+    // Showing a popover lays it out, so the first pass measures a real box; the second, a frame
+    // Later, catches a font or an image that landed after.
+    place();
+    requestAnimationFrame(place);
+  })();
+
+  const handle: MenuHandle = {
+    close: () => {
+      if (closed) {
+        return;
+      }
+      if (menu?.open) {
+        menu.hidePopover();
+      }
+      finish();
+    },
+    host: slot,
+    ready,
+    setRows: (rows) => {
+      if (closed) {
+        return;
+      }
+      // The row whose submenu holds the caret, if one does: should the new rows take that submenu
+      // Away with them (a row with no children owns none), the caret goes back to the row.
+      const active = document.activeElement;
+      const holder = active?.closest("jx-menu");
+      const ownerId =
+        holder && holder !== menu
+          ? holder.parentElement?.closest<HTMLElement>("jx-menu-item")?.dataset.commandId
+          : undefined;
+      scope.rows = rows.map((row) => project(row));
+      // The rows reconcile in microtasks of their own — the submenu's rows in one queued by the
+      // Row's — so the caret is checked once all of them have run, from the task queue.
+      setTimeout(() => {
+        if (closed || !menu || menu.contains(document.activeElement)) {
+          return;
+        }
+        const owner = ownerId
+          ? menu.querySelector<HTMLElement>(`jx-menu-item[data-command-id="${ownerId}"]`)
+          : null;
+        const submenu = owner?.querySelector<MenuElement>("jx-menu") ?? null;
+        // The submenu that held the caret is gone with its rows: its owner takes the caret.
+        // Still up with rows left: the caret stays inside it, on the first.
+        if (owner && !(submenu?.open && submenu.querySelector("jx-menu-item"))) {
+          owner.focus();
+        } else {
+          ensureCaret(menu);
+        }
+      }, 0);
+    },
+  };
+  return handle;
+}
+
+/**
+ * Hand the keyboard back to the opener, only when the menu still held it: an outside CLICK has
+ * already moved focus somewhere the author chose, and yanking it back would fight them. In a
+ * browser the platform does this itself when an `auto` popover hides; this covers the test DOM and
+ * a popover hidden programmatically.
+ */
+function restoreFocus(opener: HTMLElement | null): void {
+  const active = document.activeElement;
+  if (opener?.isConnected && (!active || active === document.body)) {
+    opener.focus();
+  }
+}

package/src/surfaces/navigator-dock.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioNavigatorDock",
+  "$description": "The Navigator dock's one panel host, as a Jx document over the kit. It is deliberately thin — a header naming the panel and its containment level, and one empty `[part=\"content\"]` island — because a Navigator panel is a `PanelRecord` whose `render` returns a lit template, so the BODY cannot be a document and this draws the box around it instead (studio-ui-guidelines.md §9.4). `panels/left-panel.ts` keeps every decision: which record `shell.leftTab` names, whether a context admits it, whether the panel needs a document it does not have, and what `afterRender` is handed. The body is a keyed `$map` of exactly one row, and the KEY IS THE PANEL: four Navigator panels append a mounted document of their own past lit's range inside the content box, and a host that survived a panel switch would leave the Outline standing underneath the file tree. Keying the row on the panel id is what makes switching panels destroy the box those documents are in — the same thing the old lit template bought by rebuilding its own markup, said once instead of relied upon. The region is stamped from the panel's own id, which is what makes `navigator/panel:<id>` DERIVED: renaming a panel renames its region in the same edit instead of leaving a stale selector that photographs the wrong box.",
+  "tagName": "div",
+  "attributes": {
+    "part": "navigator-dock"
+  },
+  "style": {
+    "$description": "`styles/panels.css`'s `.panel-header*`, `.panel-content` and `.panel-body` rules, keyed on `part` and carried here. `--spectrum-font-size-50` resolved only inside `<sp-theme>` and a document mounts outside it, so both 11px values are `--jx-text-sm`. The root is `display: contents` so the panel body is still `#left-panel`'s own child for layout — the shell cell is the scroller and a box between them would be a second one. And one rule is repaired on the way: the `·` between the title and the level was a `::before` on the level span, and it is drawn only when there IS a header now — the unknown-panel state has none, and a lone separator over an error message reads as a missing word.",
+    "display": "contents",
+    "& [part=\"panel-body\"]": {
+      "display": "flex",
+      "flexDirection": "column",
+      "minHeight": "0",
+      "padding": "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-level\"]": {
+      "fontSize": "var(--jx-text-sm)",
+      "color": "var(--fg-dim)",
+      "::before": {
+        "content": "\"·\"",
+        "marginRight": "var(--jx-space-2)"
+      }
+    },
+    "& [part=\"content\"]": {
+      "minHeight": "0"
+    }
+  },
+  "children": [
+    {
+      "$prototype": "Array",
+      "items": {
+        "$ref": "#/state/panels"
+      },
+      "key": {
+        "$ref": "$map/item/key"
+      },
+      "map": {
+        "tagName": "div",
+        "attributes": {
+          "part": "panel-body",
+          "data-panel": "${$map.item.key}",
+          "data-jx-region": "${$map.item.region || null}"
+        },
+        "children": [
+          {
+            "tagName": "div",
+            "attributes": {
+              "part": "header-slot",
+              "role": "none"
+            },
+            "style": {
+              "display": "contents"
+            },
+            "$switch": {
+              "$ref": "$map/item/hasHeader"
+            },
+            "cases": {
+              "true": {
+                "$description": "The fix for \"which panel am I in?\". Six of eight panels had no header at all, and the Imports panel silently changed meaning based on whether the focused document was `project.json`. Every panel now renders under its title AND its level (\"FILES · project\"), so the containment model is legible from the screen rather than only from the matrix: a badge on a `project` panel does not go away when the last tab closes, and a `document` panel says out loud that it is about the file in front of you.",
+                "tagName": "header",
+                "attributes": {
+                  "part": "header"
+                },
+                "children": [
+                  {
+                    "tagName": "span",
+                    "attributes": {
+                      "part": "header-title"
+                    },
+                    "textContent": "${$map.item.title}"
+                  },
+                  {
+                    "tagName": "span",
+                    "attributes": {
+                      "part": "header-level"
+                    },
+                    "textContent": "${$map.item.level}"
+                  }
+                ]
+              }
+            }
+          },
+          {
+            "$description": "The island, and it is empty for as long as this panel is the one showing: `panels/left-panel.ts` renders the record's own template here, and the four panels that are themselves mounted documents append past lit's range — the same seam they used when this box was a `.panel-content` lit rendered `nothing` into.",
+            "tagName": "div",
+            "attributes": {
+              "part": "content"
+            }
+          }
+        ]
+      }
+    }
+  ]
+}

package/src/surfaces/navigator-dock.ts

@@ -0,0 +1,130 @@
+/// <reference lib="dom" />
+/**
+ * The Navigator dock's panel host as a mounted document.
+ *
+ * `panels/left-panel.ts` is the flow — which record `shell.leftTab` names, whether the context
+ * admits it, whether it needs a document it has not got, and what its `afterRender` is handed — and
+ * this is the box it draws into.
+ *
+ * **One island per panel, and the key is the panel.** A Navigator panel's body is a lit template
+ * (that is what a `PanelRecord` is), so the content box stays empty here and the flow paints it
+ * (studio-ui-guidelines.md §9.4). It is a keyed `$map` row rather than a fixed element because four
+ * panels append a mounted document of their own PAST lit's range inside that box: a host that
+ * survived a panel switch would leave the Outline standing underneath the file tree, which is
+ * exactly what the old template avoided by rebuilding its own markup. Here the key says it.
+ *
+ * @docs studio/interface
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import navigatorDockDoc from "./navigator-dock.json";
+import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+import type { JxScope } from "@jxsuite/runtime/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("navigator-dock", navigatorDockDoc as unknown as JxDocument);
+
+/** The panel showing, as the document draws it. */
+export interface NavigatorPanelView {
+  /** The panel id. The row's identity — a change here rebuilds the body and its content island. */
+  key: string;
+  title: string;
+  /** The containment level, `project` or `document`. */
+  level: string;
+  /** Whether there is a header at all: an id the registry does not declare has none. */
+  hasHeader: boolean;
+  /** `navigator/panel:<id>`, or empty for a panel the registry does not declare. */
+  region: string;
+}
+
+export interface NavigatorDockValues {
+  /**
+   * The panel showing, as a list of exactly one.
+   *
+   * A list because it is the document's keyed `$map`, and the key is what makes a panel switch
+   * destroy the previous panel's content box; `shell.leftTab` always names something, so it is
+   * never empty.
+   */
+  panels: NavigatorPanelView[];
+}
+
+export interface NavigatorDockOptions {
+  /**
+   * A panel's content box, announced once per panel as it is created.
+   *
+   * @param panelId The panel the box belongs to
+   * @param host The empty `[part="content"]`
+   */
+  onContent: (panelId: string, host: HTMLElement) => void;
+}
+
+export interface NavigatorDockHandle {
+  update: (values: NavigatorDockValues) => void;
+  /** Take the document down and remove it from its container. Idempotent. */
+  dispose: () => void;
+}
+
+interface NavigatorDockScope extends Record<string, unknown>, NavigatorDockValues {}
+
+/** 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 Navigator dock into `container`, which is the shell's `#left-panel` cell.
+ *
+ * The cell is cleared first: the Navigator owns it outright, so a remount that appended would leave
+ * two panel bodies and every `querySelector` would silently pick the stale one.
+ */
+export function mountNavigatorDock(
+  container: HTMLElement,
+  values: NavigatorDockValues,
+  options: NavigatorDockOptions,
+): NavigatorDockHandle {
+  const scope = reactive<NavigatorDockScope>({ panels: values.panels }) as NavigatorDockScope;
+
+  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("navigator-dock", scope, container, {
+    onNodeCreated: (element, _path, def, state) => {
+      if (!(element instanceof HTMLElement) || partOf(def) !== "content") {
+        return;
+      }
+      const key = mapItem(state)?.["key"];
+      if (typeof key === "string") {
+        options.onContent(key, element);
+      }
+    },
+  }).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+      return;
+    }
+    mounted = surface;
+  });
+
+  return {
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+    },
+    update: (next) => {
+      scope.panels = next.panels;
+    },
+  };
+}