@jxsuite/studio 6.1.1 → 8.0.0

package/src/workspace/session.ts

@@ -25,9 +25,17 @@
  * across versions. Every field is validated on the way in and a bad record restores nothing.
  */
 
-import { PRIMARY_PANE, SECONDARY_PANE, focusPane, workspace } from "./workspace";
+import { PRIMARY_PANE, SECONDARY_PANE, activateTab, focusPane, workspace } from "./workspace";
+import {
+  isBoolean,
+  isJsonObject,
+  isNonNullObject,
+  isNumber,
+  isString,
+} from "@jxsuite/schema/guards";
 import { isWellFormedLocale } from "@jxsuite/schema/locale";
-import type { Tab } from "../tabs/tab";
+import type { JsonValue } from "@jxsuite/schema/types";
+import type { Tab, TabUi } from "../tabs/tab";
 
 /** One pane's share of a session. */
 export interface PersistedPane {
@@ -46,7 +54,7 @@ export interface PersistedTabUi {
   zoom?: number;
   editZoom?: number;
   activeMedia?: string | null;
-  previewColorScheme?: string;
+  previewColorScheme?: TabUi["previewColorScheme"];
   /** BCP 47 tag, or `null` for "the document's own language". */
   previewLocale?: string | null;
   showLayout?: boolean;
@@ -62,7 +70,12 @@ export interface PersistedSession {
 }
 
 const PANE_IDS = new Set([PRIMARY_PANE, SECONDARY_PANE]);
-const SCHEMES = new Set(["auto", "light", "dark"]);
+const SCHEMES: ReadonlySet<string> = new Set(["auto", "light", "dark"]);
+
+/** Whether a stored value is one of the three schemes a tab's preview may be forced into. */
+function isColorScheme(value: JsonValue | undefined): value is TabUi["previewColorScheme"] {
+  return isString(value) && SCHEMES.has(value);
+}
 
 /** The view settings this tab was left in — the ones a person chose, not the ones derived. */
 function uiOf(tab: Tab): PersistedTabUi {
@@ -118,40 +131,42 @@ export function captureSession(): PersistedSession {
 }
 
 /** Whether a parsed value is a usable {@link PersistedTabUi}. Hand-edited storage is input. */
-function readTabUi(value: unknown): PersistedTabUi {
-  if (typeof value !== "object" || value === null) {
+function readTabUi(value: JsonValue | undefined): PersistedTabUi {
+  if (!isJsonObject(value)) {
     return {};
   }
-  const raw = value as Record<string, unknown>;
   const out: PersistedTabUi = {};
-  if (typeof raw.canvasMode === "string") {
-    out.canvasMode = raw.canvasMode;
+  if (isString(value.canvasMode)) {
+    out.canvasMode = value.canvasMode;
   }
-  if (typeof raw.preview === "boolean") {
-    out.preview = raw.preview;
+  if (isBoolean(value.preview)) {
+    out.preview = value.preview;
   }
-  if (typeof raw.zoom === "number" && Number.isFinite(raw.zoom)) {
-    out.zoom = raw.zoom;
+  if (isNumber(value.zoom) && Number.isFinite(value.zoom)) {
+    out.zoom = value.zoom;
   }
-  if (typeof raw.editZoom === "number" && Number.isFinite(raw.editZoom)) {
-    out.editZoom = raw.editZoom;
+  if (isNumber(value.editZoom) && Number.isFinite(value.editZoom)) {
+    out.editZoom = value.editZoom;
   }
-  if (raw.activeMedia === null || typeof raw.activeMedia === "string") {
-    out.activeMedia = raw.activeMedia;
+  if (value.activeMedia === null || isString(value.activeMedia)) {
+    out.activeMedia = value.activeMedia;
   }
-  if (typeof raw.previewColorScheme === "string" && SCHEMES.has(raw.previewColorScheme)) {
-    out.previewColorScheme = raw.previewColorScheme;
+  if (isColorScheme(value.previewColorScheme)) {
+    out.previewColorScheme = value.previewColorScheme;
   }
   /* `null` is a value here, not an absence: it is "the document's own language", so a pane put
      deliberately back onto its own file's language would otherwise restore the tag it left.
      A tag is checked for WELL-FORMEDNESS only — whether the project still declares it is a
      question about `project.json`, which the reader cannot see and which changes between sessions;
      the control refuses an undeclared tag on the way in and the render falls back on the way out. */
-  if (raw.previewLocale === null || isWellFormedLocale(raw.previewLocale)) {
-    out.previewLocale = raw.previewLocale as string | null;
+  if (
+    value.previewLocale === null ||
+    (isString(value.previewLocale) && isWellFormedLocale(value.previewLocale))
+  ) {
+    out.previewLocale = value.previewLocale;
   }
-  if (typeof raw.showLayout === "boolean") {
-    out.showLayout = raw.showLayout;
+  if (isBoolean(value.showLayout)) {
+    out.showLayout = value.showLayout;
   }
   return out;
 }
@@ -159,35 +174,28 @@ function readTabUi(value: unknown): PersistedTabUi {
 /**
  * Validate a stored session. Returns `null` for anything that is not one — a corrupt record
  * restores nothing rather than restoring half a workspace.
+ *
+ * The input is whatever `JSON.parse` gave back for the stored record (or `undefined` when the
+ * project record has no session), so every field is decoded here rather than trusted.
  */
-export function readSession(value: unknown): PersistedSession | null {
-  if (typeof value !== "object" || value === null) {
-    return null;
-  }
-  const raw = value as Partial<PersistedSession>;
-  if (!Array.isArray(raw.panes)) {
+export function readSession(value: JsonValue | undefined): PersistedSession | null {
+  if (!isJsonObject(value) || !Array.isArray(value.panes)) {
     return null;
   }
   const panes: PersistedPane[] = [];
-  for (const entry of raw.panes) {
-    if (typeof entry !== "object" || entry === null) {
-      continue;
-    }
-    const pane = entry as Partial<PersistedPane>;
-    if (typeof pane.id !== "string" || !PANE_IDS.has(pane.id)) {
+  for (const pane of value.panes) {
+    if (!isJsonObject(pane) || !isString(pane.id) || !PANE_IDS.has(pane.id)) {
       continue;
     }
     const files = Array.isArray(pane.files)
-      ? pane.files.filter((file): file is string => typeof file === "string" && file !== "")
+      ? pane.files.filter((file): file is string => isString(file) && file !== "")
       : [];
     if (files.length === 0) {
       continue;
     }
     panes.push({
       activeFile:
-        typeof pane.activeFile === "string" && files.includes(pane.activeFile)
-          ? pane.activeFile
-          : null,
+        isString(pane.activeFile) && files.includes(pane.activeFile) ? pane.activeFile : null,
       files,
       id: pane.id,
     });
@@ -196,15 +204,17 @@ export function readSession(value: unknown): PersistedSession | null {
     return null;
   }
   const ui: Record<string, PersistedTabUi> = {};
-  if (typeof raw.ui === "object" && raw.ui !== null) {
-    for (const [path, entry] of Object.entries(raw.ui as Record<string, unknown>)) {
+  /* `isNonNullObject`, not `isJsonObject`: a hand-edited array here has always been read entry by
+     entry under its index keys, and this decoder keeps that rather than silently dropping it. */
+  if (isNonNullObject(value.ui)) {
+    for (const [path, entry] of Object.entries(value.ui)) {
       ui[path] = readTabUi(entry);
     }
   }
   return {
     focusedPane:
-      typeof raw.focusedPane === "string" && PANE_IDS.has(raw.focusedPane)
-        ? raw.focusedPane
+      isString(value.focusedPane) && PANE_IDS.has(value.focusedPane)
+        ? value.focusedPane
         : PRIMARY_PANE,
     panes,
     ui,
@@ -288,7 +298,7 @@ export async function restoreSession(
       ui.activeMedia = stored.activeMedia;
     }
     if (stored.previewColorScheme !== undefined) {
-      ui.previewColorScheme = stored.previewColorScheme as "auto" | "dark" | "light";
+      ui.previewColorScheme = stored.previewColorScheme;
     }
     if (stored.previewLocale !== undefined) {
       ui.previewLocale = stored.previewLocale;
@@ -297,8 +307,22 @@ export async function restoreSession(
       ui.showLayout = stored.showLayout;
     }
   }
-  // Each pane's active tab, then the pane that had the keyboard — in that order, because activating
-  // A tab in a pane is what makes that pane's strip meaningful and focusing comes last.
+  /*
+   * Each pane's active tab, then the pane that had the keyboard, in that order, because activating
+   * a tab in a pane is what makes that pane's strip meaningful and focusing comes last.
+   *
+   * The focused pane's tab is ACTIVATED, not merely assigned, because the restored tab is the most
+   * recently used one and the workspace switch that follows a restore asks exactly that question.
+   * Every document was reopened without moving the keyboard, so the MRU list was empty, and
+   * `focusPane` adds nothing for the pane that already has the keyboard. Entering the stored
+   * workspace then fell back to that workspace's FIRST tab in the strip: two exhibition entries
+   * restored with the English one active came back on whichever was opened first, and a Design
+   * session left on `/exhibitions` came back on `/`.
+   */
+  const focused = workspace.panes.some((pane) => pane.id === session.focusedPane)
+    ? session.focusedPane
+    : null;
+  let focusedTab: string | null = null;
   for (const stored of session.panes) {
     const pane = workspace.panes.find((p) => p.id === stored.id);
     if (!pane || !stored.activeFile) {
@@ -307,12 +331,19 @@ export async function restoreSession(
     const match = pane.tabOrder.find(
       (tabId) => workspace.tabs.get(tabId)?.documentPath === stored.activeFile,
     );
-    if (match) {
-      pane.activeTabId = match;
+    if (!match) {
+      continue;
+    }
+    if (pane.id === focused) {
+      focusedTab = match;
+    } else {
+      activateTab(match, { focus: false });
     }
   }
-  if (workspace.panes.some((pane) => pane.id === session.focusedPane)) {
-    focusPane(session.focusedPane);
+  if (focusedTab) {
+    activateTab(focusedTab);
+  } else if (focused) {
+    focusPane(focused);
   }
   return opened;
 }

package/src/workspace/tab-workspace.ts

@@ -0,0 +1,137 @@
+/**
+ * Which workspace a tab belongs to, and which of a pane's tabs its strip draws.
+ *
+ * Every tab belongs to exactly one workspace, and the answer is DERIVED from the tab rather than
+ * stored on it: what a tab is (a home, a media file, a comparison) and how it is being edited (the
+ * configuration document's stylebook editor) are already on the tab, so a stored field would be a
+ * second record of the same fact, free to disagree with it.
+ *
+ * - **Content**: the Content home and the collection and page grids; an entry's form editor; and any
+ *   file a content collection owns (collection-match.ts is the one matcher), because an entry is
+ *   written in Content even when it is opened from somewhere else.
+ * - **Media**: the media home and every media file's viewer.
+ * - **Styles**: `project.json`, in any of its three views: Elements (`stylebook`), Variables
+ *   (`tokens`) and Code (`source`). Project Settings is a dialog over every workspace (§17.1), not
+ *   a tab, so it belongs to none.
+ * - **Publish**: the publish home and every comparison (`git-diff`).
+ * - **Design**: everything else: pages, templates, components and every other file.
+ *
+ * The rules read the tab's CURRENT editor, so switching an entry from its form to the canvas keeps
+ * it in Content while a grid's kind decides between Content and Design, and
+ * `workspace/workspace-switch.ts` follows the tab wherever that puts it.
+ *
+ * @docs studio/interface
+ */
+
+import { shell } from "../shell";
+import { workspace } from "./workspace";
+import { homeWorkspaceOfTabId } from "./workspace-ids";
+import { parseGridTabId } from "../grid/grid-source";
+import { collectionForFile } from "../content/collection-match";
+import { PROJECT_CONFIG_PATH } from "../tabs/tab";
+import type { Pane } from "./workspace";
+import type { WorkspaceId } from "./workspace-ids";
+import type { Tab } from "../tabs/tab";
+
+/** The editors that are Content's whatever document they are over. */
+const CONTENT_MODES: ReadonlySet<string> = new Set(["entry"]);
+
+/** The workspace `tab` belongs to. Pure over the tab and the open project's configuration. */
+export function workspaceOfTab(tab: Tab): WorkspaceId {
+  const home = homeWorkspaceOfTabId(tab.id);
+  if (home) {
+    return home;
+  }
+  const mode = tab.session.ui.canvasMode;
+  if (mode === "git-diff") {
+    return "publish";
+  }
+  if (mode === "media") {
+    return "media";
+  }
+  if (CONTENT_MODES.has(mode)) {
+    return "content";
+  }
+  const grid = parseGridTabId(tab.id);
+  if (grid) {
+    // A data-table grid is the Data panel's, which is Design's; every other grid is content.
+    return grid.kind === "data" ? "design" : "content";
+  }
+  if (tab.documentPath === PROJECT_CONFIG_PATH) {
+    return "styles";
+  }
+  /* A file-backed collection's file too: its grid is where its records are written, and the
+     Content home opens it for any of them, so it must not carry the author off to Design. */
+  return collectionForFile(tab.documentPath) ? "content" : "design";
+}
+
+/**
+ * The editors in which a document is written on the canvas, where the Inspector applies: a page's
+ * canvas, and the Elements view (`stylebook`), whose canvas selects the element default the
+ * Inspector's Style tab edits.
+ */
+const CANVAS_WRITING_MODES: ReadonlySet<string> = new Set(["edit", "design", "stylebook"]);
+
+/**
+ * Whether a tab is a document being written on the canvas: a file-backed tab in an editing canvas
+ * mode. A grid, an entry's form, a home, the Variables view and a code view are not. Content's and
+ * Styles' presets read it to draw the Inspector while the canvas is being written (`shell.ts`'s
+ * `WORKSPACE_PRESETS`).
+ */
+export function writesOnCanvas(tab: Tab): boolean {
+  return (
+    tab.documentPath !== null &&
+    parseGridTabId(tab.id) === null &&
+    CANVAS_WRITING_MODES.has(tab.session.ui.canvasMode)
+  );
+}
+
+/** Whether a tab id names an open tab of the workspace on screen. */
+export function isTabInWorkspace(tabId: string, id: WorkspaceId = shell.workspace): boolean {
+  const tab = workspace.tabs.get(tabId);
+  return tab !== undefined && workspaceOfTab(tab) === id;
+}
+
+/**
+ * The tabs a pane's strip draws: its own, in strip order, less every tab of another workspace.
+ *
+ * The order is the pane's, so a drop index computed against {@link Pane.tabOrder} still lands
+ * between the two chips it was dropped between: the hidden tabs keep their slots, they are only not
+ * drawn.
+ */
+export function workspaceTabOrder(pane: Pane, id: WorkspaceId = shell.workspace): string[] {
+  return pane.tabOrder.filter((tabId) => isTabInWorkspace(tabId, id));
+}
+
+/**
+ * The tab a workspace was last in: the most recently used of its open tabs, in any pane, or the
+ * first of them in strip order when none has been used yet (a restored session's tabs are opened
+ * without being focused). `null` when the workspace has no tab open.
+ */
+export function lastTabOfWorkspace(id: WorkspaceId): string | null {
+  const recent = workspace.mruOrder.find((tabId) => isTabInWorkspace(tabId, id));
+  if (recent) {
+    return recent;
+  }
+  for (const pane of workspace.panes) {
+    const first = pane.tabOrder.find((tabId) => isTabInWorkspace(tabId, id));
+    if (first) {
+      return first;
+    }
+  }
+  return null;
+}
+
+/** The tab `pane` should show for a workspace: its most recent one there, or `null`. */
+export function paneTabOfWorkspace(pane: Pane, id: WorkspaceId): string | null {
+  if (pane.activeTabId && isTabInWorkspace(pane.activeTabId, id)) {
+    return pane.activeTabId;
+  }
+  return (
+    workspace.mruOrder.find(
+      (tabId) => pane.tabOrder.includes(tabId) && isTabInWorkspace(tabId, id),
+    ) ??
+    pane.tabOrder.find((tabId) => isTabInWorkspace(tabId, id)) ??
+    null
+  );
+}

package/src/workspace/workspace-back.ts

@@ -0,0 +1,189 @@
+/**
+ * Back to the workspace home — the way out of a view in a workspace that draws no tab strip.
+ *
+ * Media, Styles and Publish draw their home surface without a strip (`shell.ts`'s
+ * `WorkspacePreset.tabStrip`, `specs/studio.md` §22.3). What they open beside their home has to be
+ * leave-able anyway, and without a strip there is no chip to click and no × to press:
+ *
+ * - **Media**: a media file opened in its viewer leads back to the media library.
+ * - **Publish**: a comparison (`git-diff`) leads back to the Publish home.
+ * - **Styles**: `project.json` in its Code view leads back to the view the Styles home was left in,
+ *   Variables or Elements. Code is a view of the same tab, so going back switches the view and
+ *   closes nothing.
+ *
+ * {@link backTargetOf} is the one rule, read by the pane context bar (which draws the Back control,
+ * naming the destination) and by `pane.backToHome` (the control's command, and Escape's). A media
+ * viewer or a comparison is CLOSED on the way back, so the home is what is left: a strip-less pane
+ * holds its home and one view beside it rather than a pile of views nobody can see, and the close
+ * lands on the home (`workspace/workspace-switch.ts`'s close landing). Closing such a view any
+ * other way (⌘W) lands there too.
+ *
+ * @docs studio/interface/tabs
+ */
+
+import { shell, workspaceDrawsTabStrip } from "../shell";
+import { PROJECT_CONFIG_PATH } from "../tabs/tab";
+import { tabOfPane } from "../canvas/canvas-surface";
+import { workspace } from "./workspace";
+import { workspaceOfTab } from "./tab-workspace";
+import { homeWorkspaceOfTabId, isHomeWorkspace, workspaceInfo } from "./workspace-ids";
+import { argsSchema, optionalStringArg, stringProperty } from "../commands/command-args";
+import { EDITOR_KIND_LABELS, editorKindForMode } from "../commands/context";
+import { isPopoverOpen } from "../ui/layers";
+import type { WorkspaceId } from "./workspace-ids";
+import type { Tab } from "../tabs/tab";
+import type { AnyCommand } from "../commands/registry";
+
+/** Where the Back control leads, and how it gets there. */
+export type BackTarget =
+  | {
+      /** Close the view: the home beside it is what the pane shows next. */
+      kind: "close";
+      /** The control's text, naming the destination: "Back to Media". */
+      label: string;
+      /** Its tooltip: what happens to the view. */
+      hint: string;
+    }
+  | {
+      /** Switch the tab to another of its views (Styles' Code view back to the home view). */
+      kind: "view";
+      label: string;
+      hint: string;
+      /** The canvas mode to switch to: `tokens` or `stylebook`. */
+      mode: string;
+    };
+
+/** The Code view's mode over `project.json`. */
+const SOURCE_MODE = "source";
+
+/**
+ * Where a tab's Back control leads in workspace `id`, or `null` when there is nowhere to go back
+ * to: a workspace that draws a strip (its strip is the way between documents), a tab of another
+ * workspace, and a workspace's home itself.
+ *
+ * @param tab The tab a pane is showing
+ * @param id The workspace on screen
+ */
+export function backTargetOf(
+  tab: Tab | null,
+  id: WorkspaceId = shell.workspace,
+): BackTarget | null {
+  if (!tab || workspaceDrawsTabStrip(id) || workspaceOfTab(tab) !== id) {
+    return null;
+  }
+  if (id === "styles") {
+    if (tab.documentPath !== PROJECT_CONFIG_PATH || tab.session.ui.canvasMode !== SOURCE_MODE) {
+      return null;
+    }
+    const mode = shell.stylebook.view;
+    const name = EDITOR_KIND_LABELS[editorKindForMode(mode)];
+    return {
+      hint: `Leave the Code view for the ${name} view of your styles`,
+      kind: "view",
+      label: `Back to ${name}`,
+      mode,
+    };
+  }
+  if (!isHomeWorkspace(id) || homeWorkspaceOfTabId(tab.id) === id) {
+    return null;
+  }
+  const home = workspaceInfo(id).title;
+  return {
+    hint: `Close this view and return to ${home}`,
+    kind: "close",
+    label: `Back to ${home}`,
+  };
+}
+
+/** {@link backTargetOf} for the tab a pane is showing. */
+export function backTargetOfPane(paneId: string): BackTarget | null {
+  return backTargetOf(tabOfPane(paneId));
+}
+
+/** What going back needs that this module may not import. */
+export interface WorkspaceBackDeps {
+  /** Close a tab through the strip's guarded close (`panels/tab-strip.ts` `requestClose`). */
+  closeTab: (tabId: string) => void | Promise<void>;
+  /** Switch a tab's editor (`studio.ts` `setCanvasMode`). */
+  setCanvasMode: (tab: Tab, mode: string) => void;
+  /**
+   * Give the keyboard to the home a close landed on: the Media home's tile, the Publish change the
+   * comparison was opened from. Without it the focus falls to the page body with the view.
+   */
+  focusHome?: (paneId: string, id: WorkspaceId) => void;
+}
+
+/**
+ * Go back from what `paneId` shows to its workspace's home. `false` when there is nowhere to go.
+ *
+ * @param paneId The pane whose Back control was pressed
+ * @param deps The close and the view switch
+ */
+export async function goBack(paneId: string, deps: WorkspaceBackDeps): Promise<boolean> {
+  const tab = tabOfPane(paneId);
+  const target = backTargetOf(tab);
+  if (!tab || !target) {
+    return false;
+  }
+  if (target.kind === "view") {
+    tab.session.ui.preview = false;
+    deps.setCanvasMode(tab, target.mode);
+    return true;
+  }
+  const id = shell.workspace;
+  await deps.closeTab(tab.id);
+  // Only when the close went through: a refused close (unsaved work kept) leaves the view standing.
+  if (!workspace.tabs.has(tab.id)) {
+    deps.focusHome?.(paneId, id);
+  }
+  return true;
+}
+
+/**
+ * `pane.backToHome`: the Back control's command, and Escape's.
+ *
+ * Gated with `when`, not `enablement`, because Escape is the chord: a disabled record still claims
+ * its chord, and every other Escape in the global scope would be swallowed by a Back that is not
+ * there. Three places keep their own Escape: a text field (the caret is a field's, and Escape there
+ * is the field's own); the Code view, where Escape belongs to the code editor's widgets, so the
+ * Back control is how Code is left; and an open popover (the pane context bar's Context menu, for
+ * one), which the platform closes on Escape, and which a cancelled Escape would leave standing over
+ * a view that had gone.
+ *
+ * @param deps The close and the view switch
+ */
+export function workspaceBackCommands(deps: WorkspaceBackDeps): AnyCommand[] {
+  return [
+    {
+      args: argsSchema(
+        {
+          pane: stringProperty("Which pane to go back in. Defaults to the focused one."),
+        },
+        [],
+      ),
+      id: "pane.backToHome",
+      title: "Back to Workspace Home",
+      category: "View",
+      level: "document",
+      keybinding: "escape",
+      menus: ["palette"],
+      group: "5_pane",
+      when: (ctx) =>
+        !ctx.caret.active &&
+        ctx.editor.kind !== "code" &&
+        !isPopoverOpen() &&
+        backTargetOfPane(workspace.activePaneId) !== null,
+      requires: "a view opened beside a workspace home",
+      undo: "none",
+      run: async (_ctx, args) => {
+        const paneId = optionalStringArg("pane.backToHome", args, "pane") ?? workspace.activePaneId;
+        if (!(await goBack(paneId, deps))) {
+          throw new RangeError(
+            `command "pane.backToHome": pane "${paneId}" shows no view opened beside a ` +
+              "workspace home, so there is nothing to go back from",
+          );
+        }
+      },
+    },
+  ];
+}