@jxsuite/studio 6.1.2 → 8.0.1

package/src/panels/pane-context.ts

@@ -45,6 +45,7 @@
  * the document it is warning you about.
  */
 
+import { writesEntryOnCanvas } from "../content/content-collections";
 import { projectState, updateUi } from "../store";
 import { effect, effectScope } from "../reactivity";
 import { PRIMARY_PANE, focusPane, workspace } from "../workspace/workspace";
@@ -68,6 +69,8 @@ import { openMenu } from "../surfaces/menu";
 import { emptyPaneContextView, mountPaneContextSurface } from "../surfaces/pane-context";
 import { PANE_SELECTOR } from "../surfaces/pane-grid";
 import { diffShowsCode } from "../canvas/diff-view";
+import { backTargetOf, goBack } from "../workspace/workspace-back";
+import type { WorkspaceId } from "../workspace/workspace-ids";
 import { canRenderComparison } from "./git-diff-open";
 import { shell } from "../shell";
 import { paneRegion } from "../ui/regions";
@@ -89,7 +92,12 @@ import {
 import { editorKindOf, editorKindsOf, modeForEditorKind } from "../tabs/tab";
 import { collabState } from "../collab/collab-state";
 import { activeRegistry } from "../commands/active-registry";
-import { getEffectiveLayoutPath, getEffectiveLocales, getEffectiveMedia } from "../site-context";
+import {
+  getEffectiveLayoutPath,
+  getEffectiveLocales,
+  getEffectiveMedia,
+  getEffectiveRenderLocale,
+} from "../site-context";
 import { localeLabel, localeOfPath } from "@jxsuite/schema/locale";
 import { isSchemeQuery } from "../utils/canvas-media";
 import { dynamicRouteParams, loadParamValues, pagePathsDef } from "../page-params";
@@ -143,6 +151,14 @@ export interface PaneContextCtx {
    * Editor picker a control over the primary's document.
    */
   setCanvasMode: (tab: Tab, mode: string) => void;
+  /**
+   * Close a tab through the strip's guarded close (`panels/tab-strip.ts` `requestClose`): what the
+   * Back control does to a media viewer or a comparison. Absent (a test's partial bootstrap), the
+   * control runs `pane.backToHome` instead, whose bootstrap deps carry the same close.
+   */
+  closeTab?: (tabId: string) => void | Promise<void>;
+  /** Give the keyboard to the home a Back landed on (`WorkspaceBackDeps.focusHome`). */
+  focusHome?: (paneId: string, id: WorkspaceId) => void;
   parseMediaEntries: (media: Record<string, string> | null | undefined) => {
     sizeBreakpoints: {
       name: string;
@@ -219,10 +235,51 @@ export function attachPaneChromeHost(paneId: string, host: HTMLElement | null):
 
 /** Take one pane's document down and forget it. Idempotent. */
 function disposePane(paneId: string): void {
+  _bandWatches.get(paneId)?.observer.disconnect();
+  _bandWatches.delete(paneId);
   _surfaces.get(paneId)?.dispose();
   _surfaces.delete(paneId);
 }
 
+/**
+ * Each pane's band, as the observer that keeps the stage offset in step with it watches it.
+ *
+ * The offset used to be MEASURED on every projection, synchronously, right after the update that
+ * may have changed the band. A projection runs inside whatever changed the pane (a tab activation,
+ * a workspace switch, a mode change) with the rest of that change still to be written, so the read
+ * paid a style recalculation of the whole half-written document every time: 12 to 18 ms per tab
+ * activation in the perf trace, the hottest forced recalculation once the tab strip stopped
+ * reading. A `ResizeObserver` reports the band's height after the frame's own layout, when it is
+ * free to read, and only when it actually changed.
+ */
+const _bandWatches = new Map<string, { band: HTMLElement; observer: ResizeObserver }>();
+
+/**
+ * Keep `paneId`'s stage offset following its band: measure it once now, and again whenever it
+ * resizes. Re-binds when the document has drawn a new band element; a no-op for the one it holds.
+ * Without `ResizeObserver` (a DOM with no layout engine) every call measures, as before.
+ */
+function watchBand(paneId: string, host: HTMLElement, surface: PaneContextSurfaceHandle): void {
+  const band = surface.band();
+  const held = _bandWatches.get(paneId);
+  if (held && held.band === band) {
+    return;
+  }
+  held?.observer.disconnect();
+  _bandWatches.delete(paneId);
+  applyPaneContextOffset(topBandHeight(surface), host);
+  if (!band || typeof ResizeObserver === "undefined") {
+    return;
+  }
+  const observer = new ResizeObserver(() => {
+    if (_surfaces.get(paneId) === surface) {
+      applyPaneContextOffset(topBandHeight(surface), host);
+    }
+  });
+  observer.observe(band);
+  _bandWatches.set(paneId, { band, observer });
+}
+
 /**
  * Mount the pane chrome. Idempotent.
  *
@@ -333,21 +390,6 @@ function topBandHeight(surface: PaneContextSurfaceHandle): number {
   return Math.max(surface.band()?.offsetHeight ?? 0, PANE_CONTEXT_HEIGHT);
 }
 
-/**
- * Whether this tab's editor has any of the bar's three axes to offer.
- *
- * Project Settings has none: it declares one editor kind, no canvas view, and no rendering context
- * — and the one control the bar WOULD contribute, "Manage contexts…", routes to a section of the
- * very document on screen. A bar of three inert controls above the definition site they point at is
- * chrome that says nothing, so the stage takes the whole pane.
- *
- * @param {Tab} tab
- * @returns {boolean}
- */
-function wantsContextBar(tab: Tab): boolean {
-  return tab.session.ui.canvasMode !== "settings";
-}
-
 /** Project every attached pane's chrome. */
 export function render() {
   for (const [paneId, host] of _hosts) {
@@ -362,8 +404,7 @@ function renderPane(paneId: string, host: HTMLElement) {
   }
   try {
     const tab = tabOfPane(paneId);
-    const show = tab !== null && wantsContextBar(tab);
-    if (!show) {
+    if (tab === null) {
       disposePane(paneId);
       applyPaneContextOffset(0, host);
       return;
@@ -382,13 +423,15 @@ function renderPane(paneId: string, host: HTMLElement) {
       void surface.ready.then(() => {
         const live = _surfaces.get(paneId);
         if (live) {
-          applyPaneContextOffset(topBandHeight(live), host);
+          watchBand(paneId, host, live);
         }
       });
       return;
     }
     surface.update(view);
-    applyPaneContextOffset(topBandHeight(surface), host);
+    /* No read here: the band's observer writes the offset once the frame has laid the band out
+       ({@link watchBand}). Only a band element the update REPLACED is re-measured now. */
+    watchBand(paneId, host, surface);
   } catch (error) {
     console.error("pane-context render error:", error);
   }
@@ -663,10 +706,27 @@ function viewFor(tab: Tab, paneId: string, ctx: PaneContextCtx): PaneContextView
     view.summary = lensSummary(paneId);
     return view;
   }
+  /* The way out of a view in a workspace with no tab strip: named for where it leads. Never in a
+     lens, whose tab is the source pane's, and whose own exit is the derivation's. */
+  const back = backTargetOf(tab);
+  if (back) {
+    view.backState = "shown";
+    view.backLabel = back.label;
+    view.backHint = back.hint;
+  }
   Object.assign(view, editorAxis(tab));
   if (editorKindOf(tab) === "canvas") {
     Object.assign(view, viewAxis(tab));
   }
+  /* A workspace home (the Content, Media or Publish home) draws its workspace's own surface over a
+     stub document, so there is no rendering context to choose: "Context: Base" over the Publish
+     workspace was a control that could change nothing on screen. The ⟲ menu goes for the same
+     reason: every projection it offers is of the document, and a home has none to project. */
+  if (editorKindOf(tab) === "home") {
+    view.contextState = "hidden";
+    view.presetState = "hidden";
+    return view;
+  }
   Object.assign(view, contextAxis(tab, paneId, ctx));
   /* THIS tab's effective mode. `ctx.getCanvasMode()` answered for the focused pane, so a document
      opened as Code in either pane put an Export button in the OTHER pane's bar as well — over a
@@ -810,10 +870,8 @@ interface PaneLocale {
  * A single declared locale is the same as none for this control — there is nothing to switch TO,
  * and "groups a document declares nothing for are absent" is the rule the whole popover follows.
  *
- * The fallback chain is what makes the control honest about a file it has not been told about:
- * `previewLocale` is the author's explicit choice, the path is the file's own language
- * (`site-architecture.md` §13.3 puts a translation in its own directory), and the default locale is
- * what an unprefixed page renders as.
+ * The language itself is `getEffectiveRenderLocale`'s answer (`site-context.ts`), the rule every
+ * artboard draws by: the choice, else the file's own language, else the default locale.
  */
 function localeOf(tab: Tab | null): PaneLocale | null {
   const i18n = getEffectiveLocales();
@@ -821,8 +879,10 @@ function localeOf(tab: Tab | null): PaneLocale | null {
     return null;
   }
   const pathLocale = localeOfPath(tab.documentPath ?? "", i18n);
-  const own = pathLocale ?? i18n.defaultLocale;
-  const effective = tab.session.ui.previewLocale ?? own;
+  /* The artboard's own rule, so the segment and the canvas cannot name two languages; a stored
+     choice the project no longer declares is not reported, because it is not drawn. */
+  const own = getEffectiveRenderLocale(null, tab.documentPath) ?? i18n.defaultLocale;
+  const effective = getEffectiveRenderLocale(tab.session.ui.previewLocale, tab.documentPath) ?? own;
   return { effective, i18n, overridden: effective !== own, pathLocale };
 }
 
@@ -848,7 +908,12 @@ function contextAxis(tab: Tab, paneId: string, ctx: PaneContextCtx): Partial<Pan
   ]
     .filter((part) => part !== null)
     .join(" · ");
-  const hasLayout = isPageDoc(tab) && Boolean(getEffectiveLayoutPath(tab.doc.document.$layout));
+  /* An entry written on the canvas is wrapped in its template's layout like a page (§22.5), so it
+     offers the same "show layout" choice. Whether a layout resolves for it is read asynchronously
+     by the canvas; the project default is the answer this bar can give synchronously. */
+  const hasLayout =
+    (isPageDoc(tab) && Boolean(getEffectiveLayoutPath(tab.doc.document.$layout))) ||
+    (Boolean(projectState?.isSiteProject) && writesEntryOnCanvas(tab.documentPath));
   const page = isPageDoc(tab);
   const params = page ? paramRows(tab) : [];
   const props = page ? [] : propRows(tab, paneId);
@@ -927,8 +992,9 @@ function sizeRows(
  * cannot and must not claim to translate the page. What it does change is real: the artboard's
  * `lang` and its `dir`, and an RTL locale mirrors the layout on the stage. A control that let an
  * author believe it had translated anything would be worse than no control — which is also why the
- * sentence stops there: the build's `$page.locale` is not injected into the canvas render today, so
- * a tooltip promising it would be describing the site rather than the pane.
+ * sentence stops there: the page's `$page.locale` comes from its route on the canvas as in the
+ * build (studio.md §4.1), so this control does not change it, and a tooltip promising otherwise
+ * would describe something the pane does not do.
  *
  * Labelled with each locale's AUTONYM, for the reason `localeLabel` gives: a reader looking for
  * their own language scans for their own word for it.
@@ -1098,6 +1164,22 @@ function actionsFor(paneId: string, ctx: PaneContextCtx): PaneContextActions {
       }
     },
     exportFile: ctx.exportFile,
+    /* The flow directly rather than `pane.backToHome`: the command's `when` keeps Escape away from
+       a text field and the code editor, and the CONTROL must work in both (Back from Code is the
+       Styles case). The pane is focused first, because the view going back is this pane's. */
+    goBack: () => {
+      focusPane(paneId);
+      const { closeTab } = ctx;
+      if (!closeTab) {
+        runContextCommand(paneId, "pane.backToHome", {});
+        return;
+      }
+      void goBack(paneId, {
+        closeTab,
+        setCanvasMode: ctx.setCanvasMode,
+        ...(ctx.focusHome && { focusHome: ctx.focusHome }),
+      });
+    },
     manageContexts: () => {
       void activeRegistry()?.run("settings.open", { section: "contexts" });
     },

package/src/panels/pane-grid.ts

@@ -312,12 +312,12 @@ function attachDropZone(paneId: string, element: HTMLElement): () => void {
  * One of a cell's five boxes has been created. Fill the record in, and wire what belongs to it.
  *
  * The context bar is HANDED its host rather than resolving a region, the same way
- * `panels/frontmatter-panel.ts` is handed the stage. It cannot resolve one the way the tab strip
- * does: the strip's host carries `pane.<id>/tabs` and nothing inside it re-stamps that id, while
- * the context bar stamps `pane.<id>/context` on markup it renders INSIDE its box — 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.
+ * `content/writing-banner.ts` is handed its host on the stage. It cannot resolve one the way the
+ * tab strip does: the strip's host carries `pane.<id>/tabs` and nothing inside it re-stamps that
+ * id, while the context bar stamps `pane.<id>/context` on markup it renders INSIDE its box — 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.
  */
 function cellPart(paneId: string, part: PaneCellPart, element: HTMLElement): void {
   const cell = cellState(paneId);

package/src/panels/panel-registry.ts

@@ -32,9 +32,9 @@ import { emptyContext } from "../commands/context";
 import { projectState } from "../store";
 import { shell } from "../shell";
 import { activeTab } from "../workspace/workspace";
+import { developerPanelsShown } from "../settings/developer-panels";
 import type { Level } from "../commands/levels";
 import type { CommandContext } from "../commands/context";
-import type { GitDiffState } from "../types";
 import type { JxMutableNode, JxStateDefinition } from "@jxsuite/schema/types";
 import type { JxPath } from "../state";
 import type { Tab, TabUi } from "../tabs/tab";
@@ -85,8 +85,6 @@ export interface NavigatorPanelDeps {
   registerLayersDnD: () => void;
   registerElementsDnD: () => void;
   registerComponentsDnD: () => void;
-  setGitDiffState: (state: GitDiffState | null) => void;
-  cloneRepository?: () => void;
 }
 
 /**
@@ -158,8 +156,13 @@ export interface PanelRecord {
    * losing its rail slot and gaining its real home (Insert, reachable from the canvas and palette;
    * State, folded into Data — §5.1). Declaring it `false` also removes the panel's `rail/<level>`
    * placement, which is what keeps the rail inside its four-per-group budget.
+   *
+   * `"developer"` is a rail button only while **Show developer panels** is on (§5.1,
+   * `settings/developer-panels.ts`): Files and Packages, which a site author does not need on the
+   * Design rail and a developer wants one click away. It keeps its rail placement either way, so
+   * the budget counts the button the switch can add.
    */
-  rail?: boolean;
+  rail?: boolean | "developer";
   /**
    * The sentence a document-level panel shows instead of its body when no document is open.
    *
@@ -208,6 +211,7 @@ export function panelContext(): CommandContext {
   ctx.project.isMultilingual =
     (resolveI18n(projectState?.projectConfig ?? {}).i18n?.locales.length ?? 0) > 1;
   ctx.git.dirtyCount = shell.git.status?.files.length ?? 0;
+  ctx.workspace.id = shell.workspace;
   ctx.document.open = activeTab.value !== null;
   return ctx;
 }
@@ -324,7 +328,8 @@ function railablePanels(): readonly PanelRecord[] {
  * @param {CommandContext} ctx
  */
 export function railGroups(ctx: CommandContext): RailGroup[] {
-  const railable = railablePanels();
+  const developer = developerPanelsShown();
+  const railable = railablePanels().filter((panel) => panel.rail !== "developer" || developer);
   return RAIL_GROUP_LEVELS.flatMap(({ level, label }) => {
     const panels = railable.filter((panel) => panel.level === level && isPanelVisible(panel, ctx));
     return panels.length > 0 ? [{ level, label, panels }] : [];
@@ -334,10 +339,10 @@ export function railGroups(ctx: CommandContext): RailGroup[] {
 /**
  * The rail's panels flattened into rail order — PROJECT group, then DOCUMENT group.
  *
- * This is the order ⌘1–8 follow, and it is derived from the same two rows the rail draws rather
- * than from registration order, so a panel registered by its dock's module (Problems, from
- * `panels/bottom-dock.ts`) still lands in the slot its LEVEL gives it. `when` is not applied: a
- * chord roster that changed length with context would move every chord after the hidden panel.
+ * This is the order the `panel.focus.*` records follow, and it is derived from the same two rows
+ * the rail draws rather than from registration order, so a panel registered by its dock's module
+ * still lands in the slot its LEVEL gives it. `when` is not applied: a roster that changed length
+ * with context would reorder the palette under the reader.
  */
 export function railPanelSet(): PanelRecord[] {
   const railable = railablePanels();

package/src/panels/properties-panel.ts

@@ -8,7 +8,7 @@
  *
  * - **Repeater · Switch · Observed Attributes · CSS Properties · CSS Parts → the Logic tab.** Wiring
  *   a `$switch` and wiring a click handler are the same task (`panels/events-panel.ts`).
- * - **The Page section → the Document Header card.** `panels/head-panel.ts` owns the one layout
+ * - **The Page section → the Inspector's Page tab.** `panels/head-panel.ts` owns the one layout
  *   picker; this panel drew a second one that could disagree with it.
  * - **Media breakpoint DEFINITIONS → Project Settings › Contexts** (§17.1). Nothing remains here: the
  *   only reason adding a breakpoint used to cost you your element selection.
@@ -1583,7 +1583,9 @@ function componentPropRows(
     if (isMediaFormat(prop.format)) {
       row.kind = "control";
       plan.control = (host) =>
-        mountMediaPicker(host, prop.name, staticVal, (v: string) => onChange(v));
+        mountMediaPicker(host, prop.name, staticVal, (v: string) => onChange(v), {
+          images: prop.format === "image",
+        });
     } else if (prop.format === "color") {
       row.kind = "color";
       row.tokens = colorTokens();
@@ -1784,7 +1786,9 @@ function attributeRow(
     row.kind = "control";
     const staticVal = isRef(value) ? "" : String(value || "");
     plan.control = (host) =>
-      mountMediaPicker(host, attr, staticVal, (v: string) => commitAttr(v || undefined));
+      mountMediaPicker(host, attr, staticVal, (v: string) => commitAttr(v || undefined), {
+        images: entry.format === "image",
+      });
   } else if (type === "select") {
     row.kind = "select";
     row.value = isRef(value) ? "" : String(value || "");