@jxsuite/studio 6.1.1 → 8.0.0

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
  */
@@ -63,6 +63,7 @@ import type {
   I18nSurfaceHandle,
   I18nValues,
 } from "../surfaces/panel-i18n";
+import type { CommandArgValues } from "../commands/command-args";
 import type { LibraryFile, ScanFailure } from "../browse/library-model";
 import type { NavigatorPanelContext, PanelBody } from "./panel-registry";
 import type { ResolvedI18n } from "@jxsuite/schema/locale";
@@ -189,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
@@ -235,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[],
@@ -254,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.filter((f) => f.category !== "Media").map((f) => translationKeyOfPath(f.path, i18n)),
+    files.flatMap((f) => (f.media ? [] : [translationKeyOfPath(f.path, i18n)])),
   );
   const keyOf = (file: LibraryFile): string => {
     const own = declared.get(file.path);
@@ -277,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);
@@ -401,7 +402,7 @@ function cellTitle(cell: ParityCell, locale: string, refusal: string | undefined
  * report is what makes the next such drift a sentence in the Problems panel rather than an
  * exception out of a click.
  */
-function runByName(id: string, args: Record<string, unknown> = {}): void {
+function runByName(id: string, args: CommandArgValues = {}): void {
   const registry = activeRegistry();
   if (!registry?.get(id)) {
     return;
@@ -437,7 +438,13 @@ function projectRow(row: ParityRow, i18n: ResolvedI18n): I18nParityRow {
 }
 
 /** How many squares are not yet a file, and how many are behind their source. */
-function countCells(rows: readonly ParityRow[]): { missing: number; stale: number } {
+interface CellCounts {
+  missing: number;
+  stale: number;
+}
+
+/** Tallies {@link CellCounts} over every square of the grid. */
+function countCells(rows: readonly ParityRow[]): CellCounts {
   let missing = 0;
   let stale = 0;
   for (const row of rows) {
@@ -535,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();
@@ -599,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

@@ -21,6 +21,7 @@
  * turn, where a Navigator repaint is a frame away and would rebuild far more than one field.
  */
 
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
 import { nothing } from "lit-html";
 import { componentRegistry } from "../files/components";
 import {
@@ -46,9 +47,9 @@ import type {
   ImportsActions,
   ImportsView,
   PackageRow,
-  PickerOption,
 } from "../surfaces/panel-imports";
-import type { JxElement, JxMutableNode } from "@jxsuite/schema/types";
+import type { JxMutableNode } from "@jxsuite/schema/types";
+import type { SurfaceOption } from "../ui/surface";
 
 /** What the panel is drawn against. `left-panel.ts`'s context, reduced to what this reads. */
 export interface ImportsContext {
@@ -105,17 +106,19 @@ function groupByPackage() {
     if (comp.source !== "npm" || !comp.package || !comp.modulePath) {
       continue;
     }
-    if (!groups.has(comp.package)) {
-      groups.set(comp.package, []);
+    let group = groups.get(comp.package);
+    if (!group) {
+      group = [];
+      groups.set(comp.package, group);
     }
-    groups.get(comp.package)?.push(comp);
+    group.push(comp);
   }
   return groups;
 }
 
 /** The project's `$elements`, as the site-level mood reads and rewrites it. */
 function siteElements(): ElementsEntry[] {
-  return (projectState?.projectConfig?.$elements ?? []) as ElementsEntry[];
+  return projectState?.projectConfig?.$elements ?? [];
 }
 
 /**
@@ -163,19 +166,15 @@ function siteView(): ImportsView {
 /** The document-level mood: this document's component imports, and what it could still import. */
 function documentView(ctx: ImportsContext): ImportsView {
   const { documentElements, documentPath } = ctx;
-  const refs = documentElements
-    .filter(
-      (entry): entry is { $ref: string } =>
-        Boolean(entry) &&
-        typeof entry === "object" &&
-        typeof (entry as { $ref?: unknown }).$ref === "string",
-    )
-    .map((entry) => ({ ref: entry.$ref }));
+  const refs = documentElements.flatMap((entry) => {
+    const ref = isNonNullObject(entry) ? entry.$ref : undefined;
+    return isString(ref) ? [{ ref }] : [];
+  });
   /* The checkbox reads the STRING entries only. A `$ref` is a project component and is listed
      above; letting it answer here would tick an npm box for a file that happens to share a name. */
-  const npmEntries = documentElements.filter((entry) => typeof entry === "string");
+  const npmEntries = documentElements.filter((entry) => isString(entry));
   const imported = new Set(refs.map((entry) => entry.ref));
-  const available: PickerOption[] = componentRegistry
+  const available: SurfaceOption[] = componentRegistry
     .filter(
       (comp: ComponentEntry) =>
         comp.source !== "npm" &&
@@ -276,7 +275,7 @@ async function onRemovePackage(pkg: string): Promise<void> {
     const updated = removePackageElements(siteElements(), pkg);
     const { loadComponentRegistry } = await import("../files/components.js");
     await loadComponentRegistry();
-    await updateSiteConfig({ $elements: updated as (string | JxElement)[] });
+    await updateSiteConfig({ $elements: updated });
     context()?.renderLeftPanel();
   } catch (error) {
     console.error("Failed to remove package:", error);
@@ -301,17 +300,15 @@ async function onToggleComponent(id: string, checked: boolean): Promise<void> {
     const updated = checked
       ? enableElement(before, comp, null)
       : disableElement(before, comp, null);
-    await updateSiteConfig({ $elements: updated as (string | JxElement)[] });
+    await updateSiteConfig({ $elements: updated });
     ctx.renderLeftPanel();
     return;
   }
   ctx.applyMutation((doc: JxMutableNode) => {
-    const before = (doc.$elements ?? []) as ElementsEntry[];
-    doc.$elements = (
-      checked
-        ? enableElement(before, comp, ctx.documentPath)
-        : disableElement(before, comp, ctx.documentPath)
-    ) as (string | JxElement)[];
+    const before = doc.$elements ?? [];
+    doc.$elements = checked
+      ? enableElement(before, comp, ctx.documentPath)
+      : disableElement(before, comp, ctx.documentPath);
   });
   ctx.renderLeftPanel();
 }
@@ -339,11 +336,7 @@ function onPick(value: string): void {
   /* Through the service, which is also what makes this idempotent: it checked nothing and pushed a
      second `$ref` every time you chose the same component. */
   ctx.applyMutation((doc: JxMutableNode) => {
-    doc.$elements = enableElement(
-      (doc.$elements ?? []) as ElementsEntry[],
-      comp,
-      ctx.documentPath,
-    ) as (string | JxElement)[];
+    doc.$elements = enableElement(doc.$elements ?? [], comp, ctx.documentPath);
   });
   ctx.renderLeftPanel();
 }
@@ -355,10 +348,7 @@ function onRemoveRef(elementRef: string): void {
     return;
   }
   ctx.applyMutation((doc: JxMutableNode) => {
-    doc.$elements = removeElementRef((doc.$elements ?? []) as ElementsEntry[], elementRef) as (
-      | string
-      | JxElement
-    )[];
+    doc.$elements = removeElementRef(doc.$elements ?? [], elementRef);
   });
   ctx.renderLeftPanel();
 }
@@ -437,20 +427,6 @@ function contentArea(body: HTMLElement): HTMLElement {
   return body.querySelector<HTMLElement>(".panel-content") ?? body;
 }
 
-/**
- * The Navigator no longer draws this panel with lit.
- *
- * The record below returns `nothing` and mounts its document in `afterRender`, so this is a stub:
- * it survives only because `NavigatorPanelDeps` still declares the injection and `studio.ts` still
- * passes it. Both go in the change that deletes this.
- *
- * @deprecated The panel is `surfaces/panel-imports.json`; call {@link renderImportsPanel}.
- * @returns {typeof nothing}
- */
-export function renderImportsTemplate(_against: ImportsContext): typeof nothing {
-  return nothing;
-}
-
 /**
  * Contribute the Packages panel.
  *
@@ -466,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

@@ -63,8 +63,9 @@
  * @docs studio/interface
  */
 
-import { displayTagName } from "@jxsuite/schema/guards";
-import { childList, getNodeAtPath, nodeLabel, pathsEqual, projectState } from "../store";
+import { displayTagName, isNonNullObject, isString } from "@jxsuite/schema/guards";
+import { getNodeAtPath } from "@jxsuite/schema/doc-ops";
+import { childList, nodeLabel, pathsEqual, projectState } from "../store";
 import { effect, effectScope } from "../reactivity";
 import { activePane, workspace } from "../workspace/workspace";
 import { derivationOfPane, tabOfPane } from "../canvas/canvas-surface";
@@ -74,14 +75,23 @@ import { runReported } from "../commands/run-reported";
 import { openMenu } from "../surfaces/menu";
 import { rectOf } from "../utils/geometry";
 import { mountJumpBarSurface } from "../surfaces/jump-bar";
-import type { CommandArgs, CommandRegistry } from "../commands/registry";
+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";
-import type { MenuHandle, MenuRowProjection } from "../surfaces/menu";
+import type {
+  MenuHandle,
+  MenuRowProjection,
+  OpenMenuOptions,
+  ViewportPoint,
+} from "../surfaces/menu";
 import type { JumpBarSurface, ProjectedStep } from "../surfaces/jump-bar";
 import type { Tab } from "../tabs/tab";
 import type { PaneDerivation } from "../workspace/workspace";
 import type { EffectScope } from "@vue/reactivity";
+import type { JxMutableNode } from "@jxsuite/schema/types";
+import type { CommandArgValues } from "../commands/command-args";
 
 /**
  * The region the trail stamps on itself. It is the status bar's DOCUMENT field: the document, and
@@ -108,7 +118,7 @@ export type JumpSegmentKind = "file" | "editor" | "node";
 export interface JumpChoice {
   label: string;
   command: string;
-  args?: CommandArgs;
+  args?: CommandArgValues;
   /** The choice you are already on. Marked, never hidden — a menu that omits it loses its place. */
   current?: boolean;
 }
@@ -121,7 +131,7 @@ export interface JumpSegment {
   title?: string;
   /** The command that MOVES you here, or `null` when you are already here. */
   command: string | null;
-  args?: CommandArgs;
+  args?: CommandArgValues;
   /** Where else this step could go. Fewer than two is not a choice, and renders no control. */
   choices: readonly JumpChoice[];
 }
@@ -144,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. */
@@ -160,19 +194,19 @@ export interface SelectionCrumb {
  * array pseudo-element ("Repeater") and its template both visible instead of collapsing the array
  * into a bare `[index]`.
  */
-export function selectionCrumbs(document: unknown, selection: JxPath): SelectionCrumb[] {
+export function selectionCrumbs(document: JxMutableNode, selection: JxPath): SelectionCrumb[] {
   const crumbs: SelectionCrumb[] = [];
   for (let i = 0; i < selection.length;) {
     const seg = selection[i];
     const step = seg === "map" ? 1 : 2;
-    const path = selection.slice(0, i + step) as JxPath;
-    const node = getNodeAtPath(document as never, path);
+    const path = selection.slice(0, i + step);
+    const node = getNodeAtPath(document, path);
     const fallbackTag = node?.tag;
     const label =
       node?.$prototype === "Array"
         ? "Repeater"
         : displayTagName(node?.tagName) ||
-          (typeof fallbackTag === "string" ? fallbackTag : "") ||
+          (isString(fallbackTag) ? fallbackTag : "") ||
           (seg === "cases" ? String(selection[i + 1]) : `[${selection[i + 1]}]`);
     crumbs.push({ label, path });
     i += step;
@@ -191,7 +225,7 @@ export function selectionCrumbs(document: unknown, selection: JxPath): Selection
  * addressable, so both drop out and the segment renders no control at all.
  */
 export function crumbSiblings(
-  document: unknown,
+  document: JxMutableNode,
   crumbs: readonly SelectionCrumb[],
   index: number,
 ): JumpChoice[] {
@@ -199,17 +233,17 @@ export function crumbSiblings(
   if (!crumb) {
     return [];
   }
-  const parentPath = (index === 0 ? [] : crumbs[index - 1]!.path) as JxPath;
-  const parent = getNodeAtPath(document as never, parentPath);
+  const parentPath: JxPath = index === 0 ? [] : crumbs[index - 1]!.path;
+  const parent = getNodeAtPath(document, parentPath);
   const key = crumb.path.at(-2);
   const own = crumb.path;
   if (key === "cases") {
     const cases = parent?.cases;
-    if (!cases || typeof cases !== "object") {
+    if (!isNonNullObject(cases)) {
       return [];
     }
     return Object.keys(cases).map((name) => {
-      const path = [...parentPath, "cases", name] as JxPath;
+      const path: JxPath = [...parentPath, "cases", name];
       return choiceFor(document, path, name, own);
     });
   }
@@ -218,17 +252,22 @@ export function crumbSiblings(
   }
   const choices: JumpChoice[] = [];
   for (const [i, child] of childList(parent).entries()) {
-    if (typeof child === "string") {
+    if (isString(child)) {
       continue;
     }
-    const path = [...parentPath, "children", i] as JxPath;
+    const path: JxPath = [...parentPath, "children", i];
     choices.push(choiceFor(document, path, nodeLabel(child), own));
   }
   return choices;
 }
 
-function choiceFor(document: unknown, path: JxPath, fallback: string, own: JxPath): JumpChoice {
-  const node = getNodeAtPath(document as never, path);
+function choiceFor(
+  document: JxMutableNode,
+  path: JxPath,
+  fallback: string,
+  own: JxPath,
+): JumpChoice {
+  const node = getNodeAtPath(document, path);
   const label = node ? nodeLabel(node) : fallback;
   const choice: JumpChoice = { args: { path }, command: "selection.set", label };
   // `pathsEqual`, not a joined key: a separator is a guess about what a segment cannot contain,
@@ -271,15 +310,13 @@ 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),
     },
   ];
 
   // A logic editor is the leaf of the address, and it has no selection under it: the Monaco buffer
   // And the formula workspace are editing a definition, not a node of the document tree.
-  const editingFunction = tab.session.ui.editingFunction as FunctionEditDef | null;
-  const editingFormula = tab.session.ui.editingFormula as FormulaEditDef | null;
+  const { editingFormula, editingFunction } = tab.session.ui;
   if (editingFunction) {
     segments.push(editorSegment("ƒ", editingFunction));
     return segments;
@@ -333,9 +370,7 @@ function editorSegment(sigil: string, def: FunctionEditDef | FormulaEditDef): Ju
  */
 function stepKey(segment: JumpSegment): string {
   const path = segment.args?.path;
-  return segment.kind === "node" && Array.isArray(path)
-    ? `node:${(path as JxPath).join("/")}`
-    : segment.kind;
+  return segment.kind === "node" && Array.isArray(path) ? `node:${path.join("/")}` : segment.kind;
 }
 
 /** Whether the registry can actually run this id right now. */
@@ -446,7 +481,7 @@ function openChoices(segment: JumpSegment, anchor: HTMLElement | null): void {
     },
     title: choice.label,
   }));
-  const handle = openMenu({
+  const options: OpenMenuOptions = {
     label: `Go to a sibling of ${segment.label}`,
     onClosed: (closed) => {
       if (_menu === closed) {
@@ -455,10 +490,13 @@ function openChoices(segment: JumpSegment, anchor: HTMLElement | null): void {
     },
     opener: anchor,
     placement: ABOVE_OPENER,
-    ...(anchor ? { place: (box: DOMRect) => aboveOpener(anchor, box) } : {}),
     region: "jump-bar",
     rows,
-  });
+  };
+  if (anchor) {
+    options.place = (box: DOMRect) => aboveOpener(anchor, box);
+  }
+  const handle = openMenu(options);
   _menu = handle;
 }
 
@@ -466,13 +504,19 @@ function openChoices(segment: JumpSegment, anchor: HTMLElement | null): void {
  * The menu's corner when it hangs above `anchor`: its bottom on the anchor's top, leading edges
  * aligned.
  */
-export function aboveOpener(anchor: HTMLElement, box: DOMRect): { x: number; y: number } {
+export function aboveOpener(anchor: HTMLElement, box: DOMRect): ViewportPoint {
   const rect = rectOf(anchor);
   return { x: Math.round(rect.left), y: Math.max(0, Math.round(rect.top - box.height)) };
 }
 
 /** The address of the focused pane, and the segments behind it. */
-function projectFocused(): { steps: ProjectedStep[]; segments: JumpSegment[] } {
+interface FocusedAddress {
+  steps: ProjectedStep[];
+  segments: JumpSegment[];
+}
+
+/** Projects {@link FocusedAddress} for the focused pane. */
+function projectFocused(): FocusedAddress {
   const paneId = activePane().id;
   const segments = jumpSegments(tabOfPane(paneId), derivationOfPane(paneId));
   const registry = activeRegistry();