@jxsuite/studio 6.1.1 → 8.0.0

package/src/panels/collections-panel.ts

@@ -0,0 +1,306 @@
+/// <reference lib="dom" />
+/**
+ * The Collections panel — the Content workspace's Navigator panel (`specs/studio.md` §22.5).
+ *
+ * Two lists, chosen by what the focused pane shows:
+ *
+ * - **The collections.** The built-in Pages and every collection `project.json` declares, in
+ *   declaration order, each with its entry count (from the Content home's scan,
+ *   `browse/library-pane.ts`) and its saved grid views beneath it (`grid/grid-layout.ts`), and **+
+ *   New collection** at the foot. Choosing one shows it in the Content home
+ *   (`content.showCollection`); choosing a saved view opens the collection's grid on it.
+ * - **One collection's entries**, while an entry of it is the focused document: thumbnail, title and
+ *   status (`content/entry-summaries.ts`), under **‹ <Collection>** to go back, with **+ New
+ *   <item>** at the foot. Choosing one opens it where it is written (`content/entry-open.ts`).
+ *
+ * The markup is `surfaces/collections-panel.json`; this module is the flow. It is registered with
+ * no rail button: Content has no rail, and the workspace's frame opens the Navigator on it
+ * (`shell.ts`'s `WORKSPACE_PRESETS`).
+ *
+ * @docs studio/projects/browse
+ */
+
+import { nothing } from "lit-html";
+import { projectState, renderOnly } from "../store";
+import { activeTab } from "../workspace/workspace";
+import { runActiveReported } from "../commands/run-reported";
+import {
+  PAGES_COLLECTION,
+  collectionKeyOfPath,
+  contentCollection,
+  contentCollections,
+} from "../content/content-collections";
+import {
+  collectionCounts,
+  collectionEntryPaths,
+  collectionView,
+  shownCollectionKey,
+} from "../browse/library-pane";
+import { localeLabel, localeOfPath, resolveI18n } from "@jxsuite/schema/locale";
+import { entryLocale } from "../content/collection-pages";
+import { onEntrySummariesRead, peekEntrySummaries } from "../content/entry-summaries";
+import { openEntry } from "../content/entry-open";
+import { workspaceHomeTabId } from "../workspace/workspace-ids";
+import { makeGridTabId, parseGridTabId } from "../grid/grid-source";
+import { applySavedView, listSavedViews } from "../grid/grid-layout";
+import {
+  emptyCollectionsPanelValues,
+  mountCollectionsPanelSurface,
+} from "../surfaces/collections-panel";
+import { registerPanel } from "./panel-registry";
+import type {
+  CollectionEntryRow,
+  CollectionRow,
+  CollectionsPanelActions,
+  CollectionsPanelSurfaceHandle,
+  CollectionsPanelValues,
+} from "../surfaces/collections-panel";
+import type { Tab } from "../tabs/tab";
+
+/** The `source` every command run from here reports under. */
+const SOURCE = "Collections";
+
+/** The grid tab id a collection's saved views are stored under. */
+export function collectionGridId(key: string): string {
+  return key === PAGES_COLLECTION
+    ? makeGridTabId({ kind: "pages" })
+    : makeGridTabId({ kind: "collection", name: key });
+}
+
+/**
+ * The declared collection an entry tab is writing, or `null`: the focused document is a file a
+ * declared collection owns. Pages are Design's, so a page tab lists the collections. A file-backed
+ * collection's file is no entry either: its grid lists its records, so the panel lists the
+ * collections with that one selected.
+ */
+export function writingCollection(tab: Tab | null): string | null {
+  const key = collectionKeyOfPath(tab?.documentPath);
+  return key !== null && key !== PAGES_COLLECTION && !contentCollection(key)?.fileBacked
+    ? key
+    : null;
+}
+
+/** The file-backed collection whose file a tab holds, or `null`. */
+function fileCollectionOf(tab: Tab): string | null {
+  const key = collectionKeyOfPath(tab.documentPath);
+  return key !== null && contentCollection(key)?.fileBacked === true ? key : null;
+}
+
+/** The collection the focused pane is showing, for the list's selected row, or `null`. */
+function shownKey(tab: Tab | null): string | null {
+  if (!tab) {
+    return null;
+  }
+  if (tab.id === workspaceHomeTabId("content")) {
+    return shownCollectionKey();
+  }
+  const grid = parseGridTabId(tab.id);
+  if (grid?.kind === "pages") {
+    return PAGES_COLLECTION;
+  }
+  return grid?.kind === "collection" ? grid.name : fileCollectionOf(tab);
+}
+
+/** The collection list. */
+function collectionRows(tab: Tab | null): CollectionRow[] {
+  const counts = collectionCounts();
+  const selected = shownKey(tab);
+  return contentCollections().map((collection) => {
+    const count = counts?.get(collection.key);
+    return {
+      count: counts === null ? "" : String(count ?? 0),
+      key: collection.key,
+      selected: collection.key === selected ? "true" : "false",
+      title: collection.title,
+      views: listSavedViews(collectionGridId(collection.key)).map((view) => ({
+        key: `${collection.key}\n${view.name}`,
+        name: view.name,
+      })),
+    };
+  });
+}
+
+/** Everything the panel draws right now. */
+export function collectionsPanelValues(): CollectionsPanelValues {
+  const values = emptyCollectionsPanelValues();
+  if (!projectState) {
+    return values;
+  }
+  const tab = activeTab.value;
+  const writing = writingCollection(tab);
+  if (writing === null) {
+    return { ...values, body: "list", collections: collectionRows(tab) };
+  }
+  const collection = contentCollection(writing);
+  const counts = collectionCounts();
+  const paths = collectionEntryPaths(writing);
+  const summaries = counts === null ? null : peekEntrySummaries(writing, paths);
+  /* A multilingual collection's entries say which language each is in, and the list keeps to the
+     language the collection's view is filtered to: three translations of one exhibition are three
+     rows, and an unlabelled list of them reads as one entry listed thrice. */
+  const filter = collectionView(writing).locale;
+  const entries: CollectionEntryRow[] = (summaries ?? []).flatMap((entry) => {
+    const locale = entryLocale(entry.path) ?? "";
+    if (filter !== "" && locale !== filter) {
+      return [];
+    }
+    return [
+      {
+        art: entry.thumb === "" ? "glyph" : "image",
+        lang: locale,
+        locale: locale === "" ? "" : localeLabel(locale),
+        path: entry.path,
+        selected: entry.path === tab?.documentPath ? "true" : "false",
+        status: entry.status,
+        thumb: entry.thumb,
+        title: entry.title,
+      },
+    ];
+  });
+  return {
+    ...values,
+    backTitle: collection?.title ?? writing,
+    backCount: counts === null ? "" : String(paths.length),
+    body: "entries",
+    entries,
+    entriesState: summaries === null ? "loading" : entries.length === 0 ? "empty" : "listed",
+    newLabel: `New ${collection?.item ?? "entry"}`,
+  };
+}
+
+// ─── Actions ─────────────────────────────────────────────────────────────────
+
+/**
+ * Open a collection's grid on a saved view.
+ *
+ * The view is written onto the grid's working layout first, so a grid opened now loads it. A grid
+ * already on screen has loaded its layout, so it is told through `grid.applyView`, the command the
+ * grid's own picker runs.
+ */
+async function applyCollectionView(key: string, name: string): Promise<void> {
+  const gridId = collectionGridId(key);
+  const showing = activeTab.value?.id === gridId;
+  applySavedView(gridId, name);
+  if (showing) {
+    await runActiveReported("grid.applyView", { name }, SOURCE);
+    return;
+  }
+  const { openCollectionGrid, openPagesGrid } = await import("../grid/grid-open");
+  if (key === PAGES_COLLECTION) {
+    openPagesGrid();
+  } else {
+    openCollectionGrid(key);
+  }
+}
+
+const ACTIONS: CollectionsPanelActions = {
+  applyView: (key, name) => {
+    const [collection = ""] = key.split("\n");
+    void applyCollectionView(collection, name);
+  },
+  back: () => {
+    const writing = writingCollection(activeTab.value);
+    if (writing !== null) {
+      void runActiveReported("content.showCollection", { collection: writing }, SOURCE);
+    }
+  },
+  newCollection: () => {
+    void runActiveReported("file.new", { kind: "collection" }, SOURCE);
+  },
+  newEntry: () => {
+    const writing = writingCollection(activeTab.value);
+    void runActiveReported(
+      "file.new",
+      writing === null
+        ? { kind: "entry" }
+        : { collection: writing, kind: "entry", ...newEntryLocale(writing) },
+      SOURCE,
+    );
+  },
+  openEntry: (path) => {
+    void openEntry(path);
+  },
+  showCollection: (key) => {
+    void runActiveReported("content.showCollection", { collection: key }, SOURCE);
+  },
+};
+
+/**
+ * The language a new entry starts in from the entries list: the one the entry being written is in,
+ * else the one the collection's view is filtered to. Nothing when neither says, which leaves the
+ * dialog on the site's default.
+ */
+export function newEntryLocale(collection: string): { locale?: string } {
+  const { i18n } = resolveI18n(projectState?.projectConfig ?? {});
+  const path = activeTab.value?.documentPath ?? null;
+  const own = path === null ? null : localeOfPath(path, i18n);
+  const locale = own ?? collectionView(collection).locale;
+  return locale === "" ? {} : { locale };
+}
+
+// ─── Mounting ────────────────────────────────────────────────────────────────
+
+interface StandingPanel {
+  host: HTMLElement;
+  handle: CollectionsPanelSurfaceHandle;
+}
+
+let _standing: StandingPanel | null = null;
+let _unlisten: (() => void) | null = null;
+
+/** Repaint the Navigator, which repaints this panel when it is the one showing. */
+function repaint(): void {
+  renderOnly("leftPanel");
+}
+
+/** Mount the surface into `host`, or bring the one already there up to date. */
+function mountInto(host: HTMLElement): void {
+  _unlisten ??= onEntrySummariesRead(repaint);
+  if (_standing && (_standing.host !== host || !_standing.handle.connected())) {
+    _standing.handle.dispose();
+    _standing = null;
+  }
+  if (_standing) {
+    _standing.handle.update(collectionsPanelValues());
+    return;
+  }
+  _standing = {
+    handle: mountCollectionsPanelSurface(host, collectionsPanelValues(), ACTIONS),
+    host,
+  };
+}
+
+/**
+ * The Navigator's content area inside a panel body, where a mounted document goes (the reason is
+ * `panels/elements-panel.ts`'s: the body is lit's part, and its child is the box a panel owns).
+ */
+function contentArea(body: HTMLElement): HTMLElement {
+  return body.querySelector<HTMLElement>(".panel-content") ?? body;
+}
+
+/**
+ * Contribute the Collections panel: project level (it lists the project's collections), no rail
+ * button (Content has no rail), the Content workspace's Navigator.
+ */
+export function registerCollectionsPanel(): void {
+  registerPanel({
+    id: "collections",
+    title: "Collections",
+    level: "project",
+    dock: "navigator",
+    icon: "stack",
+    rail: false,
+    render: () => nothing,
+    afterRender: (_ctx, host) => {
+      mountInto(contentArea(host));
+    },
+  });
+}
+
+/** Forget the mounted panel — tests, and a project switch. */
+export function resetCollectionsPanel(): void {
+  _standing?.handle.dispose();
+  _standing = null;
+  _unlisten?.();
+  _unlisten = null;
+}

package/src/panels/component-preview.ts

@@ -9,28 +9,25 @@
 import { defineElement, setSkipServerFunctions } from "@jxsuite/runtime";
 import { projectState } from "../store";
 import type { ComponentEntry } from "../files/components";
+import type { JsonValue } from "@jxsuite/schema/types";
 
 /**
  * Render a live component preview by registering its custom element and instantiating it.
  *
  * @param {ComponentEntry} comp
+ * @param {ReadonlyMap<string, JsonValue>} [props] - Sample props (`browse/component-examples.ts`),
+ *   set as properties before the instance connects, the way a parent's `$props` reach it (spec.md
+ *   §16.2)
  * @returns {Promise<HTMLElement>}
  */
-export async function renderComponentPreview(comp: ComponentEntry) {
+export async function renderComponentPreview(
+  comp: ComponentEntry,
+  props: ReadonlyMap<string, JsonValue> = new Map(),
+) {
   setSkipServerFunctions(true);
   try {
-    if (comp.source === "npm") {
-      if (!customElements.get(comp.tagName)) {
-        return _componentFallback(comp.tagName);
-      }
-    } else {
-      if (comp.path && !comp.path.endsWith(".json")) {
-        // Format-class component sources (e.g. markdown) can't be imported as modules
-        return _componentFallback(comp.tagName);
-      }
-      const root = projectState?.projectRoot;
-      const url = `${location.origin}/${root ? `${root}/` : ""}${comp.path}`;
-      await defineElement(url);
+    if (!(await defineComponent(comp))) {
+      return _componentFallback(comp.tagName);
     }
     const el = document.createElement(comp.tagName);
     for (const p of comp.props || []) {
@@ -39,6 +36,13 @@ export async function renderComponentPreview(comp: ComponentEntry) {
         el.setAttribute(p.name, val);
       }
     }
+    // Read at connection as the instance's own props, ahead of the attribute defaults above.
+    /* SAFETY: an element is an ordinary extensible object, so any string key can be written; the
+       instance reads each declared prop back off itself when it connects. */
+    const properties = el as HTMLElement & Record<string, JsonValue>;
+    for (const [name, value] of props) {
+      properties[name] = value;
+    }
     return el;
   } catch (error) {
     console.warn("Component preview failed:", comp.tagName, error);
@@ -46,6 +50,24 @@ export async function renderComponentPreview(comp: ComponentEntry) {
   }
 }
 
+/**
+ * Make sure a component's element is defined in this window, registering a project definition from
+ * its file. Answers whether the tag can now be instantiated: a package's element only when its
+ * package already defined it, and a format-class source (Markdown) never, since it cannot be
+ * imported as a module.
+ */
+export async function defineComponent(comp: ComponentEntry): Promise<boolean> {
+  if (comp.source === "npm") {
+    return Boolean(customElements.get(comp.tagName));
+  }
+  if (comp.path && !comp.path.endsWith(".json")) {
+    return false;
+  }
+  const root = projectState?.projectRoot;
+  await defineElement(`${location.origin}/${root ? `${root}/` : ""}${comp.path}`);
+  return true;
+}
+
 /** @param {string} tagName */
 function _componentFallback(tagName: string) {
   const fallback = document.createElement("div");

package/src/panels/data-explorer.ts

@@ -2,6 +2,15 @@
 // ─── Data Explorer ──────────────────────────────────────────────────────────
 
 import { nothing } from "lit-html";
+import {
+  isBigInt,
+  isBoolean,
+  isFunction,
+  isNonNullObject,
+  isNumber,
+  isString,
+  isSymbol,
+} from "@jxsuite/schema/guards";
 import { activeTab } from "../workspace/workspace";
 import { booleanArg, stringArg, stringProperty } from "../commands/command-args";
 import { renderDataTreeSurface } from "../surfaces/panel-data";
@@ -9,6 +18,8 @@ import { registerPanel } from "./panel-registry";
 import type { PanelBody } from "./panel-registry";
 import type { DataTreeRow } from "../surfaces/panel-data";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
+import type { CommandArgValues } from "../commands/command-args";
+import type { ScopeRecord, ScopeValue } from "../editor/merge-tags";
 
 /**
  * The focused tab's expansion record, created on first write.
@@ -22,7 +33,7 @@ function rowsUi(): Record<string, boolean> | null {
   if (!ui) {
     return null;
   }
-  return (ui.dataRows ??= {});
+  return ui.dataRows;
 }
 
 /*
@@ -44,7 +55,7 @@ function limitsUi(): Record<string, number> | null {
   if (!ui) {
     return null;
   }
-  return (ui.dataLimits ??= {});
+  return ui.dataLimits;
 }
 
 /** The cap for one marker: the default, plus whatever the reader has asked for. */
@@ -89,34 +100,60 @@ function moreRow(
   };
 }
 
-/** A value as the tree prints it, capped at `max` characters. `undefined` prints as nothing. */
-function valueText(value: unknown, max: number): string {
-  if (typeof value === "string" && value.length > max) {
+/**
+ * A value as the tree prints it, capped at `max` characters. `undefined` prints as nothing, and so
+ * do a function and a symbol: those are the values `JSON.stringify` answers with no text at all.
+ */
+function valueText(value: ScopeValue, max: number): string {
+  if (isString(value) && value.length > max) {
     return `"${value.slice(0, max)}…"`;
   }
-  return JSON.stringify(value) ?? "";
+  return value === undefined || isFunction(value) || isSymbol(value) ? "" : JSON.stringify(value);
+}
+
+/** Each primitive kind, in the spelling `typeof` gives it, with the guard that establishes it. */
+const PRIMITIVE_KINDS: readonly (readonly [string, (value: ScopeValue) => boolean])[] = [
+  ["string", isString],
+  ["number", isNumber],
+  ["boolean", isBoolean],
+  ["bigint", isBigInt],
+  ["symbol", isSymbol],
+  ["function", isFunction],
+];
+
+/** The `typeof` name of a value that is neither `null` nor an object. */
+function primitiveKind(value: ScopeValue): string {
+  return PRIMITIVE_KINDS.find(([, test]) => test(value))?.[0] ?? "undefined";
 }
 
 /** Which colour a value takes. `null` and a summary label are the two the tree actually paints. */
-function toneOf(value: unknown): string {
-  return value === null ? "null" : typeof value;
+function toneOf(value: ScopeValue): string {
+  return value === null ? "null" : primitiveKind(value);
+}
+
+/**
+ * A value the tree can open: an array or a record. `isNonNullObject` is a `typeof "object"` test,
+ * so it already refuses a function; this predicate is what tells the type checker so.
+ */
+function isOpenable(value: ScopeValue): value is ScopeValue[] | ScopeRecord {
+  return isNonNullObject(value);
 }
 
 /** `Array(3)` or `{2}` — what a value you can open says while it is closed. */
-function summaryLabel(value: object): string {
+function summaryLabel(value: ScopeValue[] | ScopeRecord): string {
   return Array.isArray(value) ? `Array(${value.length})` : `{${Object.keys(value).length}}`;
 }
 
 /** Unwrap a Vue ref (has .value and .__v_isRef) to get the underlying value. */
-export function unwrapSignal(value: unknown) {
-  if (value && typeof value === "object" && (value as Record<string, unknown>).__v_isRef) {
-    return (value as Record<string, unknown>).value;
+export function unwrapSignal(value: ScopeValue): ScopeValue {
+  if (isOpenable(value) && !Array.isArray(value) && value.__v_isRef) {
+    return value.value;
   }
   return value;
 }
 
 /** Type label for a signal value in the data explorer. */
-export function dataTypeLabel(value: unknown) {
+export function dataTypeLabel(value: ScopeValue): string {
   const v = unwrapSignal(value);
   if (v === null) {
     return "null";
@@ -127,10 +164,10 @@ export function dataTypeLabel(value: unknown) {
   if (Array.isArray(v)) {
     return `Array(${v.length})`;
   }
-  if (typeof v === "object") {
+  if (isOpenable(v)) {
     return `{${Object.keys(v).length}}`;
   }
-  return typeof v;
+  return primitiveKind(v);
 }
 
 /* THE VALUE LIST IS GONE, AND ITS ROWS ARE THE DEFINITION ROWS — `panels/signals-panel.ts`.
@@ -148,14 +185,14 @@ export function dataTypeLabel(value: unknown) {
  * each carry their own indent. Nothing else changed: the caps are the same caps, the text is
  * truncated at the same lengths, and a capped list still ends in a marker.
  *
- * @param {unknown} value The resolved value to read.
+ * @param {ScopeValue} value The resolved value to read.
  * @param {number} depth How deep this call already is; the indent is derived from it.
  * @param {number} [maxDepth] The default depth cap, before whatever the reader has raised.
  * @param {string} path This subtree's path, which is what a raised limit is remembered against.
  * @returns {DataTreeRow[]}
  */
 export function dataTreeRows(
-  value: unknown,
+  value: ScopeValue,
   depth: number,
   maxDepth = 5,
   path = "",
@@ -182,21 +219,21 @@ export function dataTreeRows(
   if (value === null || value === undefined) {
     return [row("", String(value), "null", path)];
   }
-  if (typeof value !== "object") {
+  if (!isOpenable(value)) {
     return [row("", valueText(value, 200), toneOf(value), path)];
   }
 
   const array = Array.isArray(value);
-  const entries: [string, string, unknown][] = array
+  const entries: [string, string, ScopeValue][] = array
     ? value.map((item, i) => [`${i}`, `[${i}] `, item])
-    : Object.keys(value).map((key) => [key, `${key}: `, (value as Record<string, unknown>)[key]]);
+    : Object.keys(value).map((key) => [key, `${key}: `, value[key]]);
   const limit = array ? "items" : "keys";
   const cap = capFor(path, limit, array ? 20 : 30);
 
   const rows: DataTreeRow[] = [];
   for (const [segment, label, item] of entries.slice(0, cap)) {
     const childPath = `${path}/${segment}`;
-    if (item === null || item === undefined || typeof item !== "object") {
+    if (!isOpenable(item)) {
       rows.push(row(label, valueText(item, 80), toneOf(item), childPath));
       continue;
     }
@@ -222,14 +259,14 @@ export function dataTreeRows(
  * repaint instead of this sweeping per host.
  *
  * @param {HTMLElement} host The node the tree is drawn into.
- * @param {unknown} value What the canvas resolved this entry to.
+ * @param {ScopeValue} value What the canvas resolved this entry to.
  * @param {string} path The subtree's path, which is what a raised limit is remembered against.
  * @param {() => void} rerender Repaint the panel, so that a raised limit is drawn.
  * @param {number} [maxDepth] The default depth cap, before whatever the reader has raised.
  */
 export function paintDataTree(
   host: HTMLElement,
-  value: unknown,
+  value: ScopeValue,
   path: string,
   rerender: () => void,
   maxDepth = 5,
@@ -327,7 +364,7 @@ export function dataExplorerCommands(deps: DataExplorerCommandDeps): AnyCommand[
       group: "5_data",
       requires: "an open document that defines data",
       when: (ctx) => ctx.document.open,
-      run: (_commandCtx, args) => {
+      run: (_commandCtx, args: CommandArgValues) => {
         const name = stringArg("data.expandRow", args, "name");
         const defined = definedDataNames();
         if (!defined.includes(name)) {
@@ -336,7 +373,7 @@ export function dataExplorerCommands(deps: DataExplorerCommandDeps): AnyCommand[
               `document — it defines: ${defined.length > 0 ? defined.join(", ") : "nothing"}`,
           );
         }
-        const { expanded } = args as { expanded?: unknown };
+        const { expanded } = args;
         // `expanded` defaults to true but is never COERCED: `{ expanded: "no" }` would otherwise
         // Read as a collapse, which is the class of silent wrong answer this whole record exists
         // To stop.
@@ -382,7 +419,7 @@ export function registerDataExplorerCommands(
  * **Both halves are documents now** — `surfaces/panel-signals.{json,ts}` for the entry list and its
  * editors, `surfaces/panel-data.{json,ts}` for the value tree under an open row. So lit draws
  * nothing at all here: `render` returns `nothing` and `afterRender` mounts against the painted DOM,
- * which is the seam `panels/git-panel.ts` uses for the same reason. The mount comes through `deps`
+ * which is the seam every document-bodied Navigator panel uses. The mount comes through `deps`
  * rather than an import — this module owns the expansion store that one reads, so importing it back
  * would close a cycle — and it is idempotent, so running on every repaint is what keeps the
  * projection current.

package/src/panels/data-grid.ts

@@ -23,10 +23,11 @@ import { mountDataActionsSurface } from "../surfaces/data-actions";
 import { mountPushPlanSurface } from "../surfaces/push-plan";
 import { dataSurfaceAvailable, pushSchema, testConnection } from "../services/data-service";
 import { openGridSourcePicker } from "../grid/grid-open";
+import { closeSettingsDialog } from "../settings/settings-dialog";
 import type { DataActionsSurfaceHandle, DataActionsView } from "../surfaces/data-actions";
 import type { DialogSurfaceHandle } from "../surfaces/dialog";
 import type { PushPlanSurfaceHandle, PushPlanView } from "../surfaces/push-plan";
-import type { DataConnectionTestResult, DataPushResult } from "../types";
+import type { DataConnectionTestResult, DataPushRequest, DataPushResult } from "../types";
 import type { SectionActionsContext } from "../settings/contributed-section";
 
 // ─── Grid opening (delegates to the grid-tab source picker) ──────────────────
@@ -75,7 +76,7 @@ function noteRows(texts: readonly string[], prefix: string) {
 }
 
 /** What the body lists: the dry run until it has been applied, then what actually happened. */
-function planView(state: PushDialogState): PushPlanView {
+function planView(state: Pick<PushDialogState, "dryRun" | "phase" | "result">): PushPlanView {
   const shown = state.phase === "done" ? state.result : state.dryRun;
   return {
     errors: noteRows(shown?.errors ?? [], "error"),
@@ -129,27 +130,28 @@ export async function startPush(connection: string | undefined, onDone: () => vo
   if (pushDialog) {
     return;
   }
-  const state: PushDialogState = {
+  /* The dialog's callbacks need the state record and the record needs the dialog's handle, so the
+     record is built first and completed with the handle below; it stays one object throughout. */
+  const pending: Omit<PushDialogState, "handle"> = {
     connection,
     dryRun: null,
-    handle: null as unknown as DialogSurfaceHandle,
     onDone,
     phase: "loading",
     plan: null,
     result: null,
   };
-  state.handle = openDialogSurface({
+  const handle = openDialogSurface({
     cancelLabel: "Cancel",
     confirmLabel: "",
     headline: connection ? `Push Schema — ${connection}` : "Push Schema",
     island: (host) => {
-      state.plan = mountPushPlanSurface(host, planView(state));
+      pending.plan = mountPushPlanSurface(host, planView(pending));
     },
     layer: layerHost("dialog"),
     message: "Compiling plan…",
     onCancel: closePushDialog,
     onClosed: () => {
-      if (pushDialog === state) {
+      if (pushDialog === pending) {
         closePushDialog();
       }
     },
@@ -158,12 +160,14 @@ export async function startPush(connection: string | undefined, onDone: () => vo
     },
     region: "data/push",
   });
+  const state: PushDialogState = Object.assign(pending, { handle });
   pushDialog = state;
 
-  const plan = await pushSchema({
-    dryRun: true,
-    ...(connection === undefined ? {} : { connection }),
-  });
+  const request: DataPushRequest = { dryRun: true };
+  if (connection !== undefined) {
+    request.connection = connection;
+  }
+  const plan = await pushSchema(request);
   if (pushDialog !== state) {
     return;
   }
@@ -274,6 +278,9 @@ function paintSectionActions(
     host,
     mountDataActionsSurface(host, projectActions(sectionKey, selected), {
       openGrid: () => {
+        /* The actions row is drawn in the settings dialog, and a grid opens as a TAB: left up, the
+           dialog would cover the very tab the reader asked for (§17.1). */
+        closeSettingsDialog();
         void openGridSourcePicker();
       },
       push: () => {