@jxsuite/studio 6.1.2 → 8.0.0

package/src/surfaces/writing-banner.ts

@@ -0,0 +1,80 @@
+/// <reference lib="dom" />
+/**
+ * The writing-mode banner surface: one line over the canvas while a collection entry is written
+ * inside its template's layout (`specs/studio.md` §22.5).
+ *
+ * This is the adapter. `content/writing-banner.ts` decides what the line says and where its button
+ * goes; this module writes the projection into a scope and mounts `writing-banner.json`.
+ *
+ * @docs studio/projects/content-types
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import writingBannerDoc from "./writing-banner.json";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("writing-banner", writingBannerDoc);
+
+/** What the banner draws. */
+export interface WritingBannerView {
+  /** The region id stamped on the root: `pane.<id>/writing-banner`. */
+  region: string;
+  text: string;
+  /** "Design the post page", or "Edit the Base template in Design" when the entry has no page. */
+  actionLabel: string;
+  /** Whether there is a template to open at all. */
+  actionState: "hidden" | "shown";
+}
+
+export interface WritingBannerActions {
+  /** Open the entry's template in Design. */
+  openTemplate: () => void;
+}
+
+export interface WritingBannerHandle {
+  readonly ready: Promise<unknown>;
+  update: (view: WritingBannerView) => void;
+  dispose: () => void;
+}
+
+interface WritingBannerScope extends WritingBannerView, WritingBannerActions {}
+
+/**
+ * Mount the banner into `host`, the empty node the canvas stage drew for it.
+ *
+ * @param host The stage's `writing-banner` host.
+ * @param view What it says.
+ * @param actions What its button does.
+ */
+export function mountWritingBannerSurface(
+  host: HTMLElement,
+  view: WritingBannerView,
+  actions: WritingBannerActions,
+): WritingBannerHandle {
+  const scope: WritingBannerScope = reactive<WritingBannerScope>({ ...view, ...actions });
+  let mounted: SurfaceHandle | null = null;
+  let disposed = false;
+  const ready = mountSurface("writing-banner", scope, host).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+    } else {
+      mounted = surface;
+    }
+    return surface;
+  });
+  return {
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+    },
+    ready,
+    update(next) {
+      scope.region = next.region;
+      scope.text = next.text;
+      scope.actionLabel = next.actionLabel;
+      scope.actionState = next.actionState;
+    },
+  };
+}

package/src/tabs/bare-repeaters.ts

@@ -0,0 +1,101 @@
+/**
+ * The repeaters a file wrote as a node's whole `children`, so a save can write them back that way.
+ *
+ * A node may hold a repeater two ways: as a member of its children array (`children: [{ $prototype:
+ * "Array", … }]`) or as the whole children slot (`children: { $prototype: "Array", … }`). The two
+ * render the same, and the editor works in the first form only: `normalizeArrayChildren` rewrites
+ * every document a tab loads, because every mutation, path and history checkpoint assumes a
+ * children array. Without a record of what the file said, a save then rewrote every bare repeater
+ * in it into the member form, so one inserted paragraph produced a diff in a list nobody touched,
+ * and undoing every edit still left the file different from the one on disk.
+ *
+ * **Two keys, either of which is enough.** The pointer of the node that held the repeater survives
+ * an edit inside the repeater (a restyled template); the repeater's own JSON survives an edit that
+ * moves it (a sibling inserted above an ancestor shifts every pointer below it). A repeater both
+ * moved and changed loses both and is written in the member form, which renders the same. Only a
+ * children array whose ONLY member is a repeater is unwrapped: a node that has gained a sibling of
+ * its repeater can no longer be written the bare way at all.
+ *
+ * @docs studio/interface/tabs
+ */
+
+import { isJsonObject, isMappedArray } from "@jxsuite/schema/guards";
+import type { JsonObject, JsonValue, JxMutableNode } from "@jxsuite/schema/types";
+import { normalizeArrayChildren, pointerToken } from "../state";
+
+/** What a file said about its bare repeaters, in the normalized document's coordinates. */
+export interface BareRepeaters {
+  /** The JSON Pointer of each node whose `children` WAS the repeater. */
+  readonly pointers: ReadonlySet<string>;
+  /** `JSON.stringify` of each such repeater as it was read. */
+  readonly fingerprints: ReadonlySet<string>;
+}
+
+/**
+ * Normalize a freshly read document in place (`normalizeArrayChildren`) and return what it rewrote,
+ * or null when the file held no bare repeater — the common case, which needs no record.
+ */
+export function normalizeDocument(document: JxMutableNode): BareRepeaters | null {
+  const pointers = new Set<string>();
+  const fingerprints = new Set<string>();
+  normalizeArrayChildren(document, (pointer, repeater) => {
+    pointers.add(pointer);
+    fingerprints.add(JSON.stringify(repeater));
+  });
+  return pointers.size === 0 ? null : { fingerprints, pointers };
+}
+
+/**
+ * The document as the file should hold it: every single-member children array whose repeater the
+ * record names, written back as the node's whole `children`. Copy-on-write, so the tab's document
+ * (a reactive tree the editor owns) is never touched, and a document with nothing to restore is
+ * returned as it is.
+ */
+export function restoreBareRepeaters(
+  document: JxMutableNode,
+  record: BareRepeaters | null,
+): JxMutableNode {
+  if (!record) {
+    return document;
+  }
+  /* SAFETY: a Jx document is JSON (it is read from, and written to, a JSON file); the restored copy
+     is the same node with some `children` slots holding their sole repeater directly — the bare
+     form the node's schema allows. */
+  return restoreValue(document as JsonValue, "", record) as JxMutableNode;
+}
+
+/** Restore inside one value of the tree, returning it unchanged when nothing below it moved. */
+function restoreValue(value: JsonValue, pointer: string, record: BareRepeaters): JsonValue {
+  if (Array.isArray(value)) {
+    let copy: JsonValue[] | null = null;
+    for (const [i, item] of value.entries()) {
+      const next = restoreValue(item, `${pointer}/${i}`, record);
+      if (next !== item) {
+        copy ??= [...value];
+        copy[i] = next;
+      }
+    }
+    return copy ?? value;
+  }
+  if (!isJsonObject(value)) {
+    return value;
+  }
+  let copy: JsonObject | null = null;
+  for (const [key, child] of Object.entries(value)) {
+    let next = restoreValue(child, `${pointer}/${pointerToken(key)}`, record);
+    if (key === "children" && Array.isArray(next) && next.length === 1) {
+      const [only] = next;
+      if (
+        isMappedArray(only) &&
+        (record.pointers.has(pointer) || record.fingerprints.has(JSON.stringify(only)))
+      ) {
+        next = only;
+      }
+    }
+    if (next !== child) {
+      copy ??= { ...value };
+      copy[key] = next;
+    }
+  }
+  return copy ?? value;
+}

package/src/tabs/tab.ts

@@ -2,7 +2,8 @@
 import { effectScope, reactive } from "../reactivity";
 import { formatByName, formatForPath } from "../format/format-host";
 import type { FormatFrontmatter } from "../format/format-host";
-import { normalizeArrayChildren } from "../state";
+import { normalizeDocument } from "./bare-repeaters";
+import type { BareRepeaters } from "./bare-repeaters";
 import type { JxPath } from "../state";
 import type { FormulaEditDef, FunctionEditDef, InlineEditDef, JsonValue } from "../types";
 import { editorKindForMode } from "../commands/context";
@@ -15,13 +16,20 @@ import type { JsonLayout } from "@jxsuite/schema/json-layout";
  * The project's configuration file, project-relative.
  *
  * Named here rather than at the four places that used to spell it, because it is a DOCUMENT PATH —
- * `inferModes` answers `["stylebook", "source"]` for it (editor kind `config`), and
- * `tabs/project-config.ts` binds the tab at this path as the configuration document.
+ * `inferModes` answers `["stylebook", "tokens", "source"]` for it (the Styles workspace's Elements,
+ * Variables and Code views; editor kind `config`), and `tabs/project-config.ts` binds the tab at
+ * this path as the configuration document.
  */
 export const PROJECT_CONFIG_PATH = "project.json";
 
 export interface TabUi {
+  /** The Inspector leaf showing (`shell.ts`'s `INSPECTOR_TAB_IDS`); Page on a fresh tab (§6). */
   rightTab: string;
+  /**
+   * The Element leaf last shown — Content, Style or Logic — so the selection-driven switch from
+   * Page returns to the view the author was using rather than always to Content (§6).
+   */
+  elementTab: string;
   canvasMode: string;
   /** Preview toggle — composes with an edit/design canvasMode; the effective mode becomes "preview". */
   preview: boolean;
@@ -198,6 +206,22 @@ export interface Tab {
      * file.
      */
     layout: JsonLayout | null;
+    /**
+     * The text a format-class file (Markdown) was read as, or null for a JSON document, a new
+     * document or a stub. The format's serializer is handed it on save
+     * (`files/serialize-document.ts`) so every frontmatter key the author did not edit keeps its
+     * own spelling and the body keeps its markers (`@jxsuite/parser` `source-style.ts`). The
+     * lifetime is `layout`'s: an edit leaves it alone, and a read from disk, a source-view commit,
+     * a peer's text or a save replaces it with the text just read or written.
+     */
+    source: string | null;
+    /**
+     * The repeaters the file wrote as a node's whole `children`, which loading rewrote into the
+     * member form the editor works in (`tabs/bare-repeaters.ts`); null when it wrote none. A fact
+     * about the file with the lifetime `layout` has: a reload or a source-view commit replaces it,
+     * an edit or an undo leaves it alone, and a save writes those repeaters back as they were.
+     */
+    bareRepeaters: BareRepeaters | null;
   };
   session: {
     /**
@@ -267,7 +291,8 @@ function createDefaultUi(canvasMode: string, preview = false): TabUi {
     previewLocale: null,
     previewParams: {},
     previewProps: null,
-    rightTab: "properties",
+    rightTab: "page",
+    elementTab: "properties",
     showLayout: true,
     styleFilter: "",
     styleSections: {},
@@ -302,6 +327,7 @@ const ALL_MODES = ["edit", "design", "preview", "source", "stylebook", "git-diff
  *   openedFrom?: TabOrigin | null;
  *   preview?: boolean;
  *   layout?: JsonLayout | null;
+ *   source?: string | null;
  * }} opts
  * @returns {Tab}
  */
@@ -316,6 +342,8 @@ export function createTab({
   openedFrom = null,
   preview: previewTab = false,
   layout = null,
+  source = null,
+  canvasMode,
 }: {
   id: string;
   documentPath?: string | null;
@@ -327,28 +355,37 @@ export function createTab({
   openedFrom?: TabOrigin | null;
   preview?: boolean;
   layout?: JsonLayout | null;
+  /** The text a format-class file was read as (`doc.source`). */
+  source?: string | null;
+  /**
+   * The mode to open in instead of the first declared one: a comparison opens straight into
+   * `git-diff`, so the tab is never active in an edit mode that belongs to another workspace.
+   */
+  canvasMode?: string | undefined;
 }) {
   const scope = effectScope();
 
   // Normalize legacy whole-children repeaters to the canonical array-member form before the doc
   // (and its first history checkpoint) are stored.
-  normalizeArrayChildren(document);
+  const bareRepeaters = normalizeDocument(document);
 
   const resolvedModes = capabilities?.modes ?? inferModes(documentPath, sourceFormat);
   // A tab opens in its first allowed mode — never one the toolbar would disable.
   // Formats author mode order so the default comes first (edit, stylebook, etc.).
   // "preview" is a per-tab toggle rather than a base mode: a preview-first format opens
   // In its first non-preview mode with the toggle already on.
-  const initialCanvasMode = resolvedModes.find((m) => m !== "preview") ?? "edit";
+  const initialCanvasMode = canvasMode ?? resolvedModes.find((m) => m !== "preview") ?? "edit";
   const initialPreview = resolvedModes[0] === "preview";
 
   const doc: Tab["doc"] = {
+    bareRepeaters,
     content: { frontmatter: frontmatter || {} },
     dirty: false,
     document,
     handlersSource: null,
     layout,
     mode: inferDocumentMode(documentPath, sourceFormat),
+    source,
     sourceFormat,
   };
   const history: Tab["history"] = {
@@ -404,7 +441,10 @@ export function createTab({
  */
 function inferModes(documentPath: string | null | undefined, sourceFormat: string | null) {
   if (documentPath === PROJECT_CONFIG_PATH) {
-    return ["stylebook", "source"];
+    /* Elements, Variables and Code: the Styles workspace's three views. Spelled here rather than
+       imported from `style/project-styles` (`STYLES_TAB_MODES`), whose imports reach `store`,
+       which imports this module; `tests/project-config.test.ts` holds the two lists equal. */
+    return ["stylebook", "tokens", "source"];
   }
   const format = formatByName(sourceFormat) ?? formatForPath(documentPath);
   if (format) {

package/src/types.ts

@@ -311,25 +311,9 @@ export interface StudioPlatform {
   /**
    * URL of the canvas iframe document. Optional: when set (chromium serves it from the project
    * server under the studio namespace), the iframe host uses it; otherwise the host falls back to
-   * the default dev-server path. Not keyed on `id` — chromium and electrobun both report `id:
-   * "desktop"`, but only chromium sets this.
+   * the default dev-server path. Not keyed on `id`.
    */
   canvasUrl?: string;
-  /**
-   * True when this platform resolves {@link canvasUrl} ASYNCHRONOUSLY.
-   *
-   * Electrobun does: the url is this window's loopback port, fetched over RPC inside `activate()`.
-   * Until the canvas fallback was anchored to the bundle it did not matter — the old literal
-   * `/packages/studio/canvas.html` resolved to nothing servable under `views://`, so an early frame
-   * simply failed and the host rebuilt when the real url landed. Now the fallback RESOLVES:
-   * `views://studio/canvas.html` is a document electrobun really stages. An early frame would boot
-   * the whole canvas bundle inside the SHELL's app-privileged origin, in a CEF instance running
-   * `disable-site-isolation-trials` — and the cross-origin loopback canvas exists precisely so that
-   * cannot happen. Declaring it makes the host wait instead.
-   *
-   * Not keyed on `id`: chromium and electrobun both report `"desktop"`, and only electrobun defers.
-   */
-  canvasUrlDeferred?: boolean;
   /**
    * Base URL the canvas fetches PROJECT FILES from — component `$ref`s, `$src` modules, images.
    *
@@ -408,12 +392,11 @@ export interface StudioPlatform {
    * image. So a caller that must DECODE a project file — the image editor — needs this instead.
    *
    * **The `<img>` route is not an alternative, on the one platform that matters most.** A preview
-   * `src` from `files/media-paths.ts` is a cross-origin loopback URL on the electrobun desktop
-   * while the shell sits on `views://`, so drawing it into a canvas taints the canvas and
-   * `toBlob()` throws; and `server.md` §4.2 bans CORS outright, because the whole loopback security
-   * model rests on the browser refusing cross-origin reads. Bytes through the PAL become a
-   * same-origin `Blob`, so tainting stops being a thing that can happen rather than a thing that is
-   * worked around.
+   * `src` from `files/media-paths.ts` can be a cross-origin loopback URL while the shell sits on
+   * another origin, so drawing it into a canvas taints the canvas and `toBlob()` throws; and
+   * `server.md` §4.2 bans CORS outright, because the whole loopback security model rests on the
+   * browser refusing cross-origin reads. Bytes through the PAL become a same-origin `Blob`, so
+   * tainting stops being a thing that can happen rather than a thing that is worked around.
    *
    * Optional, and feature-detected like every optional member: a backend without it simply does not
    * offer the image editor, which is the honest degradation `specs/desktop.md` §3.1 asks for.
@@ -595,6 +578,16 @@ export interface StudioPlatform {
   gitDiscard: (files: string[]) => Promise<void>;
   gitClone?: (url: string) => Promise<{ ok: boolean; root: string }>;
   gitInit: () => Promise<void>;
+  /**
+   * True on a host whose git is the remote's: a commit lands on GitHub as it is made, a push is
+   * only a check that it did, and each branch is a session of its own, so a checkout reloads the
+   * window into that branch's session (the cloud). Absent means an ordinary working tree, where a
+   * commit is local until it is pushed and a checkout swaps files in place.
+   *
+   * A declaration rather than a method, because what differs is the meaning of the verbs every host
+   * has: the Publish workspace reads it to say what a verb will do (studio.md §22.8).
+   */
+  gitHosted?: boolean;
   /**
    * Build the site to its output directory, so a reader opens what the author is looking at.
    *
@@ -864,9 +857,9 @@ export interface StudioPlatform {
    * Watch the backend connection, on platforms whose transport can lose one.
    *
    * Only a socket-based launcher implements this: the dev server talks over `fetch` and has nothing
-   * to lose, and the electrobun launcher's RPC times a request out rather than dropping it. The
-   * chromium launcher holds one long-lived WebSocket, and when it died every call after it hung
-   * with no error anywhere — so the transport reports the state, and the studio says it out loud.
+   * to lose, The chromium launcher holds one long-lived WebSocket, and when it died every call
+   * after it hung with no error anywhere — so the transport reports the state, and the studio says
+   * it out loud.
    *
    * The handler is called on each transition, never repeatedly for one state.
    */
@@ -886,6 +879,8 @@ export interface ContentSectionEntry {
   source?: string;
   format?: string;
   schema?: ContentTypeSchema;
+  /** The field a file-backed collection's records are identified by (the loader's `idField`). */
+  idField?: string;
   $elements?: unknown[];
 }
 

package/src/ui/form-controls.ts

@@ -34,6 +34,7 @@ import {
 import { mountSchemaBuilderSurface } from "../surfaces/schema-builder";
 import { mountReferenceFieldSurface } from "../surfaces/reference-field";
 import { mountSecretFieldSurface } from "../surfaces/secret-field";
+import { mountMediaPicker, unmountMediaPicker } from "./media-picker";
 import { camelToLabel, toCamelCase } from "../utils/studio-utils";
 
 import type { JsonObject, JsonValue } from "@jxsuite/schema/types";
@@ -710,6 +711,44 @@ export const secretControl: SchemaFormMountedControl = { mount: mountSecret };
 
 registerFormControl("secret", secretControl);
 
+// ─── Media control ───────────────────────────────────────────────────────────
+
+/**
+ * An image field as the media field: the path, its thumbnail, **Upload media** and **Browse
+ * media**, exactly as the page's Icon and OG Image rows draw them. The flow is
+ * `ui/media-picker.ts`'s, which already makes a repeat mount into the same host an update, so this
+ * control only keeps the latest commit hook and clears the field to absent rather than to "".
+ *
+ * @param {HTMLElement} host - The field's `[part="control-host"]`
+ * @param {SchemaFormControlArgs} args - The value and the commit hook
+ * @returns {SchemaFormControlHandle}
+ */
+function mountMedia(host: HTMLElement, args: SchemaFormControlArgs): SchemaFormControlHandle {
+  let latest = args;
+  const draw = (): void => {
+    mountMediaPicker(
+      host,
+      latest.key,
+      isString(latest.value) ? latest.value : "",
+      (value: string) => latest.onChange(value === "" ? undefined : value),
+      { images: true },
+    );
+  };
+  draw();
+  return {
+    dispose: () => unmountMediaPicker(host),
+    update(next) {
+      latest = next;
+      draw();
+    },
+  };
+}
+
+/** The media control as the registry holds it, named so a test can drive it as the engine does. */
+export const mediaControl: SchemaFormMountedControl = { mount: mountMedia };
+
+registerFormControl("media", mediaControl);
+
 // ─── Reference control ───────────────────────────────────────────────────────
 
 /**
@@ -804,13 +843,13 @@ function entryIdsFor(collection: string): Promise<string[]> {
  * `null` means the read is still in flight, and `onSettled` is called when it lands — which is the
  * second frame a document has to be GIVEN, since nothing repaints it on the read's behalf.
  *
- * Exported because two surfaces draw the choices and neither is this control: the Document Header
- * card and the Navigator's Page panel project a `$ref` field as a picker row of their own
- * (`panels/frontmatter-fields.ts`), and what they need is not the widget but the answer behind it.
- * Taking it from here rather than calling `listCollectionEntryIds` directly is what keeps ONE cache
- * and ONE invalidation: a collection listed for the Document Header card is not listed again for
- * the entry editor, and {@link invalidateReferenceEntries} after an entry is created is still the
- * single event that forgets it.
+ * Exported because a surface draws the choices and is not this control: the Inspector's Page tab
+ * projects a `$ref` field as a picker row of its own (`panels/frontmatter-fields.ts`), and what it
+ * needs is not the widget but the answer behind it. Taking it from here rather than calling
+ * `listCollectionEntryIds` directly is what keeps ONE cache and ONE invalidation: a collection
+ * listed for the Page tab is not listed again for the entry editor, and
+ * {@link invalidateReferenceEntries} after an entry is created is still the single event that
+ * forgets it.
  *
  * @param {string} collection
  * @param {() => void} [onSettled]
@@ -990,4 +1029,4 @@ export const referenceControl: SchemaFormMountedControl = { mount: mountReferenc
 registerFormControl("reference", referenceControl);
 
 // Keep an explicit export so hosts can assert the built-ins module loaded
-export const builtinFormControls = ["schema-builder", "secret", "reference"] as const;
+export const builtinFormControls = ["schema-builder", "secret", "reference", "media"] as const;

package/src/ui/layers.ts

@@ -99,6 +99,19 @@ export function isModalOpen(): boolean {
   return Boolean(_dialogLayer?.querySelector(UNDERLAID) || _modalLayer?.querySelector(UNDERLAID));
 }
 
+/**
+ * Whether a popover is showing anywhere in the chrome: a kit `jx-popover`, a menu, any element in
+ * the platform's popover top layer.
+ *
+ * A popover leaves Escape to the platform, which closes it as the keystroke's default action, so an
+ * app chord on bare Escape has to stand down while one is up: cancelling the keystroke would cancel
+ * the close as well, and whatever the chord did would happen under a popover that stays open. Asked
+ * of the live DOM for the reason {@link isModalOpen} is.
+ */
+export function isPopoverOpen(): boolean {
+  return document.querySelector(":popover-open") !== null;
+}
+
 /*
  * `showDialog` was here, with `openOverlaySlot`, `focusOverlay`, `focusablesIn` and
  * `BODY_FOCUSABLE` under it — and all five are GONE together.