@jxsuite/studio 6.1.1 → 8.0.0

package/src/surfaces/welcome.ts

@@ -24,16 +24,15 @@ import { runOfferedAction } from "../account/action-flow";
 import { platformSupportsAddRepo } from "../new-project/add-repo-modal";
 import { getProjectList } from "../project-list";
 import { reactive } from "../reactivity";
-import { now } from "../services/clock";
+import { MINUTE, now } from "../services/clock";
 import { clearRecentProjects, getRecentProjects, removeRecentProject } from "../recent-projects";
-import { platformSupportsClone } from "../panels/git-panel";
+import { platformSupportsClone } from "../publish/source-control";
 import { mountSurface, registerSurface } from "../ui/surface";
 import welcomeDoc from "./welcome.json";
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { SurfaceHandle } from "../ui/surface";
 import type { AccountNotice, OfferedAction } from "../types";
 
-registerSurface("welcome", welcomeDoc as unknown as JxDocument);
+registerSurface("welcome", welcomeDoc);
 
 interface WelcomeCtx {
   openProject: () => void;
@@ -122,7 +121,6 @@ export function recentLocations(
   return labels;
 }
 
-const MINUTE = 60_000;
 const HOUR = 60 * MINUTE;
 const DAY = 24 * HOUR;
 
@@ -195,7 +193,7 @@ interface CatalogueRow {
   detail: string;
 }
 
-interface WelcomeScope extends Record<string, unknown> {
+interface WelcomeScope {
   actions: StartAction[];
   installNeeded: boolean;
   installUrl: string;
@@ -292,7 +290,7 @@ function noticeAction(key: string): OfferedAction | null {
 
 /** The reactive scope the surface reads, made once. */
 function state(): WelcomeScope {
-  _state ??= reactive({
+  _state ??= reactive<WelcomeScope>({
     actions: [],
     catalogue: [],
     clear: () => {
@@ -342,7 +340,7 @@ function state(): WelcomeScope {
         }
       }
     },
-  }) as WelcomeScope;
+  });
   return _state;
 }
 

package/src/surfaces/writing-banner.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioWritingBanner",
+  "$description": "The writing-mode banner (specs/studio.md §22.5): one slim line above the canvas while a collection entry is written inside its template's layout, saying what the arrangement is (the text and media are editable, the layout is locked) with the door to the template, which opens it in Design. `content/writing-banner.ts` decides whether there is a template to open and what it is called; this document draws a sentence and, when there is one, the button.",
+  "tagName": "div",
+  "attributes": {
+    "part": "banner",
+    "role": "note",
+    "data-jx-region": "${state.region}"
+  },
+  "style": {
+    "$description": "A quiet band, the Content-Entry board's: the canvas is the subject, so the banner is a tinted line rather than a panel, and its action is a quiet button.",
+    "display": "flex",
+    "alignItems": "center",
+    "flexWrap": "wrap",
+    "gap": "var(--jx-space-2)",
+    "padding": "var(--jx-space-1) var(--jx-space-4)",
+    "background": "color-mix(in srgb, var(--accent) 10%, var(--bg-panel))",
+    "borderBottom": "1px solid var(--border)",
+    "fontFamily": "var(--jx-font-sans)",
+    "fontSize": "var(--jx-text-sm)",
+    "color": "var(--fg-dim)",
+    "& [part=\"glyph\"]": {
+      "flexShrink": "0",
+      "color": "var(--accent)"
+    },
+    "& [part=\"text\"]": {
+      "flex": "1",
+      "minWidth": "0"
+    },
+    "& [part=\"action-slot\"]": {
+      "display": "contents"
+    }
+  },
+  "children": [
+    {
+      "tagName": "jx-icon",
+      "attributes": {
+        "part": "glyph"
+      },
+      "$props": {
+        "name": "lock-simple"
+      }
+    },
+    {
+      "tagName": "span",
+      "attributes": {
+        "part": "text"
+      },
+      "textContent": "${state.text}"
+    },
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "action-slot",
+        "role": "none"
+      },
+      "$switch": {
+        "$ref": "#/state/actionState"
+      },
+      "cases": {
+        "shown": {
+          "tagName": "jx-action-button",
+          "attributes": {
+            "part": "edit-template"
+          },
+          "$props": {
+            "size": "sm",
+            "quiet": true
+          },
+          "onclick": {
+            "$prototype": "Function",
+            "body": [
+              {
+                "operator": "call",
+                "target": {
+                  "$ref": "#/state/openTemplate"
+                },
+                "value": []
+              }
+            ],
+            "description": "Opening the template is activating it, which enters Design (studio.md §22.1)."
+          },
+          "children": [
+            {
+              "tagName": "span",
+              "textContent": "${state.actionLabel}"
+            }
+          ]
+        }
+      }
+    }
+  ]
+}

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/patch-ops.ts

@@ -7,6 +7,7 @@
 
 // oxlint-disable-next-line unicorn/prefer-export-from -- JxDocOpPair is also used locally (TransactionRecord)
 import type { JxDocOpPair } from "@jxsuite/schema/doc-ops";
+import type { JxDocumentValue, JxMutableNode } from "@jxsuite/schema/types";
 import type { JxPath } from "../state";
 import type { Tab } from "./tab.js";
 
@@ -48,8 +49,8 @@ export type { JxDocOpPair };
  */
 export interface JxFmOp {
   field: string;
-  before?: unknown;
-  after?: unknown;
+  before?: JxDocumentValue | undefined;
+  after?: JxDocumentValue | undefined;
 }
 
 /** Everything recorded during one transaction. */
@@ -82,7 +83,7 @@ export interface PatchConsumer {
    * was consumed by whichever pane's effect ran first, so the second full-rendered every patched
    * edit while the skip counter reported one skip.
    */
-  markConsumed: (docRef: object, tab: Tab) => void;
+  markConsumed: (docRef: JxMutableNode, tab: Tab) => void;
   /**
    * Apply the batch to all ready canvas panels. Throws on any failure (caller escalates). `record`
    * carries the value-carrying `docOps` the iframe consumer posts across the frame boundary; the

package/src/tabs/project-config.ts

@@ -63,7 +63,7 @@ import { errorMessage } from "@jxsuite/schema/parse";
 import { effect, toRaw } from "../reactivity";
 import { getPlatform } from "../platform";
 import { notify } from "../services/notify";
-import { requireProjectState, setProjectState } from "../state";
+import { projectState, requireProjectState, setProjectState } from "../state";
 import { setWorkspaceProject, workspace } from "../workspace/workspace";
 import { PROJECT_CONFIG_PATH, createTab, disposeTab } from "./tab";
 import { transactDoc } from "./transact";
@@ -71,7 +71,7 @@ import { deriveJsonLayout, parseJsonDocument, serializeJson } from "@jxsuite/sch
 import type { JsonLayout } from "@jxsuite/schema/json-layout";
 
 import type { Tab } from "./tab";
-import type { ProjectConfig } from "@jxsuite/schema/types";
+import type { JxMutableNode, ProjectConfig } from "@jxsuite/schema/types";
 
 export { PROJECT_CONFIG_PATH } from "./tab";
 
@@ -147,7 +147,7 @@ let _seeding: Promise<void> | null = null;
  */
 function openConfigTab(): Tab | null {
   const tab = workspace.tabs.get(PROJECT_CONFIG_PATH);
-  return tab ? (toRaw(tab as unknown as object) as Tab) : null;
+  return tab ? toRaw(tab) : null;
 }
 
 /** Drop the current binding, disposing the detached document if that is what it was. */
@@ -169,7 +169,8 @@ function seedCommitted(): Promise<void> {
       const text = await getPlatform().readFile(PROJECT_CONFIG_PATH);
       const { document, layout } = parseJsonDocument(text);
       _layout = layout;
-      _committed = serializeProjectConfig(document as unknown as ProjectConfig);
+      // {@link serializeProjectConfig}'s serialisation, over the file's parse rather than a config.
+      _committed = serializeJson(document, configLayout());
     } catch {
       // No file, an unreadable one, or one that does not parse. "Unknown" is the honest answer,
       // And an unknown file is one every commit must write.
@@ -240,8 +241,22 @@ function syncProjectState(config: ProjectConfig): void {
  * @returns {ProjectConfig | null}
  */
 function liveConfig(): ProjectConfig | null {
-  const config = requireProjectState()?.projectConfig;
-  return config ? (toRaw(config as unknown as object) as ProjectConfig) : null;
+  const config = projectState?.projectConfig;
+  return config ? toRaw(config) : null;
+}
+
+/**
+ * The configuration a configuration document holds, unwrapped.
+ *
+ * @param {JxMutableNode} document The bound tab's `doc.document`.
+ * @returns {ProjectConfig}
+ */
+function configOf(document: JxMutableNode): ProjectConfig {
+  /* SAFETY: every document this module reads is the `project.json` tab's root, and that root is
+     only ever installed as a ProjectConfig: `createTab` below seeds it from `projectConfig`, an open
+     tab parsed the file the schema gate wrote, and every transaction here assigns configuration
+     keys. The Tab type calls every root a JxMutableNode; this is the one place that says which. */
+  return toRaw(document) as ProjectConfig;
 }
 
 /**
@@ -261,10 +276,10 @@ function liveConfig(): ProjectConfig | null {
  * settings surfaces render from `projectState` and mutate it in place, and every reader of the
  * document follows the root reference {@link transactDoc} replaces when the transaction ends.
  *
- * @param {Record<string, unknown>} target
+ * @param {JxMutableNode} target
  * @param {ProjectConfig} source
  */
-function replaceContents(target: Record<string, unknown>, source: ProjectConfig): void {
+function replaceContents(target: JxMutableNode, source: ProjectConfig): void {
   for (const key of Object.keys(target)) {
     delete target[key];
   }
@@ -282,10 +297,10 @@ function bind(tab: Tab): Tab {
   tab.scope.run(() => {
     effect(() => {
       const doc = tab.doc.document;
-      if (_bound !== tab || !requireProjectState()) {
+      if (_bound !== tab || !projectState) {
         return;
       }
-      syncProjectState(toRaw(doc) as unknown as ProjectConfig);
+      syncProjectState(configOf(doc));
     });
   });
   return tab;
@@ -316,7 +331,7 @@ export function projectConfigDocument(): Tab {
     return bind(open);
   }
   _detached = createTab({
-    document: (state.projectConfig ?? {}) as unknown as Record<string, unknown>,
+    document: state.projectConfig ?? {},
     documentPath: PROJECT_CONFIG_PATH,
     id: PROJECT_CONFIG_PATH,
   });
@@ -380,7 +395,7 @@ export async function commitProjectConfig(
   // The seed, and the record it read handed to the document — so the tab the Settings door opened
   // Writes the same bytes from ⌘S that this commit is about to.
   await lendProjectConfigLayout(tab);
-  const current = toRaw(tab.doc.document) as unknown as ProjectConfig;
+  const current = configOf(tab.doc.document);
   const currentText = serializeProjectConfig(current);
 
   // Two objects that disagree — whichever one loses, an edit written into it is lost. Null when
@@ -404,7 +419,7 @@ export async function commitProjectConfig(
   }
 
   const base = rival ?? current;
-  const next = patch ? ({ ...base, ...patch } as ProjectConfig) : base;
+  const next: ProjectConfig = patch ? { ...base, ...patch } : base;
   const text = serializeProjectConfig(next);
 
   // Nothing the file does not already say: no transaction, no write, and therefore no diff. The
@@ -417,7 +432,7 @@ export async function commitProjectConfig(
 
   const before = extensionsKey(current);
   transactDoc(tab, (t) => {
-    const doc = t.doc.document as unknown as Record<string, unknown>;
+    const doc = t.doc.document;
     if (rival) {
       replaceContents(doc, rival);
     }
@@ -429,7 +444,7 @@ export async function commitProjectConfig(
   // Serialised from what the transaction actually LANDED, not from the `next` computed above: a
   // Gate on `transactDoc` can refuse a mutation, and writing the value it refused would put the
   // File and the document into the one disagreement this module exists to make impossible.
-  const config = toRaw(tab.doc.document) as unknown as ProjectConfig;
+  const config = configOf(tab.doc.document);
   const output = serializeProjectConfig(config);
   try {
     await getPlatform().writeFile(PROJECT_CONFIG_PATH, output);
@@ -480,18 +495,14 @@ export async function commitProjectConfig(
  * @returns {Promise<void>}
  */
 export async function adoptProjectConfig(config: ProjectConfig, text: string): Promise<void> {
-  if (!requireProjectState()) {
+  if (!projectState) {
     // No project state is no configuration document either ({@link projectConfigDocument} reads
     // One). The workspace copy is then the only thing there is to keep true.
     setWorkspaceProject(workspace.projectRoot, config);
     return;
   }
   const tab = projectConfigDocument();
-  transactDoc(
-    tab,
-    (t) => replaceContents(t.doc.document as unknown as Record<string, unknown>, config),
-    { skipHistory: true },
-  );
+  transactDoc(tab, (t) => replaceContents(t.doc.document, config), { skipHistory: true });
   tab.doc.dirty = false;
   // Settle a read already in flight before saying what the file holds, or it would resolve after
   // These lines with the PREVIOUS bytes and record, and make the next real commit look like a

package/src/tabs/selection.ts

@@ -42,6 +42,8 @@
  * standing between a mixed selection and a half-applied, unrecorded delete.
  */
 
+import { isNumber } from "@jxsuite/schema/guards";
+
 import type { JxPath } from "../state";
 import { isAncestor, pathsEqual } from "../state";
 
@@ -52,7 +54,7 @@ import { isAncestor, pathsEqual } from "../state";
  * @returns {JxPath | null}
  */
 export function primarySelection(selection: readonly JxPath[] | null | undefined): JxPath | null {
-  return selection && selection.length > 0 ? (selection.at(-1) as JxPath) : null;
+  return selection?.at(-1) ?? null;
 }
 
 /**
@@ -62,7 +64,7 @@ export function primarySelection(selection: readonly JxPath[] | null | undefined
  * @returns {JxPath | null}
  */
 export function selectionAnchor(selection: readonly JxPath[] | null | undefined): JxPath | null {
-  return selection && selection.length > 0 ? (selection[0] as JxPath) : null;
+  return selection?.[0] ?? null;
 }
 
 /**
@@ -187,7 +189,7 @@ export function comparePaths(a: JxPath, b: JxPath): number {
     if (x === y) {
       continue;
     }
-    if (typeof x === "number" && typeof y === "number") {
+    if (isNumber(x) && isNumber(y)) {
       return x - y;
     }
     return String(x) < String(y) ? -1 : 1;
@@ -231,7 +233,27 @@ export function topLevelSelection(selection: readonly JxPath[]): JxPath[] {
  * @returns {boolean}
  */
 export function isSpliceablePath(path: JxPath): boolean {
-  return path.at(-2) === "children" && typeof path.at(-1) === "number";
+  return spliceCoordinate(path) !== null;
+}
+
+/** Where a structural verb splices: the parent element's path and the index in its children. */
+export interface SpliceCoordinate {
+  parentPath: JxPath;
+  index: number;
+}
+
+/**
+ * The splice coordinate `path` names, or `null` for no path and for every path
+ * {@link isSpliceablePath} refuses.
+ *
+ * @param {JxPath | null | undefined} path
+ * @returns {SpliceCoordinate | null}
+ */
+export function spliceCoordinate(path: JxPath | null | undefined): SpliceCoordinate | null {
+  const index = path?.at(-1);
+  return path && path.at(-2) === "children" && isNumber(index)
+    ? { index, parentPath: path.slice(0, -2) }
+    : null;
 }
 
 /**
@@ -289,7 +311,13 @@ export function selectionsEqual(
 ): boolean {
   const x = a ?? [];
   const y = b ?? [];
-  return x.length === y.length && x.every((p, i) => pathsEqual(p, y[i] as JxPath));
+  return x.length === y.length && x.every((p, i) => pathsEqual(p, y[i] ?? null));
+}
+
+/** One field's value read across the selection: `mixed` when the selected nodes disagree. */
+export interface UnifiedValue<T> {
+  mixed: boolean;
+  value: T | undefined;
 }
 
 /**
@@ -306,13 +334,13 @@ export function selectionsEqual(
  *
  * @template T
  * @param {readonly T[]} values One per selected node, in selection order.
- * @returns {{ mixed: boolean; value: T | undefined }}
+ * @returns {UnifiedValue<T>}
  */
-export function unifyValues<T>(values: readonly T[]): { mixed: boolean; value: T | undefined } {
+export function unifyValues<T>(values: readonly T[]): UnifiedValue<T> {
   if (values.length === 0) {
     return { mixed: false, value: undefined };
   }
-  const first = values[0] as T;
+  const [first] = values;
   const key = JSON.stringify(first ?? null);
   for (let i = 1; i < values.length; i++) {
     if (JSON.stringify(values[i] ?? null) !== key) {