@jxsuite/studio 6.1.2 → 8.0.1

package/src/editor/shortcuts.ts

@@ -528,15 +528,15 @@ function cycleRegion(direction: 1 | -1): void {
   }
 }
 
-// ─── Panel and inspector focus (⌘1–8, ⌘⇧1–4) ─────────────────────────────────
+// ─── Panel and inspector focus (`panel.focus.*`, ⌘⇧1–4) ──────────────────────
 
 /**
  * Toggle-FOCUS, not toggle-visible.
  *
- * ⌘1 from the canvas reveals Files and puts the caret in it; ⌘1 again — with Files already focused
- * — collapses the dock and hands the caret back to the pane. The distinction matters because the
- * common case is "take me there", and a toggle-visible binding makes that a coin flip on whichever
- * panel happened to be showing.
+ * `Show Files` from the canvas reveals Files and puts the caret in it; running it again — with
+ * Files already focused — collapses the dock and hands the caret back to the pane. The distinction
+ * matters because the common case is "take me there", and a toggle-visible binding makes that a
+ * coin flip on whichever panel happened to be showing.
  *
  * Every panel this can be handed lives in the Navigator. The roster is the rail plus the rail-less
  * NAVIGATOR panels (`panels/navigator-panels.ts`), so a Bottom-dock record cannot reach here — the
@@ -546,14 +546,14 @@ function cycleRegion(direction: 1 | -1): void {
  */
 function focusPanel(panelId: string): void {
   /* THE DOOR. `shell.ts`'s `NAVIGATOR_PANEL_IDS` docstring says the command is what refuses an
-     undeclared id, "at the one door a caller comes through" — this is that door for ⌘1–8, and it
+     undeclared id, "at the one door a caller comes through" — this is that door for `panel.focus.*`, and it
      was the only one of three doors that had no lock. `setActivityTab` now takes a
      `NavigatorPanelId`, so the roster's `string` has to be narrowed somewhere; narrowing HERE keeps
      `commands/defaults.ts` free of shell types, which is the property that lets three CI checks
      load the command set in a bare Bun process.
 
      A throw rather than a silent return: `tests/navigator-panels.test.ts` asserts the enum and the
-     registry agree, so this is unreachable while that passes, and a chord that quietly does nothing
+     registry agree, so this is unreachable while that passes, and a command that quietly does nothing
      is precisely the defect this change is closing. */
   const id = requireNavigatorPanelId(panelId, "panel.focus");
   const alreadyThere =
@@ -990,7 +990,6 @@ export function initShortcuts(registry: CommandRegistry, stageContext: StageCont
  * scrolled with the wheel at all.
  *
  * - `grid` — a Tabulator viewport with its own virtual scroller.
- * - `manage` — the Library's ordinary overflow container.
  * - `settings` — the Project Settings document (`panels/settings-pane.ts`): an `overflow-y: auto`
  *   section column, plus the Raw JSON `<pre>`'s own box inside it.
  * - `entry` — the Entry editor's `overflow-y: auto` form (`content/entry-editor.ts`).
@@ -1000,28 +999,30 @@ export function initShortcuts(registry: CommandRegistry, stageContext: StageCont
  *   there is no artboard here to zoom, either.
  */
 const SELF_SCROLLING_MODES: ReadonlySet<string> = new Set([
+  /* The Content home — `browse/library-pane.ts`. Its own scrolling list, nothing to zoom. */
+  "content-home",
   "entry",
   "grid",
-  "manage",
   /* `media` — the Media viewer's own scrolling column (`media/media-pane.ts`). There is no artboard
      here either: a wheel over an image is a scroll down the page it sits on, not a zoom. */
   "media",
+  /* A workspace's home — `workspace/workspace-home.ts`. A centred column with nothing to zoom. */
+  "media-home",
   "preview",
-  "settings",
+  "publish-home",
 ]);
 
 /**
  * Can a box between `target` and the stage still answer this wheel itself?
  *
- * Edit forwards every wheel to the page's scroller (see the branch below), which was the whole
- * story while the stage cell held nothing but the page. It also holds the Document Header band now,
- * a capped scroll container standing beside the scroller — and a `preventDefault` from an ANCESTOR
- * listener cancels the native scroll of whatever the pointer is over, so a form taller than the cap
- * could not be wheeled at all while the page scrolled underneath it instead. So the stage takes the
- * wheel only when nothing inside it wants one: the walk stops at the stage cell, and it steps over
- * the page's scroller because that box is what the forwarding is FOR — a wheel forwarded out of the
- * cross-origin frame is dispatched on the cell itself and reaches no scrollable element on the way,
- * and letting the browser scroll the page natively would chain out of it into the shell.
+ * Edit forwards every wheel to the page's scroller (see the branch below). A `preventDefault` from
+ * an ANCESTOR listener cancels the native scroll of whatever the pointer is over, so any box in the
+ * stage cell that scrolls itself (a sideways strip, a capped list) would otherwise be unwheelable
+ * while the page scrolled underneath it instead. So the stage takes the wheel only when nothing
+ * inside it wants one: the walk stops at the stage cell, and it steps over the page's scroller
+ * because that box is what the forwarding is FOR — a wheel forwarded out of the cross-origin frame
+ * is dispatched on the cell itself and reaches no scrollable element on the way, and letting the
+ * browser scroll the page natively would chain out of it into the shell.
  *
  * @param {WheelEvent} e
  * @param {HTMLElement} stage The cell the listener is on — the walk's upper bound, exclusive.
@@ -1146,8 +1147,8 @@ export function installStageGestures(surface: CanvasSurface): () => void {
         /* The stage's own scroller, by the `part` the stage document draws it with — the same
            attribute every other consumer of the canvas's chrome now addresses it by. */
         const sc = canvasWrap.querySelector<HTMLElement>('[part="edit-canvas"]');
-        /* …unless the pointer is over a box in this cell that scrolls itself — the Document Header
-           band, which Edit docks beside the scroller. See {@link wheelBelongsInside}. */
+        /* …unless the pointer is over a box in this cell that scrolls itself. See
+           {@link wheelBelongsInside}. */
         if (sc && !wheelBelongsInside(e, canvasWrap, sc)) {
           e.preventDefault();
           sc.scrollTop += e.deltaY;
@@ -1231,7 +1232,7 @@ export function installStageGestures(surface: CanvasSurface): () => void {
   canvasWrap.addEventListener(
     "click",
     (e: MouseEvent) => {
-      if (e.target !== canvasWrap && e.target !== surface.panzoomWrap) {
+      if (!isStageBackground(e.target, canvasWrap, surface.panzoomWrap)) {
         return;
       }
       const tab = tabOfPane(surface.paneId);
@@ -1249,6 +1250,27 @@ export function installStageGestures(surface: CanvasSurface): () => void {
   };
 }
 
+/**
+ * Whether a click landed on a stage's BACKGROUND rather than on anything drawn in it: the stage
+ * itself, the pan/zoom surface, or the frame box every view draws its artboards in.
+ *
+ * The frame box is the one that matters in Edit. Edit has no pan/zoom surface; its frame is the
+ * scrolling `[part="edit-canvas"]` that fills the stage around the page column, so the grey margin
+ * beside the page IS that box, and a test that knew only the stage and the pan/zoom surface never
+ * saw a click there. The frame is recognised by its static `data-slot`, which the stage document
+ * stamps on it in every view.
+ */
+export function isStageBackground(
+  target: EventTarget | null,
+  stage: Element,
+  panzoom: Element | null,
+): boolean {
+  if (target === stage || (panzoom !== null && target === panzoom)) {
+    return true;
+  }
+  return target instanceof HTMLElement && target.dataset.slot === "frame" && stage.contains(target);
+}
+
 /** The context a stage answers with before the bootstrap has published a reader. */
 function stageless(): ShortcutPointerContext {
   return {

package/src/editor/slash-menu.ts

@@ -27,8 +27,14 @@
  */
 
 import { openSlashMenuSurface } from "../surfaces/slash-menu";
+import { componentSlashCommands } from "./insert-component";
 import { rectOf } from "../utils/geometry";
-import type { SlashMenuRow, SlashMenuSurface, SlashMenuView } from "../surfaces/slash-menu";
+import type {
+  SlashMenuGroup,
+  SlashMenuRow,
+  SlashMenuSurface,
+  SlashMenuView,
+} from "../surfaces/slash-menu";
 import type { SlashCommand } from "./inline-edit";
 
 // ─── Commands ─────────────────────────────────────────────────────────────────
@@ -115,9 +121,43 @@ export function showSlashMenuAtRect(
   showAt(rect, filter, cbs);
 }
 
+/**
+ * The standard set: the HTML elements, then the project's components under their own heading
+ * (§5.7), read from the registry at the moment the menu opens so a component saved a moment ago is
+ * on offer.
+ */
+function standardCommands(): SlashCommand[] {
+  return [...SLASH_COMMANDS, ...componentSlashCommands()];
+}
+
 /** Everything on offer right now: what the caller named, or the standard set. */
 function source(): SlashCommand[] {
-  return callbacks?.commands || SLASH_COMMANDS;
+  return callbacks?.commands || standardCommands();
+}
+
+/**
+ * The rows as the panel groups them: consecutive offers with the same heading share a group, and
+ * the first, unheaded group is the HTML elements. Each row keeps its index in the FLAT list, which
+ * is the one the keyboard, the highlight and a pick count in.
+ */
+function groupsOf(rows: readonly SlashMenuRow[], items: readonly SlashCommand[]): SlashMenuGroup[] {
+  const groups: SlashMenuGroup[] = [];
+  for (const [index, row] of rows.entries()) {
+    const label = items[index]?.group ?? "";
+    const last = groups.at(-1);
+    if (last?.label === label) {
+      last.rows.push(row);
+    } else {
+      groups.push({
+        hasLabel: label !== "",
+        key: label || "elements",
+        label,
+        name: label || "Elements",
+        rows: [row],
+      });
+    }
+  }
+  return groups;
 }
 
 /** The offers a filter leaves standing. An empty filter leaves all of them. */
@@ -132,14 +172,17 @@ function matching(filter: string, from: SlashCommand[]): SlashCommand[] {
 /** What the panel should be showing, from the state above. */
 function view(): SlashMenuView {
   const rect = _anchorRect;
+  const rows = filteredItems.map((cmd, index): SlashMenuRow => ({
+    description: cmd.description,
+    index,
+    key: cmd.tag,
+    label: cmd.label,
+  }));
   return {
     activeIndex: activeIdx,
     filter: filterText,
-    rows: filteredItems.map((cmd): SlashMenuRow => ({
-      description: cmd.description,
-      key: cmd.tag,
-      label: cmd.label,
-    })),
+    groups: groupsOf(rows, filteredItems),
+    rows,
     showFilter,
     // The gap between the anchor and the panel is the `--jx-popover-offset` token the element
     // Already applies, so this is the anchor's own edge rather than an edge plus a guess.
@@ -163,7 +206,7 @@ function showAt(
   callbacks = cbs;
   _anchorRect = rect;
 
-  filteredItems = matching(filter, cbs.commands || SLASH_COMMANDS);
+  filteredItems = matching(filter, cbs.commands || standardCommands());
 
   if (filteredItems.length === 0 && !cbs.showFilter) {
     dismissSlashMenu();

package/src/files/components.ts

@@ -18,14 +18,39 @@ export interface ComponentEntry extends Omit<ComponentMeta, "path"> {
 export let componentRegistry: ComponentEntry[] = [];
 export let _componentRegistryLoaded = false;
 
-export async function loadComponentRegistry() {
-  try {
-    const platform = getPlatform();
-    componentRegistry = await platform.discoverComponents(projectState?.projectRoot || undefined);
-    _componentRegistryLoaded = true;
-  } catch {
+/** Bumped by every load, so only the newest scan may write the registry. */
+let _generation = 0;
+/** The newest scan, which a superseded one waits on so its caller still sees a loaded registry. */
+let _newest: Promise<void> = Promise.resolve();
+
+/**
+ * Scan the project's components into the registry.
+ *
+ * Scans can overlap (the project-open path and the Site panel each start one), and a scan bound to
+ * the project being closed may resolve after the next project's. So the newest scan wins: an older
+ * one discards what it read and resolves when the newest has written the registry.
+ */
+export function loadComponentRegistry(): Promise<void> {
+  _generation += 1;
+  const generation = _generation;
+  const scan = (async () => {
+    let found: ComponentEntry[] | null = null;
+    try {
+      found = await getPlatform().discoverComponents(projectState?.projectRoot || undefined);
+    } catch {
+      found = null;
+    }
+    if (generation !== _generation) {
+      await _newest;
+      return;
+    }
+    if (found) {
+      componentRegistry = found;
+    }
     _componentRegistryLoaded = true;
-  }
+  })();
+  _newest = scan;
+  return scan;
 }
 
 /**
@@ -107,18 +132,57 @@ export function buildComponentInstance(comp: ComponentEntry): JxMutableNode {
 }
 
 /**
+ * Walk `parts` the way a path resolver does: `.` stays, `..` climbs, the rest descend. A climb
+ * above the start is kept as a leading `..`, which is how a project-relative path names a file
+ * outside the project.
+ */
+function normalizeParts(parts: readonly string[]): string[] {
+  const out: string[] = [];
+  for (const part of parts) {
+    if (part === ".") {
+      continue;
+    }
+    if (part === ".." && out.length > 0 && out.at(-1) !== "..") {
+      out.pop();
+    } else {
+      out.push(part);
+    }
+  }
+  return out;
+}
+
+/**
+ * The `$ref` a document at `fromDocPath` writes to reach `toCompPath`, both project-relative.
+ *
+ * A document can sit OUTSIDE the project: jxsuite.com's docs collection is `../../docs`, so an
+ * entry is `../../docs/extending/x.md`. Climbing from there back into the project needs the names
+ * of the folders the project sits in, which a project-relative path does not carry; counting its
+ * segments gave five `../` and a ref into a folder that does not exist, so every component a docs
+ * layout imports failed to register on the canvas. Such a path is resolved against `projectRoot`
+ * (the open project's, by default), the way the browser resolves the ref.
+ *
  * @param {string | null} fromDocPath
  * @param {string} toCompPath
+ * @param {string | null} [projectRoot]
  */
-export function computeRelativePath(fromDocPath: string | null, toCompPath: string) {
+export function computeRelativePath(
+  fromDocPath: string | null,
+  toCompPath: string,
+  projectRoot: string | null = projectState?.projectRoot ?? null,
+) {
   if (!fromDocPath) {
     return `./${toCompPath}`;
   }
   const from = fromDocPath.replaceAll("\\", "/");
   const to = toCompPath.replaceAll("\\", "/");
   const fromDir = from.includes("/") ? from.slice(0, from.lastIndexOf("/")) : "";
-  const fromParts = fromDir.split("/").filter(Boolean);
-  const toParts = to.split("/").filter(Boolean);
+  let fromParts = normalizeParts(fromDir.split("/").filter(Boolean));
+  let toParts = normalizeParts(to.split("/").filter(Boolean));
+  if (fromParts[0] === ".." && projectRoot) {
+    const rootParts = projectRoot.replaceAll("\\", "/").split("/").filter(Boolean);
+    fromParts = normalizeParts([...rootParts, ...fromParts]);
+    toParts = normalizeParts([...rootParts, ...toParts]);
+  }
   let common = 0;
   while (
     common < fromParts.length &&

package/src/files/file-ops.ts

@@ -105,6 +105,8 @@ export async function parseSourceForPath(path: string, source: string) {
 export const parseCollabSource: CollabParser = async (tab, text) => {
   if (tab.documentPath && formatForPath(tab.documentPath)) {
     const parsed = await parseSourceForPath(tab.documentPath, text);
+    // The peer's text is what this client saves against now, as `layout` is for a JSON file.
+    tab.doc.source = text;
     return { document: parsed.document, frontmatter: parsed.frontmatter };
   }
   const parsed = parseJsonDocument(text);
@@ -195,6 +197,7 @@ export async function openFile() {
           fileHandle: handle,
           frontmatter,
           id: name,
+          source: text,
           sourceFormat: format.name,
         });
       } else if (name.endsWith(".json")) {
@@ -254,26 +257,27 @@ export async function openFile() {
  * **By injection**, the idiom `setSurfaceTeardown` and `setDiffRepaint` already use. The one
  * listener today is source control: a comparison is two texts read once, so it does not notice a
  * save on its own, and the file an author is most likely to save is the one they are reviewing. A
- * direct import would put `panels/git-panel.ts` into this module's graph, which is a load error for
- * every suite that mocks the canvas host out from under it.
+ * direct import would put `publish/source-control.ts` and the comparison opener behind it into this
+ * module's graph, which is a load error for every suite that mocks the canvas host out from under
+ * it.
  *
  * The listener is handed the document as well as the path, for the second listener: the live chrome
  * lane (`services/live-surfaces.ts`) re-mounts a saved surface from the document the tab just wrote
  * rather than reading the file back, which is what keeps the shipped app from ever reading its
  * chrome from disk.
  */
-let _onDocumentSaved: (path: string | null, doc: JxMutableNode) => void = () => {};
+let _onDocumentSaved: (path: string | null, doc: JxMutableNode, tab: Tab) => void = () => {};
 
 /** Register the save listener. Called once, from the bootstrap. */
 export function setDocumentSavedListener(
-  listener: (path: string | null, doc: JxMutableNode) => void,
+  listener: (path: string | null, doc: JxMutableNode, tab: Tab) => void,
 ): void {
   _onDocumentSaved = listener;
 }
 
 function reportSaved(tab: Tab) {
   const doc = tab.doc.document;
-  _onDocumentSaved(tab.documentPath, doc);
+  _onDocumentSaved(tab.documentPath, doc, tab);
   const warning =
     isString(doc.tagName) && doc.tagName.includes("-") ? validateComponentSlots(doc) : null;
   if (warning) {
@@ -398,6 +402,9 @@ export async function saveFile(tab: Tab | null = activeTab.value): Promise<boole
       const platform = getPlatform();
       await platform.writeFile(tab.documentPath, output);
       tab.doc.dirty = false;
+      if (tab.doc.sourceFormat !== null) {
+        tab.doc.source = output;
+      }
       /* Retract the unsaved bytes NOW rather than a debounce later. The write also reaches the
          backend's filesystem watcher, and a live preview coalesces both into one reload only if
          they arrive together — otherwise a save costs two. */
@@ -418,6 +425,9 @@ export async function saveFile(tab: Tab | null = activeTab.value): Promise<boole
       await writable.write(output);
       await writable.close();
       tab.doc.dirty = false;
+      if (tab.doc.sourceFormat !== null) {
+        tab.doc.source = output;
+      }
       reportSaved(tab);
       return true;
     }