@jxsuite/studio 6.1.2 → 8.0.1

package/src/panels/i18n-panel.ts

@@ -34,8 +34,8 @@
  * does, because the document is appended into the `.panel-content` lit renders `nothing` into).
  *
  * **Off the rail.** `railDeclarations()` does not apply `when`, so a rail button here would spend
- * the last `rail/project` slot in every monolingual project and shift every document panel's ⌘1–8
- * chord by one. `i18n.showParity` is how this panel is reached.
+ * the last `rail/project` slot in every monolingual project. `i18n.showParity` is how this panel is
+ * reached.
  *
  * @docs studio/interface/languages
  */
@@ -190,7 +190,7 @@ async function takeScan(root: string, rerender: () => void): Promise<void> {
  */
 async function readDeclaredKeys(files: readonly LibraryFile[]): Promise<Map<string, string>> {
   const platform = getPlatform();
-  const pages = files.filter((file) => file.category !== "Media" && file.path.startsWith("pages/"));
+  const pages = files.filter((file) => !file.media && file.path.startsWith("pages/"));
   /* Issued together, not one after another. Each read is a round trip on a remote backend, and a
      sequential loop paid one per page; issued in one tick, the cloud adapter coalesces them into a
      single batch request (specs/desktop.md §10.1). `Promise.all` keeps the input order, so the map
@@ -236,8 +236,8 @@ function timeOf(modified: string | undefined): number | null {
  * it is the source the other columns are measured against, and hiding it would leave the grid with
  * a column of `missing` cells whose sources are on disk.
  *
- * Assets are skipped. `categoryFor` already decides what is media by extension, so an image beside
- * a page is not a row here for the same reason it is not a page anywhere else.
+ * Assets are skipped. The scan already marks what is media by its extension, so an image beside a
+ * page is not a row here for the same reason it is not a page anywhere else.
  */
 export function parityRows(
   files: readonly LibraryFile[],
@@ -255,7 +255,7 @@ export function parityRows(
   /* Every key the paths alone produce, so a declared one can be matched against a real file rather
      than against a spelling. */
   const derivedKeys = new Set(
-    files.flatMap((f) => (f.category === "Media" ? [] : [translationKeyOfPath(f.path, i18n)])),
+    files.flatMap((f) => (f.media ? [] : [translationKeyOfPath(f.path, i18n)])),
   );
   const keyOf = (file: LibraryFile): string => {
     const own = declared.get(file.path);
@@ -278,7 +278,7 @@ export function parityRows(
     return `pages/${own}${ext}`;
   };
   for (const file of files) {
-    if (file.category === "Media") {
+    if (file.media) {
       continue;
     }
     const key = keyOf(file);
@@ -542,8 +542,10 @@ let rerender: () => void = () => {};
 
 /** What the document's three controls do. Every one of them is a decision this module owns. */
 const ACTIONS: I18nActions = {
+  /* On Locales, not wherever Project Settings was last left: the empty state's one sentence is
+     "declare your languages", and the dialog remembers its section for the session (§17.1). */
   openSettings: () => {
-    runByName(SETTINGS_COMMAND);
+    runByName(SETTINGS_COMMAND, { section: "locales" });
   },
   rescan: () => {
     refreshParityScan();
@@ -606,8 +608,7 @@ export function registerI18nPanel(): void {
     // Button, and `check-icons.ts` fails on a resolver row no rail panel declares.
     icon: "globe",
     // OFF THE RAIL. `railDeclarations()` does not apply `when`, so a rail button would spend the
-    // Last rail/project slot in every monolingual project — and would shift every document panel's
-    // ⌘1-8 chord by one. `i18n.showParity` is how it is reached.
+    // Last rail/project slot in every monolingual project. `i18n.showParity` is how it is reached.
     rail: false,
     when: (ctx) => ctx.project.isMultilingual,
     // The body is a document, so lit draws nothing and the mount happens against the painted

package/src/panels/imports-panel.ts

@@ -442,6 +442,8 @@ export function registerPackagesPanel(): void {
     level: "document",
     dock: "navigator",
     icon: "cube",
+    // A developer panel (§5.1): on the rail only with **Show developer panels** on.
+    rail: "developer",
     requiresDocument: "Open a page to choose which components it can use.",
     render: () => nothing,
     afterRender: (ctx, host) => {

package/src/panels/jump-bar.ts

@@ -75,6 +75,8 @@ import { runReported } from "../commands/run-reported";
 import { openMenu } from "../surfaces/menu";
 import { rectOf } from "../utils/geometry";
 import { mountJumpBarSurface } from "../surfaces/jump-bar";
+import { workspaceHomeLabel } from "../workspace/workspace-ids";
+import { gridTabLabel } from "../grid/grid-source";
 import type { CommandRegistry } from "../commands/registry";
 import type { FormulaEditDef, FunctionEditDef } from "../types";
 import type { JxPath } from "../state";
@@ -152,6 +154,30 @@ export function documentLabel(path: string | null): string {
   return root && path.startsWith(`${root}/`) ? path.slice(root.length + 1) : path;
 }
 
+/**
+ * What the file segment says about a tab: its path, or, for a VIRTUAL tab, the view's own name.
+ *
+ * A pathless tab is one of two different things. A workspace home (`workspace://content`) or a grid
+ * (`grid://…`) has no file because it is a view, not a document, and it never will have one;
+ * calling it "Untitled · Not saved to disk yet" invited the author to save a page that does not
+ * exist. Those tabs are named exactly as their strip chip names them (`panels/tab-strip.ts`), so
+ * the address and the tab agree. Only a genuinely new document is "Untitled".
+ */
+export function fileSegmentText(tab: Tab): Pick<JumpSegment, "label" | "title"> {
+  if (tab.documentPath) {
+    return { label: documentLabel(tab.documentPath), title: tab.documentPath };
+  }
+  const home = workspaceHomeLabel(tab.id);
+  if (home) {
+    return { label: home, title: `The ${home} workspace's home, a view rather than a file` };
+  }
+  const grid = gridTabLabel(tab.id);
+  if (grid) {
+    return { label: grid, title: `${grid}, a view of many files rather than one` };
+  }
+  return { label: documentLabel(null), title: "Not saved to disk yet" };
+}
+
 // ─── The selection trail (moved here from statusbar.ts) ──────────────────────
 
 /** One crumb of the ancestor trail: what to call the node, and the path that selects it. */
@@ -284,8 +310,7 @@ export function jumpSegments(
       choices: [],
       command: derived ? "pane.pin" : "palette.openFiles",
       kind: "file",
-      label: documentLabel(tab.documentPath),
-      title: tab.documentPath ?? "Not saved to disk yet",
+      ...fileSegmentText(tab),
     },
   ];
 

package/src/panels/layers-panel.ts

@@ -3,14 +3,16 @@
  * Layers panel — the Outline: the document tree, with collapse, selection, drag-and-drop
  * reordering, and per-row actions that are RENDERINGS of the command registry.
  *
- * **One panel, two bodies, and both of them are documents now.** The tree is
- * `surfaces/panel-outline.json`; the Project Styles catalogue is
+ * **One panel, two bodies, and both of them are documents.** The tree is
+ * `surfaces/panel-outline.json`; the element catalogue a document's Elements view lists is
  * `surfaces/panel-stylebook-layers.json` (`panels/stylebook-layers-panel.ts`). This module renders
- * neither. It owns the record — only the record can know which body the pane is asking for — and
+ * neither. It owns the record (only the record can know which body the pane is asking for) and
  * everything that is a DECISION: which rows exist and in what order, what a row is called, what the
  * window onto them is, which verbs the registry places on which row, and the whole of the keyboard
  * model. The surface reads values. The two bodies are appended into the same `.panel-content`, so
- * each mode takes the other's document down on the way in; that symmetry is the whole of the seam.
+ * each mode takes the other's document down on the way in. The Variables view has no body here:
+ * `project.json`'s custom properties are listed by the Styles workspace's own Navigator panel
+ * (`panels/styles-panel.ts`, §7.1).
  *
  * Four things this file is deliberate about.
  *
@@ -27,7 +29,7 @@
  * **A row says something.** On a real page the tree was a wall of rows all reading "div": only
  * text-bearing nodes got a preview and containers got the tag they already wear as a coloured
  * badge. {@link outlineLabel} derives an identity instead — a title, an `$id`, a class, a landmark
- * name, the first text inside — and returns "" rather than repeat the badge.
+ * name, the text it owns (never a descendant row's) — and returns "" rather than repeat the badge.
  *
  * **It is a tree, and it is reachable.** `role="tree"` / `role="treeitem"` with a roving tabindex
  * and the arrow-key model ARIA specifies: ↑↓ walk the visible rows, → expands then descends, ←
@@ -87,6 +89,7 @@ import {
   mountStylebookLayersPanel,
 } from "./stylebook-layers-panel";
 import { selectStylebookTag, stylebookMeta } from "./stylebook-panel";
+import { PROJECT_STYLES_VIEW } from "../style/project-styles";
 import { isInlineElement } from "../editor/inline-edit";
 import { showContextMenu } from "../editor/context-menu";
 import { revealPathInCanvas } from "../canvas/popover-state";
@@ -147,31 +150,32 @@ function truncate(text: string): string {
 }
 
 /**
- * The first text anywhere under `node`, or "".
+ * The text `node` OWNS, or "": its string children, and the text of its inline children.
  *
- * Bounded at three levels and short-circuited on the first hit: a container's identity is usually
- * its heading or its first line, and walking a whole subtree per row would cost the render what the
- * five-buttons-per-row build already cost it.
+ * Inline children (`strong`, `a`, …) never get a row of their own ({@link buildOutlineRows} skips
+ * them), so their words belong to the row that holds them. A block child's text does not: it is
+ * that child's row's to show. Borrowing it — what the bounded "first text under" walk did — made a
+ * `section > div > div > h2` read the heading four times over, one row above the other.
  */
-function firstText(node: JxMutableNode, depth = 0): string {
-  if (isString(node.textContent) && node.textContent.trim()) {
+function ownText(node: JxMutableNode): string {
+  if (isString(node.textContent)) {
     return node.textContent.trim();
   }
-  if (depth >= 3 || !Array.isArray(node.children)) {
+  if (!Array.isArray(node.children)) {
     return "";
   }
+  let text = "";
   for (const child of node.children) {
-    if (isString(child) && child.trim()) {
-      return child.trim();
+    if (isString(child)) {
+      text += child;
+    } else if (isNonNullObject(child) && isInlineElement(child, node)) {
+      text += ownText(child);
     }
-    if (isNonNullObject(child)) {
-      const found = firstText(child, depth + 1);
-      if (found) {
-        return found;
-      }
+    if (text.length > LABEL_MAX * 2) {
+      break;
     }
   }
-  return "";
+  return text.trim();
 }
 
 /** The node's first class name, when it has a plain (unbound) `class` attribute. */
@@ -212,9 +216,9 @@ export function outlineLabel(node: JxMutableNode): string {
   if (landmark) {
     return landmark;
   }
-  const inner = firstText(node);
-  if (inner) {
-    return `“${truncate(inner)}”`;
+  const own = ownText(node);
+  if (own) {
+    return `“${truncate(own)}”`;
   }
   const count = Array.isArray(node.children) ? node.children.length : 0;
   return count > 0 ? `${count} item${count === 1 ? "" : "s"}` : "";
@@ -1142,9 +1146,9 @@ export function outlineValues(): OutlineValues {
 /**
  * The surface standing in the Navigator, and the node it was mounted into.
  *
- * One slot rather than a per-host map, for the reason `panels/stylebook-layers-panel.ts` gives:
- * there is one Navigator, so a mount into a DIFFERENT node is the old one being replaced, and
- * holding both would leave the first one's effects running against a scope nobody writes any more.
+ * One slot rather than a per-host map, for the reason `panels/elements-panel.ts` gives: there is
+ * one Navigator, so a mount into a DIFFERENT node is the old one being replaced, and holding both
+ * would leave the first one's effects running against a scope nobody writes any more.
  */
 let standing: { host: HTMLElement; handle: OutlineSurfaceHandle } | null = null;
 /** Re-register drag-and-drop once the rows the projection asked for are actually in the DOM. */
@@ -1353,7 +1357,7 @@ export function mountOutlinePanel(
 /**
  * Take the tree down.
  *
- * Called by the record when the pane starts showing Project Styles. Without it the document
+ * Called by the record when the pane starts showing an Elements view. Without it the document
  * survives its own irrelevance: both bodies are appended into the same `.panel-content`, so the one
  * nobody took down sits under the one that replaced it for the rest of the session.
  */
@@ -1388,18 +1392,20 @@ export function registerLayersPanel(): void {
     requiresDocument: "Open a page to see the elements it is built from.",
     /*
      * One panel, two bodies, and neither of them is lit's. The body is a document either way, so
-     * there is nothing for lit to draw here — a document CLEARS nothing and is APPENDED, and lit's
+     * there is nothing for lit to draw here: a document CLEARS nothing and is APPENDED, and lit's
      * own comment markers inside `.panel-content` are what it finds its (empty) content by.
      */
     render: (): PanelBody => nothing,
     /*
-     * `afterRender` runs on every repaint, and both mounts are idempotent — the standing surface is
+     * `afterRender` runs on every repaint, and both mounts are idempotent: the standing surface is
      * updated where it is still there and re-mounted only where something has taken it out. The
      * detach on each side is not symmetry for its own sake: the two documents are appended into the
      * same node, so a body nobody took down would sit under the one that replaced it.
      */
     afterRender: (ctx, host) => {
-      if (ctx.deps.getCanvasMode() === "stylebook") {
+      /* A document's Elements view lists the element catalogue; every other view draws the tree,
+         Variables and Code included. */
+      if (ctx.deps.getCanvasMode() === PROJECT_STYLES_VIEW) {
         detachOutline();
         mountStylebookLayersPanel({ selectStylebookTag, stylebookMeta }, host);
         return;

package/src/panels/left-panel.ts

@@ -76,7 +76,24 @@ export function mount(deps: NavigatorPanelDeps) {
     { panels: [panelView()] },
     {
       onContent: (panelId, host) => {
+        const switched = _content !== null && _content.panelId !== panelId;
         _content = { host, panelId };
+        /* `#left-panel` is the ONE scroller every panel draws in (the dock's root is `display:
+           contents`), so its offset outlived the panel it belonged to: scrolled down to the Site
+           panel's Components, a click on Outline opened the Outline that far down. A different
+           panel is a different list, and it opens at its top. A repaint of the same panel keeps
+           its place, because the box is keyed on the panel and is not announced again.
+           In the next FRAME, not here: this runs while the dock is still building the new panel,
+           and a scroll write lays out the half-built document to clamp the offset (a forced
+           recalculation on every Navigator panel switch in the perf trace). The frame lays it out
+           anyway, and resets the offset before anything is painted. */
+        if (switched) {
+          requestAnimationFrame(() => {
+            if (_content?.host === host) {
+              requireShellRef(leftPanel, "left-panel").scrollTop = 0;
+            }
+          });
+        }
         /* A MICROTASK, not this call. `onNodeCreated` fires the moment the element is CONSTRUCTED
            and the runtime applies its attributes on the next line, so a panel's `afterRender` run
            from here would be handed a content box with no `part` on it — and several panels find
@@ -93,20 +110,17 @@ export function mount(deps: NavigatorPanelDeps) {
   _scope = effectScope();
   _scope.run(() => {
     effect(() => {
-      // Shell state is tracked with no tab open — which panel is showing, and the project-level
-      // State the project-level panels draw from. A document-less rail tab still repaints.
+      // Shell state is tracked with no tab open: which panel is showing. A document-less rail tab
+      // Still repaints.
       void shell.leftTab;
-      void shell.settingsTab;
-      void shell.git.status;
-      void shell.git.loading;
-      void shell.git.error;
-      void shell.git.subTab;
-      void shell.git.logEntries;
       const tab = activeTab.value;
       if (tab) {
         // Track properties the Navigator's panels read
         void tab.doc.document;
         void tab.doc.mode;
+        // The editor too: the Outline draws the element catalogue beside a document's Elements
+        // View, and the tree beside every other.
+        void tab.session.ui.canvasMode;
         // The whole SET, joined — a bare property read would not re-trigger when the selection
         // Changes WITHIN the array, and §6.7's helpers always replace it but nothing enforces that.
         void tab.session.selection.map((path) => path.join("/")).join("|");

package/src/panels/navigator-panels.ts

@@ -7,8 +7,10 @@
  * Nothing here decides what a panel is called, what level it is, or what it draws — that would be
  * the second definition site the registry exists to prevent.
  *
- * **Registration order is rail order** within a level group: PROJECT (Files ⌘1 · Search ⌘2 · Source
- * Control ⌘3) above the divider, DOCUMENT (Outline ⌘4 · Page ⌘5 · Data ⌘6 · Packages ⌘7) below it.
+ * **Registration order is rail order** within a level group: PROJECT (Site, then Files with the
+ * developer panels on) above the divider, DOCUMENT (Outline · Data, then Packages with the
+ * developer panels on) below it (§5.1). Search, Languages and Insert are registered rail-less:
+ * reachable by `view.setActivity` and the palette, with no button.
  *
  * **Every rail button opens the Navigator.** Problems used to hold the fourth PROJECT slot while
  * its body was drawn in the Bottom dock, and paying for that took a per-dock branch in three
@@ -17,21 +19,22 @@
  * The count reaches the user from the status bar the moment there is one.
  *
  * **Search is declared and hidden.** It is a surface a later phase builds (the palette's project
- * index), and it holds a slot in the rail's four-tab budget (`studio-ui-guidelines.md` §12.2). A
+ * index), and it is off the rail like every other panel the Design rail does not list (§5.1). A
  * `when: () => false` record is the honest way to say "this exists in the design and not yet in the
- * app": the id is reserved, the budget already counts it, and the day it ships the only edit is
- * deleting one predicate — as opposed to a stub button that lies to whoever clicks it.
+ * app": the id is reserved, and the day it ships the only edit is deleting one predicate — as
+ * opposed to a stub button that lies to whoever clicks it.
  */
 
 import { registerFilesPanel } from "../files/files";
 import { registerDataPanel } from "./data-explorer";
 import { registerInsertPanel } from "./elements-panel";
-import { registerGitPanel } from "./git-panel";
 import { registerI18nPanel } from "./i18n-panel";
-import { registerPagePanel } from "./head-panel";
 import { registerPackagesPanel } from "./imports-panel";
 import { registerBottomPanels } from "./bottom-dock";
 import { registerLayersPanel } from "./layers-panel";
+import { registerSitePanel } from "./site-panel";
+import { registerCollectionsPanel } from "./collections-panel";
+import { registerStylesPanel } from "./styles-panel";
 import { getPanel, listPanels, railPanelSet, registerPanel, resetPanels } from "./panel-registry";
 import type { PanelRecord } from "./panel-registry";
 
@@ -45,14 +48,21 @@ const NOT_YET_BUILT = () => false;
  * per window in the app, but a test suite mounts it per case.
  */
 export function registerNavigatorPanels(): void {
-  // Keyed on Files rather than on `listPanels("navigator")`, because the Bottom dock composes
+  // Keyed on Site rather than on `listPanels("navigator")`, because the Bottom dock composes
   // Itself independently (`bottomPanelSet()` calls `registerBottomPanels()` directly) and either
   // Order has to leave this function still registering the Navigator's own eight.
-  if (getPanel("files")) {
+  if (getPanel("site")) {
     return;
   }
 
   // ── PROJECT group ───────────────────────────────────────────────────────────
+  registerSitePanel();
+  /* The Content workspace's Navigator (§22.5): off the rail, because Content draws none, and opened
+     by that workspace's frame. */
+  registerCollectionsPanel();
+  /* The Styles workspace's Navigator (§7.1): variables, element defaults and color schemes, off the
+     rail for the same reason. */
+  registerStylesPanel();
   registerFilesPanel();
   registerPanel({
     id: "search",
@@ -60,10 +70,13 @@ export function registerNavigatorPanels(): void {
     level: "project",
     dock: "navigator",
     icon: "magnifying-glass",
+    rail: false,
     when: NOT_YET_BUILT,
     render: () => nothingYet(),
   });
-  registerGitPanel();
+  /* No Source Control panel: its change list, commit and branch picker are the Publish workspace's
+     Review changes and Branches (§5.5, §22.8), and a Navigator beside that workspace would be a
+     second list of the same things. */
   /* Off the rail, and registered in the PROJECT group anyway: registration order is roster order,
      so this is what puts Languages beside the panels it belongs with in the palette and in
      `panel.focus.*`. Its `when` is `project.isMultilingual` — a project written in one language
@@ -72,7 +85,6 @@ export function registerNavigatorPanels(): void {
 
   // ── DOCUMENT group ──────────────────────────────────────────────────────────
   registerLayersPanel();
-  registerPagePanel();
   registerDataPanel();
   registerPackagesPanel();