@jxsuite/studio 4.0.0 → 5.0.0

package/src/surfaces/shell.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioShell",
+  "$description": "The application frame: the one definition of what Studio's shell IS. Every cell here is a HOST another surface mounts into, and each is addressed by id because TypeScript adopts it (`store.ts`'s initShellRefs, `ui/panel-resize.ts`'s handles) \u2014 so the ids are a contract rather than styling, which is also why this document carries no style of its own: the frame must be laid out by the first paint, so its rules are the generated `styles/shell-frame.css` (specs/studio-ui-guidelines.md \u00a71.1).",
+  "tagName": "div",
+  "attributes": {
+    "id": "app"
+  },
+  "children": [
+    {
+      "tagName": "div",
+      "attributes": {
+        "id": "toolbar",
+        "data-jx-region": "commandbar"
+      }
+    },
+    {
+      "tagName": "div",
+      "$description": "The PANE GRID (studio.md \u00a718.1). One cell per pane, each holding that pane's own strip, jump bar, chrome layer and stage \u2014 the four surfaces that used to be flat siblings of THIS grid, which is to say application rows that only ever described one pane. There is nothing to see here in markup: panels/pane-grid.ts reconciles the cells against workspace.panes, because how many there are is a fact about the workspace and a single div can only ever be one of them.",
+      "attributes": {
+        "id": "pane-grid"
+      }
+    },
+    {
+      "tagName": "div",
+      "attributes": {
+        "id": "activity-bar",
+        "data-jx-region": "rail"
+      }
+    },
+    {
+      "tagName": "div",
+      "attributes": {
+        "id": "left-panel",
+        "data-jx-region": "navigator"
+      }
+    },
+    {
+      "tagName": "jx-split",
+      "attributes": {
+        "id": "resize-left",
+        "class": "resize-handle"
+      },
+      "$description": "`jx-split` (ui.md \u00a75.5): role=\"separator\", a tab stop, aria-valuenow and its own arrow keys, Home/End and Enter \u2014 the door this handle owed a keyboard user, which a bare div driven by pointer events could not give (SC 2.1.1). Its share of the app box, its bounds and its reset point are all written by `ui/panel-resize.ts`, because the frame carries no scope: a dock is sized in PIXELS and persisted that way, so the px\u2194share arithmetic \u2014 and the window-resize listener that keeps it honest \u2014 is that adapter's, in one place for all three.",
+      "$props": {
+        "orientation": "vertical",
+        "label": "Resize the Navigator"
+      }
+    },
+    {
+      "tagName": "jx-split",
+      "$description": "The Bottom dock (\u2318J). It sits in the PANE's column, under the stage and above the status bar, so opening it never narrows the Navigator or the Inspector (studio.md \u00a712 region \u246a). Its handle resizes on the other axis; panels/bottom-dock.ts stamps dock.bottom on this host while it is open, and nothing while it is closed. `jx-split` (ui.md \u00a75.5): role=\"separator\", a tab stop, aria-valuenow and its own arrow keys, Home/End and Enter \u2014 the door this handle owed a keyboard user, which a bare div driven by pointer events could not give (SC 2.1.1). Its share of the app box, its bounds and its reset point are all written by `ui/panel-resize.ts`, because the frame carries no scope: a dock is sized in PIXELS and persisted that way, so the px\u2194share arithmetic \u2014 and the window-resize listener that keeps it honest \u2014 is that adapter's, in one place for all three.",
+      "attributes": {
+        "id": "resize-bottom",
+        "class": "resize-handle resize-handle-row"
+      },
+      "$props": {
+        "orientation": "horizontal",
+        "label": "Resize the Bottom dock"
+      }
+    },
+    {
+      "tagName": "div",
+      "attributes": {
+        "id": "bottom-dock"
+      }
+    },
+    {
+      "tagName": "jx-split",
+      "attributes": {
+        "id": "resize-right",
+        "class": "resize-handle"
+      },
+      "$description": "`jx-split` (ui.md \u00a75.5): role=\"separator\", a tab stop, aria-valuenow and its own arrow keys, Home/End and Enter \u2014 the door this handle owed a keyboard user, which a bare div driven by pointer events could not give (SC 2.1.1). Its share of the app box, its bounds and its reset point are all written by `ui/panel-resize.ts`, because the frame carries no scope: a dock is sized in PIXELS and persisted that way, so the px\u2194share arithmetic \u2014 and the window-resize listener that keeps it honest \u2014 is that adapter's, in one place for all three.",
+      "$props": {
+        "orientation": "vertical",
+        "label": "Resize the Inspector"
+      }
+    },
+    {
+      "tagName": "div",
+      "$description": "The Inspector dock. Four tabs \u2014 Content \u00b7 Style \u00b7 Logic \u00b7 Assistant (studio.md \u00a712 region \u2468) \u2014 all inside this one host.",
+      "attributes": {
+        "id": "right-panel",
+        "data-jx-region": "inspector"
+      }
+    },
+    {
+      "tagName": "div",
+      "$description": "The app's only status channel: announce what lands in it (studio.md \u00a712 region \u246b).",
+      "attributes": {
+        "id": "statusbar",
+        "role": "status",
+        "aria-live": "polite",
+        "data-jx-region": "statusbar"
+      }
+    }
+  ]
+}

package/src/surfaces/shell.ts

@@ -0,0 +1,30 @@
+/**
+ * The shell surface: the application frame as a Jx document.
+ *
+ * It is the one surface with no scope and no adapter state, because the frame is not a projection
+ * of anything — it is the set of HOSTS every other surface mounts into. What it does have is a
+ * boot-order contract the others do not: `store.ts`'s `initShellRefs` and `ui/panel-resize.ts` read
+ * these cells out of the document by id, so the mount has to be awaited before either runs.
+ *
+ * The frame's STYLE is not here. It is `styles/shell-frame.css`, generated from
+ * `styles/shell-frame.json`, because the frame is what the first paint lays out and an adopted
+ * sheet arrives after it (specs/studio-ui-guidelines.md §1.1).
+ *
+ * @docs studio/interface
+ */
+
+import { mountSurface, registerSurface } from "../ui/surface";
+import shellDoc from "./shell.json";
+import type { SurfaceHandle } from "../ui/surface";
+import type { JxDocument } from "@jxsuite/schema/types";
+
+registerSurface("shell", shellDoc as unknown as JxDocument);
+
+/**
+ * Render the frame into `host`, and resolve once its cells exist.
+ *
+ * @param host Where `#app` goes — the theme wrapper at boot.
+ */
+export function mountShellSurface(host: HTMLElement): Promise<SurfaceHandle> {
+  return mountSurface("shell", {}, host);
+}

package/src/surfaces/slash-menu.json

@@ -0,0 +1,180 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioSlashMenu",
+  "$description": "The slash menu: the element-insertion list that hangs under the caret. It is a LISTBOX rather than a `jx-menu`, and that is the one thing about this surface worth knowing — the panel must not take the keyboard, because the caret it is filtering for is in the canvas (often in the iframe realm), and every character the author types after the `/` has to keep landing there. A menu owns DOM focus by contract; this panel marks its active row and leaves the caret where it was. The rows are the kit's `jx-listbox` and `jx-option`, which is what makes that expressible rather than hand-rolled: a `jx-listbox` has no tab stop and never calls `focus()`, and the highlight is ONE string — the listbox's `active`, the id its owning field points `aria-activedescendant` at — instead of a per-row comparison the field and the rows could each answer differently. When the menu is opened BY NAME rather than by a slash there is no caret to protect, so it grows a filter field of its own and that field is what carries `aria-activedescendant`.",
+  "tagName": "jx-popover",
+  "$props": {
+    "label": "Insert element",
+    "x": {
+      "$ref": "#/state/x"
+    },
+    "y": {
+      "$ref": "#/state/y"
+    }
+  },
+  "children": [
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "body"
+      },
+      "style": {
+        "display": "flex",
+        "flexDirection": "column",
+        "minWidth": "220px",
+        "maxHeight": "320px",
+        "minHeight": "0",
+        "fontFamily": "var(--jx-font-sans)",
+        "fontSize": "var(--jx-text-md)",
+        "& [part=\"filter\"]": {
+          "$description": "Borderless inside a panel that already draws a frame: a second box around the field would only be a box inside a box. The keyboard ring is given back explicitly, because a reader who arrives here by Tab has nothing else to go on.",
+          "display": "block",
+          "width": "100%",
+          "boxSizing": "border-box",
+          "flex": "0 0 auto",
+          "padding": "var(--jx-space-2) var(--jx-space-3)",
+          "border": "none",
+          "borderBottom": "1px solid var(--jx-border)",
+          "outline": "none",
+          "background": "transparent",
+          "color": "inherit",
+          "font": "inherit",
+          "::placeholder": {
+            "color": "var(--jx-fg-muted)"
+          },
+          ":focus-visible": {
+            "outline": "var(--jx-focus-ring)",
+            "outlineOffset": "-2px"
+          }
+        },
+        "& [part=\"list\"]": {
+          "$description": "One declaration, because the list is a `jx-listbox` now and the element already draws itself: the scroll, the `min-block-size: 0` that lets it, the row rules, the highlight, the group headings and the empty sentence all live in its own definition. What is left is the one thing only this panel knows — that the list is the part of the body that gives.",
+          "flex": "1"
+        }
+      },
+      "children": [
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "filter-slot",
+            "role": "none"
+          },
+          "style": {
+            "display": "contents"
+          },
+          "$switch": {
+            "$ref": "#/state/showFilter"
+          },
+          "cases": {
+            "true": {
+              "tagName": "input",
+              "attributes": {
+                "part": "filter",
+                "type": "text",
+                "role": "combobox",
+                "autocomplete": "off",
+                "aria-controls": "slash-menu-listbox",
+                "aria-expanded": "${state.expanded ? 'true' : 'false'}",
+                "aria-activedescendant": "${state.activeId || null}",
+                "aria-autocomplete": "list",
+                "aria-label": "Filter elements",
+                "placeholder": "Filter…"
+              },
+              "value": {
+                "$ref": "#/state/filter"
+              },
+              "oninput": {
+                "$prototype": "Function",
+                "body": [
+                  {
+                    "operator": "call",
+                    "target": {
+                      "$ref": "#/state/input"
+                    },
+                    "value": [
+                      {
+                        "$ref": "event#/target/value"
+                      }
+                    ]
+                  }
+                ]
+              }
+            }
+          }
+        },
+        {
+          "tagName": "jx-listbox",
+          "attributes": {
+            "part": "list",
+            "id": "slash-menu-listbox"
+          },
+          "$props": {
+            "label": "Elements",
+            "active": {
+              "$ref": "#/state/activeId"
+            }
+          },
+          "onselect": {
+            "$ref": "#/state/pick"
+          },
+          "children": [
+            {
+              "tagName": "div",
+              "attributes": {
+                "part": "empty-slot",
+                "role": "none"
+              },
+              "$switch": {
+                "$ref": "#/state/isEmpty"
+              },
+              "cases": {
+                "true": {
+                  "tagName": "div",
+                  "attributes": {
+                    "part": "empty"
+                  },
+                  "textContent": "No matches"
+                }
+              }
+            },
+            {
+              "$prototype": "Array",
+              "items": {
+                "$ref": "#/state/rows"
+              },
+              "key": {
+                "$ref": "$map/item/key"
+              },
+              "map": {
+                "tagName": "jx-option",
+                "attributes": {
+                  "part": "option",
+                  "id": "slash-menu-option-${$map.index}",
+                  "value": "${$map.item.key}",
+                  "label": "${$map.item.label}",
+                  "description": "${$map.item.description}"
+                },
+                "onmouseenter": {
+                  "$prototype": "Function",
+                  "body": [
+                    {
+                      "operator": "call",
+                      "target": {
+                        "$ref": "#/state/hover"
+                      },
+                      "value": [
+                        {
+                          "$ref": "$map/index"
+                        }
+                      ]
+                    }
+                  ]
+                }
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/src/surfaces/slash-menu.ts

@@ -0,0 +1,272 @@
+/// <reference lib="dom" />
+/**
+ * The slash menu, as a Jx document over the kit — the mount seam, and nothing else.
+ *
+ * `slash-menu.json` is the markup, the ARIA and the style; `editor/slash-menu.ts` is the flow —
+ * which commands are on offer, what the filter matches, which row is active and what a pick does.
+ *
+ * **It is a listbox, and it is deliberately not `surfaces/menu.json`.** Every other Studio menu is
+ * that surface, and the rule is that a second list of actions is a defect (§12.5) — but the two
+ * differ on the one thing a menu cannot give up. `jx-menu` owns the keyboard: showing it moves the
+ * caret onto its first row, which is the whole point of a roving-focus menu. This panel filters a
+ * caret that is somewhere else — inside the canvas's `contenteditable`, and usually inside the
+ * canvas IFRAME — and every character typed after the `/` has to keep landing there, so the panel
+ * that takes the keyboard is the panel that ends the interaction it exists to serve. What is left
+ * once focus is off the table is a combobox popup: `role="listbox"`, an active row marked with
+ * `aria-selected`, and an external driver for the arrow keys.
+ *
+ * The one case with no caret to protect is the menu opened BY NAME — `insert.openSlashMenu`, the
+ * palette, a toolbar button — and that one grows a filter field of its own, which is the element
+ * that carries `aria-activedescendant` and makes the whole thing announce properly.
+ *
+ * **The list is the kit's `jx-listbox`, and that is what makes "owned by nothing at all" sayable.**
+ * The element has no `tabindex` and never calls `focus()`, so the no-focus mode is its contract
+ * rather than this panel's discipline — and the highlight is ONE string, the listbox's `active`,
+ * which is the same id the filter field puts in `aria-activedescendant`. The sidecar is the single
+ * writer of every row's `selected`, so the per-row `aria-selected` comparison this document used to
+ * carry, and the `data-selected` beside it, are gone: the field and the rows can no longer answer
+ * "which row is active" differently, because only one of them is asked. Scrolling that row back
+ * into view went with them — it is a measurement, so it belongs in the sidecar, and this adapter no
+ * longer offers a `revealActive` for the flow to remember to call.
+ *
+ * The panel is a `jx-popover`, so light dismissal, Escape on the topmost popover and the top layer
+ * are the platform's; the hand-rolled `mousedown` capture listener that used to do the first of
+ * those is gone with the Spectrum markup.
+ *
+ * @docs studio/editing/slash-commands
+ */
+
+import { reactive } from "../reactivity";
+import { clearLayerSlot, getLayerSlot } from "../ui/layers";
+import { mountSurface, registerSurface } from "../ui/surface";
+import { overlayRegion, REGION_ATTR } from "../ui/regions";
+import slashMenuDoc from "./slash-menu.json";
+import type { JxDocument } from "@jxsuite/schema/types";
+import type { JxScope } from "@jxsuite/runtime/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("slash-menu", slashMenuDoc as unknown as JxDocument);
+
+/** The popover slot id; the region is `overlay.menu:slash-menu`, which is what the shots crop. */
+const SLOT = "slash-menu";
+
+/** One offer, as the document reads it. */
+export interface SlashMenuRow extends Record<string, unknown> {
+  /**
+   * The element's tag — unique in the list, so it is the repeater's key AND the row's `value`,
+   * which is what a picked row names in its `select` event.
+   */
+  key: string;
+  label: string;
+  /** A muted note at the end of the row. Empty draws no box: `jx-option` hides its own part. */
+  description: string;
+}
+
+/** What the panel is showing right now. */
+export interface SlashMenuView {
+  /** Where the panel's inline-start edge sits, in viewport pixels. */
+  x: number;
+  /** Where its block-start edge sits. */
+  y: number;
+  /** Whether the panel carries a filter field of its own — true only when opened by name. */
+  showFilter: boolean;
+  /** What that field contains. */
+  filter: string;
+  rows: SlashMenuRow[];
+  /** The highlighted row, as an index into {@link SlashMenuView.rows}. */
+  activeIndex: number;
+}
+
+/** What a gesture on the panel asks of the flow. Read once, when the scope is made. */
+export interface SlashMenuActions {
+  /** The filter field changed. */
+  input: (value: string) => void;
+  /** A row was clicked. */
+  activateRow: (index: number) => void;
+  /** The pointer entered a row; the highlight follows it. */
+  hover: (index: number) => void;
+  /** The panel closed on its own — light dismissal, or Escape reaching the platform. */
+  dismissed: () => void;
+}
+
+export interface SlashMenuSurface {
+  /** The layer slot the panel is mounted in. */
+  readonly host: HTMLElement;
+  /** Settles once the document is mounted and the panel shown, or it was closed first. */
+  readonly ready: Promise<void>;
+  /** Bring the standing panel up to date. An assignment; the mount is never rebuilt. */
+  readonly update: (view: SlashMenuView) => void;
+  /** Put the caret in the filter field, when there is one. */
+  readonly focusFilter: () => void;
+  /** Close the panel now; the slot is emptied before this returns. */
+  readonly close: () => void;
+}
+
+/** The scope `slash-menu.json` reads. */
+interface SlashMenuScope extends Record<string, unknown> {
+  x: number;
+  y: number;
+  showFilter: boolean;
+  filter: string;
+  rows: SlashMenuRow[];
+  /**
+   * The active row's id — the ONE string the highlight is written as. The listbox turns it into a
+   * row's `selected`, and the filter field, when there is one, puts the same string in its
+   * `aria-activedescendant`.
+   */
+  activeId: string;
+  isEmpty: boolean;
+  expanded: boolean;
+  input: (value: string) => void;
+  /** A row dispatched `select`; its detail is the row's tag. */
+  pick: (scope: JxScope, event: Event) => void;
+  /**
+   * The pointer entered a row. This one still names a POSITION where {@link SlashMenuScope.pick}
+   * names a tag, and the asymmetry is the two gestures' own: a hover is handled where the repeater
+   * is drawing, with `$map.index` in hand, and a pick arrives at the listbox as a bubbled event
+   * with no repeater around it.
+   */
+  hover: (index: number) => void;
+}
+
+type PopoverElement = HTMLElement & {
+  open?: boolean;
+  showPopover: (options?: { source?: Element }) => void;
+  hidePopover: () => void;
+};
+
+/**
+ * The active row's id, or the empty string when no row is.
+ *
+ * One function, because the two readers of that id — the listbox that moves the highlight and the
+ * filter field that announces it — must be handed the same string, and the row itself computes it
+ * from the repeater's own `$map.index`. An out-of-range index (an empty result list, which the flow
+ * still counts from zero) names no row, and the empty string is how the listbox is told that.
+ */
+function activeIdOf(view: SlashMenuView): string {
+  return view.rows[view.activeIndex] ? `slash-menu-option-${view.activeIndex}` : "";
+}
+
+/**
+ * Open the panel.
+ *
+ * @param {SlashMenuView} view What it shows to begin with.
+ * @param {SlashMenuActions} actions What each gesture does.
+ * @param {Element | null} [anchor] The element it was opened from, when the caller has one in this
+ *   realm. It becomes the popover's invoker, so the platform restores focus to it on close and a
+ *   press on it does not light-dismiss the panel its own click is about to open.
+ * @returns {SlashMenuSurface}
+ */
+export function openSlashMenuSurface(
+  view: SlashMenuView,
+  actions: SlashMenuActions,
+  anchor?: Element | null,
+): SlashMenuSurface {
+  const slot = getLayerSlot("popover", SLOT);
+  const controller = new AbortController();
+  let panel: PopoverElement | null = null;
+  let mounted: SurfaceHandle | null = null;
+  let closed = false;
+
+  const scope = reactive<SlashMenuScope>({
+    activeId: activeIdOf(view),
+    expanded: view.rows.length > 0,
+    filter: view.filter,
+    hover: (index: number) => {
+      actions.hover(index);
+    },
+    input: (value: string) => {
+      actions.input(value);
+    },
+    isEmpty: view.rows.length === 0,
+    pick: (_scope: JxScope, event: Event) => {
+      /* A picked row names ITSELF — `select`'s detail is the row's `value`, which is the tag — so
+         one bubbling handler on the listbox replaces a closure per row, and the position the flow
+         wants is resolved here against the list the panel is showing rather than baked into the
+         row when it was drawn. */
+      const tag = String((event as CustomEvent<unknown>).detail);
+      const index = scope.rows.findIndex((row) => row.key === tag);
+      if (index !== -1) {
+        actions.activateRow(index);
+      }
+    },
+    rows: [...view.rows],
+    showFilter: view.showFilter,
+    x: view.x,
+    y: view.y,
+  }) as SlashMenuScope;
+
+  const finish = (fromPlatform: boolean): void => {
+    if (closed) {
+      return;
+    }
+    closed = true;
+    controller.abort();
+    mounted?.dispose();
+    mounted = null;
+    clearLayerSlot("popover", SLOT);
+    if (fromPlatform) {
+      actions.dismissed();
+    }
+  };
+
+  const ready = (async () => {
+    const surface = await mountSurface("slash-menu", scope, slot, { signal: controller.signal });
+    if (controller.signal.aborted) {
+      return;
+    }
+    mounted = surface;
+    panel = surface.root as PopoverElement;
+    /* The region rides on the PANEL as well as on the slot `getLayerSlot` stamped: a popover is
+       `position: fixed` in the top layer, so the slot around it has a zero-height box and the
+       screenshots lane refuses it ("has an empty box"). Both carry the id, and the measurement
+       takes the last match in document order, which is the panel. */
+    panel.setAttribute(REGION_ATTR, overlayRegion("popover", SLOT));
+    panel.addEventListener("toggle", (event) => {
+      if ((event as { newState?: string }).newState === "closed") {
+        finish(true);
+      }
+    });
+    // A custom element connects asynchronously: `jx-ready` is the panel saying its `popover`
+    // Attribute is on and it may be shown.
+    if (!panel.hasAttribute("popover")) {
+      await new Promise<void>((resolve) => {
+        panel!.addEventListener("jx-ready", () => resolve(), { once: true });
+      });
+    }
+    if (controller.signal.aborted) {
+      return;
+    }
+    panel.showPopover(anchor instanceof HTMLElement ? { source: anchor } : undefined);
+  })();
+
+  return {
+    close: () => {
+      if (closed) {
+        return;
+      }
+      if (panel?.open) {
+        panel.hidePopover();
+      }
+      finish(false);
+    },
+    focusFilter: () => {
+      slot.querySelector<HTMLInputElement>('[part="filter"]')?.focus();
+    },
+    host: slot,
+    ready,
+    update: (next) => {
+      if (closed) {
+        return;
+      }
+      scope.x = next.x;
+      scope.y = next.y;
+      scope.showFilter = next.showFilter;
+      scope.filter = next.filter;
+      scope.rows = [...next.rows];
+      scope.activeId = activeIdOf(next);
+      scope.isEmpty = next.rows.length === 0;
+      scope.expanded = next.rows.length > 0;
+    },
+  };
+}