@jxsuite/studio 4.1.0 → 5.0.0

package/src/surfaces/pane-grid.json

@@ -0,0 +1,188 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioPaneGrid",
+  "$description": "The pane grid (studio.md §18.1): one cell per pane, with a splitter before every cell but the first. Every box here is EMPTY by design — the four inside a cell are hosts other modules fill (`panels/tab-strip.ts` the strip, `panels/jump-bar.ts` the jump bar, `panels/pane-context.ts` the chrome layer, `canvas/canvas-render.ts` the stage), and the stage is an ISLAND in the §9.4 sense: the canvas host mounts a cross-origin `<iframe>` into it, so nothing this document draws may ever go inside it. What the document owns is the STRUCTURE and the STYLE — the cell's own two-row grid, the three row-2 children that share its lower cell, and the splitter — which is `styles/shell.css`'s `.pane*` block and `styles/canvas.css`'s `.pane-stage` rule, carried here and keyed on `part`. Two things are load-bearing and easy to undo. (1) **A row that moves reloads an iframe**, so the keyed `$map` is not an optimisation: `workspace.panes[0]` is always the primary and `MAX_PANES` is 2, the key is the pane id, and the runtime's forward-cursor pass therefore never moves a kept row — gaining or losing the side pane leaves the primary's node, and the frame inside it, untouched. (2) **The splitter must sit BETWEEN two cells and inside neither**, so each row is a `display: contents` wrapper holding its own leading splitter and its cell: the wrapper generates no box, so the splitter and the two cells are the grid items of `#pane-grid` in DOM order, and a pointer landing on the splitter is in no cell at all. Every selector below is a `>` chain from the root, because a pane's stage hosts other surface documents and a bare `[part=\"row\"]` descendant rule would reach into them.",
+  "tagName": "div",
+  "attributes": {
+    "part": "grid",
+    "role": "none"
+  },
+  "style": {
+    "$description": "The pane's own layout, and the splitter's. The tracks of `#pane-grid` ITSELF are not here and must not be: the track count depends on `workspace.panes.length` and the split on `shell.paneSplit`, which is written on every `pointermove` of a drag — `panels/pane-grid.ts` writes them as one inline `grid-template-columns` on the host, so a drag moves a track edge and never a node. The splitter's own paint is not here either: `jx-split` owns the hairline, the cursors and the drag state it mirrors as `data-dragging`, so this block says only where the element is placed.",
+    "display": "contents",
+    "& > [part=\"row\"]": {
+      "$description": "One pane's row: its leading splitter and its cell, generating no box of their own so both are grid items of `#pane-grid`.",
+      "display": "contents"
+    },
+    "& > [part=\"row\"] > [part=\"splitter-slot\"]": {
+      "display": "contents"
+    },
+    "& > [part=\"row\"] > [part=\"splitter-slot\"] > jx-split": {
+      "$description": "WHERE the splitter sits, and nothing about what it looks like: the hairline, the two cursors, the hover and drag colours and the focus ring are `jx-split`'s own, and the `.dragging` class this block used to name is gone with the module that wrote it — the element mirrors its own gesture as `data-dragging` and paints itself. BOTH grid axes are `auto`: a definite row position — the `2 / 4` a column handle inherits on the APP grid, or the `1 / -1` this rule used to carry — moves the item into an earlier step of CSS Grid's auto-placement, so the splitter claimed column 1 and the two cells flowed around it into the 5px track and the second half. DOM order was already right; the placement algorithm was not reading it. `width: auto` with `justify-self: stretch` is what hands the thickness back to the TRACK `panels/pane-grid.ts` writes, so the element's own 5px default cannot disagree with the column it is placed in.",
+      "gridRow": "auto",
+      "gridColumn": "auto",
+      "justifySelf": "stretch",
+      "margin": "0",
+      "width": "auto",
+      "zIndex": "10"
+    },
+    "& > [part=\"row\"] > [part=\"pane\"]": {
+      "$description": "ONE PANE, and one COLUMN, declared. Three children name `grid-row: 2` in order to share the lower cell, and auto-placement answers that by inventing an implicit column each: the jump bar, the chrome layer and the stage lined up side by side, the stage taking a third of the pane and pinning the document to the right edge. `grid-template-columns` is what makes \"share the cell\" mean it, and every row-2 child restates `grid-column: 1` so a future fourth one cannot re-open the same hole. No unit test can see this — happy-dom does no layout, so every rect is zero — which is why the screenshot lane is what caught it.",
+      "display": "grid",
+      "gridTemplateColumns": "minmax(0, 1fr)",
+      "gridTemplateRows": "auto minmax(0, 1fr)",
+      "minWidth": "0",
+      "minHeight": "0"
+    },
+    "& > [part=\"row\"] > [part=\"pane\"] > [part=\"strip\"]": {
+      "gridRow": "1",
+      "gridColumn": "1",
+      "minHeight": "0",
+      "minWidth": "0"
+    },
+    "& > [part=\"row\"] > [part=\"pane\"] > [part=\"strip\"]:empty": {
+      "$description": "A pane with nothing to say costs no band. The strip host is empty until `panels/tab-strip.ts` mounts a document into it, and empty again the moment it disposes.",
+      "display": "none"
+    },
+    "& > [part=\"row\"] > [part=\"pane\"] > [part=\"jump\"]": {
+      "$description": "Region ⑥. Like the chrome layer below it this shares the pane's lower cell rather than owning a row, so the two bars stack OVER the stage instead of pushing it down. `align-self: start` is what keeps it the height of its own content instead of the height of the cell, so the bar never covers the stage it sits above.",
+      "gridRow": "2",
+      "gridColumn": "1",
+      "alignSelf": "start",
+      "position": "relative",
+      "zIndex": "3",
+      "minWidth": "0",
+      "maxWidth": "100%"
+    },
+    "& > [part=\"row\"] > [part=\"pane\"] > [part=\"chrome\"]": {
+      "$description": "Regions ⑦ and ⑩. The layer itself is inert and only its children take the pointer; `surfaces/pane-context.json` owns what they look like. Offset by `--jump-bar-h` for the same reason the stage is: the jump bar is stacked over this same cell, and one projection per bar is what keeps \"no tab open\" costing no dead band.",
+      "gridRow": "2",
+      "gridColumn": "1",
+      "marginTop": "var(--jump-bar-h, 0px)",
+      "position": "relative",
+      "zIndex": "2",
+      "minWidth": "0",
+      "display": "flex",
+      "flexDirection": "column",
+      "justifyContent": "space-between",
+      "pointerEvents": "none"
+    },
+    "& > [part=\"row\"] > [part=\"pane\"] > [part=\"chrome\"] > *": {
+      "pointerEvents": "auto"
+    },
+    "& > [part=\"row\"] > [part=\"pane\"] > [part=\"pane-stage\"]": {
+      "$description": "The stage: the pane's own axis (`styles/canvas.css`) over its placement in the cell (`styles/shell.css`). Offset by the SUM of the two bars stacked over this cell — `--jump-bar-h` (written by `panels/jump-bar.ts`) and `--pane-context-h` (by `panels/pane-context.ts`), both onto the CELL, which is why this reads them by cascade — so neither ever covers the document, and by zero when no tab is open, so the welcome screen does not sit under a band nothing explains. Two variables rather than one total: each bar owns its own answer, and a bar that renders nothing writes 0 without knowing the other exists.",
+      "gridRow": "2",
+      "gridColumn": "1",
+      "marginTop": "calc(var(--jump-bar-h, 0px) + var(--pane-context-h, 0px))",
+      "position": "relative",
+      "overflow": "auto",
+      "background": "var(--bg-panel)",
+      "minWidth": "0",
+      "display": "flex",
+      "gap": "var(--jx-space-6)",
+      "alignItems": "flex-start"
+    }
+  },
+  "children": [
+    {
+      "$description": "Keyed on the PANE ID, and that is the whole of §18.1 rule 1's structural half: the key is what makes the runtime MOVE a kept row rather than rebuild it, and re-parenting is not a move for an `<iframe>` — it reloads, dropping its `iframe-channel` connection, its shadow document and every `ready` panel with it. A row renders complete (its cell, its four hosts and its splitter) inside the row's own effect scope before it is inserted, so there is no frame in which a cell exists with no stage inside it.",
+      "$prototype": "Array",
+      "items": { "$ref": "#/state/rows" },
+      "key": { "$ref": "$map/item/id" },
+      "map": {
+        "tagName": "div",
+        "attributes": {
+          "part": "row",
+          "role": "none"
+        },
+        "children": [
+          {
+            "$description": "Present on every cell but the first. It is a child of the ROW rather than of either cell, so a splitter drag never reaches the cell's pane-focus listener — and it is created and destroyed with the second pane, so nothing re-inserts it while a pointer capture is live.",
+            "tagName": "div",
+            "attributes": {
+              "part": "splitter-slot",
+              "role": "none"
+            },
+            "$switch": { "$ref": "$map/item/split" },
+            "cases": {
+              "shown": {
+                "$description": "`jx-split` (ui.md §5.5), which is where `role=\"separator\"`, the tab stop, `aria-valuenow` and the whole keyboard now live. This document used to write the role on a bare div and hand the div to `ui/panel-resize.ts`, which made the pane split the one dock-sized thing in Studio a reader could not move without a mouse — an SC 2.1.1 failure with a drag handle drawn on it, and an SC 2.5.7 one besides. Every prop below is a CONSTANT except `value`: `min` and `max` are the shell's own supported range, and `gap` is the pixel floor the element converts against the track it measures itself, which is why nothing here has to be recomputed when the window resizes. `collapse` is the even split rather than the floor, because both sides of this splitter are real panes: the first Enter or double click is the 50/50 reset this gesture has always been, and the second one is the return trip it never had.",
+                "tagName": "jx-split",
+                "attributes": {
+                  "part": "splitter"
+                },
+                "$props": {
+                  "label": "Pane split",
+                  "value": { "$ref": "#/state/paneSplit" },
+                  "min": { "$ref": "#/state/splitMin" },
+                  "max": { "$ref": "#/state/splitMax" },
+                  "gap": { "$ref": "#/state/splitGap" },
+                  "collapse": { "$ref": "#/state/splitDefault" }
+                },
+                "oninput": {
+                  "$prototype": "Function",
+                  "body": [
+                    {
+                      "operator": "call",
+                      "target": { "$ref": "#/state/move" },
+                      "value": [{ "$ref": "event#/target/value" }]
+                    }
+                  ]
+                },
+                "onchange": {
+                  "$prototype": "Function",
+                  "body": [
+                    {
+                      "operator": "call",
+                      "target": { "$ref": "#/state/settle" },
+                      "value": []
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          {
+            "$description": "One pane's cell. `pane.<id>` goes on the STAGE and `pane.<id>/tabs` on the strip, never on this element: nine shots crop `pane.primary` meaning \"the canvas\", and moving the id up one level would silently widen all nine to include the strip and the two bars, which no gate can tell from an intended crop.",
+            "tagName": "div",
+            "attributes": {
+              "part": "pane",
+              "data-pane-id": "${$map.item.id}"
+            },
+            "children": [
+              {
+                "tagName": "div",
+                "attributes": {
+                  "part": "strip",
+                  "data-jx-region": "${$map.item.stripRegion}"
+                }
+              },
+              {
+                "$description": "The jump bar and the context bar are HANDED this box rather than resolving a region into it. They cannot resolve one the way the strip does: nothing inside the strip re-stamps `pane.<id>/tabs`, while both bars stamp `pane.<id>/jump` and `pane.<id>/context` on markup they render INSIDE these two divs — so a region on the wrapper as well would put the same id on two nested elements, and `resolveRegion` takes the LAST match. Sixty shots crop `pane.primary/context`; a second, larger element carrying it is a silently widened crop.",
+                "tagName": "div",
+                "attributes": {
+                  "part": "jump"
+                }
+              },
+              {
+                "tagName": "div",
+                "attributes": {
+                  "part": "chrome"
+                }
+              },
+              {
+                "$description": "Drawn EMPTY and left empty. `canvas/canvas-render.ts` is this element's render root and `canvas/iframe-host.ts` mounts the artboards' iframes into it; a node cannot have two owners of its child list.",
+                "tagName": "div",
+                "attributes": {
+                  "part": "pane-stage",
+                  "data-jx-region": "${$map.item.region}"
+                }
+              }
+            ]
+          }
+        ]
+      }
+    }
+  ]
+}

package/src/surfaces/pane-grid.ts

@@ -0,0 +1,250 @@
+/// <reference lib="dom" />
+/**
+ * The pane grid, as a mounted document — the mount seam, and nothing else.
+ *
+ * `pane-grid.json` is the structure and the style: the cell's own two-row grid, the four empty
+ * boxes inside it, the splitter between two cells. `panels/pane-grid.ts` is the flow — which panes
+ * exist, what a cell's stage is furnished with, in what order a departing cell is taken apart, and
+ * what the grid's own tracks are. This module is the seam between them: one reactive scope holding
+ * the projected rows, one document mounted into `#pane-grid`, and an `update()` that ASSIGNS.
+ *
+ * **Every box the document draws is an island's host** (specs/studio-ui-guidelines.md §9.4), which
+ * is why the whole of this file's interface is `onNodeCreated`. A cell's four boxes are announced
+ * as they are CREATED — one reconcile step before the row is in the page, so the flow's stage
+ * furnishing, the two bars' mounts and the pane-focus listener are all in place while the cell is
+ * still detached (§18.1 rule 1).
+ *
+ * **The pane-focus listener is attached HERE rather than declared in the document**, and that is a
+ * schema gap rather than a preference: a document's `on*` key binds through `addEventListener` with
+ * no options, so there is no way to say CAPTURE. The listener has to be capture-phase — a control
+ * inside a cell that stops propagation would otherwise silently keep the keyboard in the other pane
+ * — so the flow adds it to the cell element it is handed. See {@link PaneGridActions.cellPart}.
+ *
+ * @docs studio/interface
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import paneGridDoc from "./pane-grid.json";
+import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+import type { JxScope } from "@jxsuite/runtime/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("pane-grid", paneGridDoc as unknown as JxDocument);
+
+/**
+ * The `part` a pane's CELL carries.
+ *
+ * `panels/jump-bar.ts` and `panels/pane-context.ts` both write a `--*-h` custom property onto the
+ * cell so the stage can read it back by cascade, and each is handed a box inside the cell rather
+ * than the cell itself — so both resolve it with {@link PANE_SELECTOR}. It replaces a `.pane`
+ * class: a converted surface emits none, and a `part` is the hook a document offers instead.
+ */
+export const PANE_PART = "pane";
+
+/**
+ * The `part` a pane's STAGE carries — the canvas's host, and the id nine screenshots crop.
+ *
+ * `pane-stage` rather than `stage`, and the qualifier is load-bearing: `surfaces/canvas-stage.json`
+ * mounts INTO this box and its own root is `part="stage"`, as are the media pane's and the git
+ * panel's. This name is resolved with `closest()` from outside the surface, so it has to be one no
+ * other document can answer — see the surface's own test.
+ */
+export const STAGE_PART = "pane-stage";
+
+/** `closest()` from anything inside a cell to the cell. */
+export const PANE_SELECTOR = `[part="${PANE_PART}"]`;
+
+/**
+ * `closest()` from an event target to the stage it happened in.
+ *
+ * `editor/shortcuts.ts`'s ctrl-wheel guard is the one reader: "everywhere that is not A stage" has
+ * as many answers as there are panes, so it asks the element rather than a registry.
+ */
+export const STAGE_SELECTOR = `[part="${STAGE_PART}"]`;
+
+/** The five boxes a cell is made of, in the order the document draws them. */
+export type PaneCellPart = "pane" | "strip" | "jump" | "chrome" | "stage";
+
+const CELL_PARTS: ReadonlyMap<string, PaneCellPart> = new Map([
+  ["pane", "pane"],
+  ["strip", "strip"],
+  ["jump", "jump"],
+  ["chrome", "chrome"],
+  ["pane-stage", "stage"],
+]);
+
+/**
+ * One row of the grid: a pane, and whether a splitter leads it.
+ *
+ * Every field is a finished value. The document asks no question about a pane — not which index it
+ * is at, not how many there are — so a projection cannot disagree with what is drawn.
+ */
+export interface PaneGridRow extends Record<string, unknown> {
+  /** The pane id. The repeater's key, and what every action is addressed with. */
+  id: string;
+  /** `"shown"` for every row but the first. The `$switch` the leading splitter hangs off. */
+  split: "hidden" | "shown";
+  /** `pane.<id>` — stamped on the STAGE, because that is what the shots crop. */
+  region: string;
+  /** `pane.<id>/tabs` — stamped on the strip host. */
+  stripRegion: string;
+}
+
+/**
+ * The splitter's constants and its opening position — everything `jx-split` is handed.
+ *
+ * It arrives from the FLOW rather than being read here, because every number in it belongs to a
+ * module this one deliberately does not import: `min` and `max` are `shell.ts`'s supported range
+ * and `collapse` its default split, and `gap` is the pane grid's own idea of a usable pane. This
+ * module is the seam between the document and the flow and knows nothing about either.
+ */
+export interface PaneGridSplit {
+  /** Where the splitter sits: the primary pane's share of the grid. */
+  value: number;
+  /** The smallest share the primary may have. */
+  min: number;
+  /** The largest. */
+  max: number;
+  /** The smallest either pane may be dragged to, in PIXELS — the element converts it itself. */
+  gap: number;
+  /** What Enter and a double click move to, and back from. */
+  collapse: number;
+}
+
+/** What the flow wants to be told about. Read once, when the scope is made. */
+export interface PaneGridActions {
+  /**
+   * One of a cell's five boxes exists, detached and empty.
+   *
+   * Called once per box per cell, in document order (`pane` first), while the row is still inside
+   * the runtime's own render pass. The flow builds its record, furnishes the stage and adds the
+   * cell's capture-phase `pointerdown` listener from here.
+   */
+  cellPart: (paneId: string, part: PaneCellPart, element: HTMLElement) => void;
+  /**
+   * The splitter moved, and is still moving: once per `pointermove` of a drag, and once per key.
+   *
+   * There is nothing to wire and nothing to un-wire any more. `jx-split` owns the gesture, the
+   * capture and the keyboard, and reports the value it has already bounded — so this is the whole
+   * of the flow's part in a drag, and the document is not touched by one at all.
+   */
+  move: (value: number) => void;
+  /** The gesture ended, or a key committed. Persist once. */
+  settle: () => void;
+}
+
+export interface PaneGridSurface {
+  /** Resolves once the first projection is in the document. */
+  ready: Promise<void>;
+  /**
+   * Bring the standing document up to date. An assignment; the mount is never rebuilt.
+   *
+   * The split is re-asserted HERE, on a pane-set change, and nowhere else — which is what keeps a
+   * drag clear of the document entirely. During one the element is the single writer of its own
+   * position and the flow only mirrors it into `shell`; the scope catches up the next time the grid
+   * gains or loses a pane, which is the only moment anything else could have moved it.
+   */
+  update: (rows: PaneGridRow[], split: number) => void;
+  /** Take the document down and give `#pane-grid` back empty. Idempotent. */
+  dispose: () => void;
+}
+
+/** The scope `pane-grid.json` reads. */
+interface PaneGridScope extends Record<string, unknown> {
+  rows: PaneGridRow[];
+  /** `jx-split`'s `value`. */
+  paneSplit: number;
+  splitMin: number;
+  splitMax: number;
+  splitGap: number;
+  /** `jx-split`'s `collapse`. */
+  splitDefault: number;
+  move: (value: number) => void;
+  settle: () => 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 = typeof def === "string" ? undefined : def.attributes?.["part"];
+  return typeof part === "string" ? part : "";
+}
+
+/**
+ * The pane a created node belongs to, read from the row scope the runtime renders it with.
+ *
+ * NOT from `data-pane-id`: `onNodeCreated` fires before `applyAttributes`, so at this point the
+ * element carries nothing at all. `$map.item` is the row the runtime is building, which is the same
+ * object the projection put in `rows`.
+ */
+function paneOf(state: JxScope | undefined): string {
+  const row = (state?.["$map"] as { item?: { id?: unknown } } | undefined)?.item;
+  return typeof row?.id === "string" ? row.id : "";
+}
+
+/**
+ * Mount the grid into `host`, wired to `actions`.
+ *
+ * The host is CLEARED first: `#pane-grid` belongs to this document alone, and anything already in
+ * it is a previous mount that a project switch forgot to take down.
+ *
+ * @param {HTMLElement} host `#pane-grid`.
+ * @param {PaneGridRow[]} rows What to draw on the first paint.
+ * @param {PaneGridSplit} split The splitter's constants, and where it opens.
+ * @param {PaneGridActions} actions What to tell the flow about. Read once.
+ * @returns {PaneGridSurface}
+ */
+export function mountPaneGridSurface(
+  host: HTMLElement,
+  rows: PaneGridRow[],
+  split: PaneGridSplit,
+  actions: PaneGridActions,
+): PaneGridSurface {
+  host.replaceChildren();
+  const scope = reactive<PaneGridScope>({
+    move: actions.move,
+    paneSplit: split.value,
+    rows,
+    settle: actions.settle,
+    splitDefault: split.collapse,
+    splitGap: split.gap,
+    splitMax: split.max,
+    splitMin: split.min,
+  }) as PaneGridScope;
+
+  let mounted: SurfaceHandle | null = null;
+  let disposed = false;
+  const ready = mountSurface("pane-grid", scope, host, {
+    /* No `instanceof` narrowing and no "is there a pane" guard, and both absences are structural.
+       `pane-grid.json` draws no text and no `textContent`, so every node the runtime reports here
+       is an element; and the five cell parts exist only inside the repeater's rows, so a `$map`
+       scope is always there to name the pane. A guard on either would be a branch the document
+       cannot reach — which is a line no test could ever cover, which is a claim nothing checks. */
+    onNodeCreated: (element, _path, def, state) => {
+      const cellPart = CELL_PARTS.get(partOf(def));
+      if (cellPart) {
+        actions.cellPart(paneOf(state), cellPart, element as HTMLElement);
+      }
+    },
+  }).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+      return;
+    }
+    mounted = surface;
+  });
+
+  return {
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+      host.replaceChildren();
+    },
+    ready,
+    update(next, value) {
+      scope.rows = next;
+      scope.paneSplit = value;
+    },
+  };
+}