@jxsuite/studio 6.1.2 → 8.0.1

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",
+          );
+        }
+      },
+    },
+  ];
+}

package/src/workspace/workspace-home.ts

@@ -0,0 +1,133 @@
+/// <reference lib="dom" />
+/**
+ * Workspace homes — the virtual tab a workspace opens on when none of its own tabs is open.
+ *
+ * A home is a tab like a grid is a tab: it sits in a pane's strip, it can be closed, and it has a
+ * canvas mode of its own (`content-home`, `media-home`, `publish-home`) that
+ * `canvas/canvas-render.ts` routes here. It has no document — the tab carries a stub, exactly as
+ * the grid tabs do — and its id is in the `workspace://` space `workspace/workspace-ids.ts`
+ * declares, so it can never collide with a file.
+ *
+ * What a home DRAWS is its workspace's own surface: the Content home is the collection it shows
+ * (`browse/library-pane.ts`, studio.md §22.5), the Media home is the media library
+ * (`media/media-library.ts`, §22.6) and the Publish home is the Publish workspace
+ * (`publish/publish-workspace.ts`, §22.8). The mechanism (the tab, the mode, the routing and the
+ * per-pane mount) is the same for all three, and this module only routes.
+ *
+ * @docs studio/interface
+ */
+
+import { activateTab, openTab, workspace } from "./workspace";
+import { WORKSPACE_HOME_MODES, homeWorkspaceOfTabId, workspaceHomeTabId } from "./workspace-ids";
+import {
+  detachMediaLibrary,
+  mediaLibraryMounted,
+  renderMediaLibrary,
+} from "../media/media-library";
+import { detachLibraryPane, libraryPaneMounted, renderLibraryMode } from "../browse/library-pane";
+import {
+  detachPublishWorkspace,
+  publishWorkspaceMounted,
+  renderPublishWorkspace,
+} from "../publish/publish-workspace";
+import type { HomeWorkspaceId } from "./workspace-ids";
+import type { Tab } from "../tabs/tab";
+import type { CanvasSurface } from "../canvas/canvas-surface";
+
+/** The stub a home tab carries: it is never read, and nothing is ever saved from it. */
+const HOME_STUB_DOCUMENT = { children: [], tagName: "div" };
+
+/** The canvas modes a home draws under. */
+export const WORKSPACE_HOME_MODE_SET: ReadonlySet<string> = new Set(
+  Object.values(WORKSPACE_HOME_MODES),
+);
+
+/** Whether a canvas mode is a workspace home's. */
+export function isWorkspaceHomeMode(mode: string): boolean {
+  return WORKSPACE_HOME_MODE_SET.has(mode);
+}
+
+/**
+ * Open (or activate) a workspace's home.
+ *
+ * Idempotent by construction, which is what lets `view.setWorkspace` say "show me Media" without
+ * caring whether an earlier switch opened its home already.
+ */
+export function openWorkspaceHome(id: HomeWorkspaceId): Tab {
+  const tabId = workspaceHomeTabId(id);
+  const existing = workspace.tabs.get(tabId);
+  if (existing) {
+    activateTab(tabId);
+    return existing;
+  }
+  return openTab({
+    capabilities: { modes: [WORKSPACE_HOME_MODES[id]] },
+    document: structuredClone(HOME_STUB_DOCUMENT),
+    documentPath: null,
+    id: tabId,
+  });
+}
+
+/**
+ * Put a workspace's home in `paneId`'s strip without showing it, unless it is open already.
+ *
+ * A workspace with no Navigator (Media, Publish) has no other way back to its home than its tab: a
+ * media file opened from the Site panel lands in Media on its viewer, and with the home absent the
+ * strip offered that viewer alone and closing it left an empty stage. Keeping the home beside it is
+ * what makes the grid one click away, and what closing the viewer falls back to.
+ */
+export function placeWorkspaceHome(id: HomeWorkspaceId, paneId: string): void {
+  openTab({
+    background: true,
+    capabilities: { modes: [WORKSPACE_HOME_MODES[id]] },
+    document: structuredClone(HOME_STUB_DOCUMENT),
+    documentPath: null,
+    id: workspaceHomeTabId(id),
+    paneId,
+  });
+}
+
+// ─── Mounting ────────────────────────────────────────────────────────────────
+
+/** Whether this tab's home is already mounted in this pane and still in the document. */
+export function workspaceHomeMounted(paneId: string, tab: Tab): boolean {
+  const id = homeWorkspaceOfTabId(tab.id);
+  if (id === "media") {
+    return mediaLibraryMounted(paneId, tab);
+  }
+  if (id === "content") {
+    return libraryPaneMounted(paneId, tab);
+  }
+  return publishWorkspaceMounted(paneId, tab);
+}
+
+/** Tear one pane's home down (mode change, tab switch, project close). Idempotent. */
+export function detachWorkspaceHome(paneId: string): void {
+  detachMediaLibrary(paneId);
+  detachLibraryPane(paneId);
+  detachPublishWorkspace(paneId);
+}
+
+/**
+ * Draw a home tab into its pane's stage.
+ *
+ * @param {CanvasSurface} surface
+ * @param {Tab} tab
+ */
+export function renderWorkspaceHome(surface: CanvasSurface, tab: Tab): void {
+  const { paneId } = surface;
+  if (workspaceHomeMounted(paneId, tab)) {
+    return;
+  }
+  detachWorkspaceHome(paneId);
+  const id = homeWorkspaceOfTabId(tab.id);
+  if (id === "media") {
+    renderMediaLibrary(surface, tab);
+    return;
+  }
+  if (id === "content") {
+    renderLibraryMode(surface, tab);
+    return;
+  }
+  renderPublishWorkspace(surface, tab);
+}

package/src/workspace/workspace-ids.ts

@@ -0,0 +1,129 @@
+/**
+ * The five workspaces, declared where a bare Bun process can read them.
+ *
+ * A workspace is the answer to "what am I doing right now": designing pages, writing content,
+ * managing media, editing the project's styles, or publishing. Studio's top bar switches between
+ * them, and every open tab belongs to exactly one (`workspace/tab-workspace.ts` derives which).
+ *
+ * The ids live in a module with no DOM and no state for the reason `NAVIGATOR_PANEL_IDS` does:
+ * `view.setWorkspace`'s `args` enum is built from {@link WORKSPACE_IDS}, and
+ * `commands/app-commands.ts` must load that enum in the bare Bun process the CI checks run in. A
+ * manifest step naming a workspace this list does not declare is then a red check in the PR that
+ * renamed it, rather than a screenshot of the wrong screen.
+ *
+ * The workspace HOME tab ids are declared here too. A home is a virtual tab (a document the pane
+ * draws that no file backs), and both the derivation that says which workspace a tab belongs to and
+ * the module that opens one must agree on its id, so the id has one definition site that imports
+ * nothing.
+ *
+ * @docs studio/interface
+ */
+
+/** The workspaces, in top-bar order. ⌘1 to ⌘5 follow this order. */
+export const WORKSPACE_IDS = ["design", "content", "media", "styles", "publish"] as const;
+
+export type WorkspaceId = (typeof WORKSPACE_IDS)[number];
+
+/** The workspace a project wakes up in when nothing usable is stored. */
+export const DEFAULT_WORKSPACE: WorkspaceId = "design";
+
+/** One workspace, as the top bar and the palette name it. */
+export interface WorkspaceInfo {
+  id: WorkspaceId;
+  /** What the top-bar tab reads, and what the palette row says after "Show". */
+  title: string;
+  /** A key into the kit's glyph manifest (`@jxsuite/ui/icons`), checked by this module's test. */
+  icon: string;
+}
+
+/** Every workspace, in {@link WORKSPACE_IDS} order. */
+export const WORKSPACES: readonly WorkspaceInfo[] = [
+  {
+    icon: "frame-corners",
+    id: "design",
+    title: "Design",
+  },
+  {
+    icon: "file-text",
+    id: "content",
+    title: "Content",
+  },
+  {
+    icon: "image",
+    id: "media",
+    title: "Media",
+  },
+  {
+    icon: "paint-brush",
+    id: "styles",
+    title: "Styles",
+  },
+  {
+    icon: "paper-plane-tilt",
+    id: "publish",
+    title: "Publish",
+  },
+];
+
+/** Whether a value is a declared workspace id. A stored value is untrusted input. */
+export function isWorkspaceId(value: unknown): value is WorkspaceId {
+  return typeof value === "string" && WORKSPACE_IDS.some((id) => id === value);
+}
+
+/** The record for a workspace id. Total over {@link WorkspaceId}. */
+export function workspaceInfo(id: WorkspaceId): WorkspaceInfo {
+  /* SAFETY of the `!`: WORKSPACES holds one entry per WORKSPACE_IDS member, which this module's
+     test asserts in both directions. */
+  return WORKSPACES.find((entry) => entry.id === id)!;
+}
+
+// ─── Workspace homes ─────────────────────────────────────────────────────────
+
+/**
+ * The scheme a workspace home's tab id carries. Not a path, so it can never collide with a file,
+ * and not `grid://`, which is the grid's id space.
+ */
+const HOME_SCHEME = "workspace://";
+
+/**
+ * The workspaces whose home is a virtual tab of the generic home mechanism, and the canvas mode
+ * that tab draws under.
+ *
+ * Design has no home (an empty stage is its home), and Styles' is `project.json` in its stylebook
+ * editor, opened by the module that owns that document. These three are the generic mechanism's:
+ * Content's home is the collection it shows (`browse/library-pane.ts`), Media's the media library,
+ * and Publish's its own surface.
+ */
+export const WORKSPACE_HOME_MODES = {
+  content: "content-home",
+  media: "media-home",
+  publish: "publish-home",
+} as const satisfies Partial<Record<WorkspaceId, string>>;
+
+/** A workspace whose home is a generic home tab. */
+export type HomeWorkspaceId = keyof typeof WORKSPACE_HOME_MODES;
+
+/** Whether a workspace's home is a generic home tab. */
+export function isHomeWorkspace(id: WorkspaceId): id is HomeWorkspaceId {
+  return Object.hasOwn(WORKSPACE_HOME_MODES, id);
+}
+
+/** The tab id of a workspace's home. */
+export function workspaceHomeTabId(id: HomeWorkspaceId): string {
+  return `${HOME_SCHEME}${id}`;
+}
+
+/** The workspace a home tab id names, or `null` for any other id. */
+export function homeWorkspaceOfTabId(tabId: string): HomeWorkspaceId | null {
+  if (!tabId.startsWith(HOME_SCHEME)) {
+    return null;
+  }
+  const rest = tabId.slice(HOME_SCHEME.length);
+  return isWorkspaceId(rest) && isHomeWorkspace(rest) ? rest : null;
+}
+
+/** The label a home tab's chip reads: the workspace's own title. `null` for any other id. */
+export function workspaceHomeLabel(tabId: string): string | null {
+  const id = homeWorkspaceOfTabId(tabId);
+  return id ? workspaceInfo(id).title : null;
+}