@jxsuite/studio 6.1.1 → 8.0.0

package/src/panels/formula-workspace.ts

@@ -42,10 +42,11 @@
  */
 
 import { nothing } from "lit-html";
-import { getEventBinding, isExpressionDef, isJsonObject } from "@jxsuite/schema/guards";
+import { getNodeAtPath } from "@jxsuite/schema/doc-ops";
+import { getEventBinding, isExpressionDef, isJsonObject, isString } from "@jxsuite/schema/guards";
 
 import { effect, effectScope, shallowRef } from "../reactivity";
-import { getNodeAtPath, updateUi } from "../store";
+import { updateUi } from "../store";
 import { activeTab } from "../workspace/workspace";
 import { mutateAddDef, mutateUpdateDef, mutateUpdateProperty, transactDoc } from "../tabs/transact";
 import { setBottomTab } from "../shell";
@@ -69,14 +70,19 @@ import {
   stringProperty,
 } from "../commands/command-args";
 
-import type { JxNodeValue } from "../tabs/transact";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 import type { PanelBody } from "./panel-registry";
 import type { ExpressionPreview } from "../services/preview-eval";
-import type { FormulaEditDef, FunctionEditDef, JsonValue } from "../types";
+import type { FormulaEditDef, FunctionEditDef } from "../types";
 import type { Tab } from "../tabs/tab";
-import type { JxStateDefinition } from "@jxsuite/schema/types";
+import type {
+  JsonObject,
+  JsonValue,
+  JxEventBinding,
+  JxStateDefinition,
+} from "@jxsuite/schema/types";
 import type { EffectScope } from "@vue/reactivity";
+import type { ScopeValue } from "../editor/merge-tags";
 import type {
   LogicChipView,
   LogicScopeEntryView,
@@ -125,10 +131,10 @@ export function logicTarget(tab: Tab | null = activeTab.value): LogicTarget | nu
     return null;
   }
   if (ui.editingFunction) {
-    return { editing: ui.editingFunction as FunctionEditDef, surface: "function" };
+    return { editing: ui.editingFunction, surface: "function" };
   }
   if (ui.editingFormula) {
-    return { editing: ui.editingFormula as FormulaEditDef, surface: "formula" };
+    return { editing: ui.editingFormula, surface: "formula" };
   }
   return null;
 }
@@ -176,25 +182,35 @@ export function openLogicTarget(target: LogicTarget): void {
   revealLogicPanel();
 }
 
-function isExprNode(value: unknown): value is Record<string, unknown> {
-  return isJsonObject(value) && typeof value.operator === "string";
+/** An expression node: a plain object naming its `operator`. */
+function isExprNode(value: JsonValue | undefined): value is JsonObject {
+  return isJsonObject(value) && isString(value.operator);
 }
 
 // ─── Document access ─────────────────────────────────────────────────────────
 
+/**
+ * The `$expression` of an expression entry or binding, as the JSON object it is; null for anything
+ * else. `isExpressionDef` has already checked it is a plain object, and the guard carries that to
+ * the type.
+ */
+function expressionOf(value: JxStateDefinition | JxEventBinding | undefined): JsonObject | null {
+  if (!isExpressionDef(value)) {
+    return null;
+  }
+  const { $expression } = value;
+  return isJsonObject($expression) ? $expression : null;
+}
+
 /** Read the workspace target's current root expression node from the document. */
-export function formulaRoot(tab: Tab, editing: FormulaEditDef): Record<string, unknown> | null {
+export function formulaRoot(tab: Tab, editing: FormulaEditDef): JsonObject | null {
   const { document } = tab.doc;
   if (editing.type === "def" && editing.defName) {
-    const def = document?.state?.[editing.defName];
-    return isExpressionDef(def) ? (def.$expression as unknown as Record<string, unknown>) : null;
+    return expressionOf(document.state?.[editing.defName]);
   }
   if (editing.type === "event" && editing.path && editing.eventKey) {
     const node = getNodeAtPath(document, editing.path);
-    const binding = node ? getEventBinding(node, editing.eventKey) : undefined;
-    return isExpressionDef(binding)
-      ? (binding.$expression as unknown as Record<string, unknown>)
-      : null;
+    return expressionOf(node ? getEventBinding(node, editing.eventKey) : undefined);
   }
   return null;
 }
@@ -203,18 +219,18 @@ export function formulaRoot(tab: Tab, editing: FormulaEditDef): Record<string, u
  * Resolve a chip selection to its editable node: the deepest expression-node prefix of `path` (head
  * chips target ref/literal operands; stale paths fall back toward the root).
  */
-function resolveSelection(
-  root: Record<string, unknown>,
-  path: NodePath,
-): { node: Record<string, unknown>; path: NodePath } {
-  let current: unknown = root;
-  let node: Record<string, unknown> = root;
+function resolveSelection(root: JsonObject, path: NodePath) {
+  let current: JsonValue | undefined = root;
+  let node = root;
   let nodePath: NodePath = [];
   for (const [i, seg] of path.entries()) {
-    if (!current || typeof current !== "object") {
+    if (Array.isArray(current)) {
+      current = current[Number(seg)];
+    } else if (isJsonObject(current)) {
+      current = current[String(seg)];
+    } else {
       break;
     }
-    current = (current as Record<string, unknown>)[seg as keyof typeof current];
     if (isExprNode(current)) {
       node = current;
       nodePath = path.slice(0, i + 1);
@@ -224,30 +240,28 @@ function resolveSelection(
 }
 
 /** Immutably replace the value at `path` within `node` (object keys / array indexes). */
-function replaceAtPath(node: unknown, path: NodePath, value: unknown): unknown {
-  if (path.length === 0) {
+function replaceAtPath(node: JsonValue | undefined, path: NodePath, value: JsonValue): JsonValue {
+  const [head, ...rest] = path;
+  if (head === undefined) {
     return value;
   }
-  const [head, ...rest] = path as [string | number, ...NodePath];
   if (Array.isArray(node)) {
-    const copy = [...(node as unknown[])];
+    const copy = [...node];
     copy[Number(head)] = replaceAtPath(copy[Number(head)], rest, value);
     return copy;
   }
-  const base: Record<string, unknown> = isJsonObject(node) ? node : {};
-  return { ...base, [head]: replaceAtPath(base[head as string], rest, value) };
+  const base: JsonObject = isJsonObject(node) ? node : {};
+  return { ...base, [head]: replaceAtPath(base[head], rest, value) };
 }
 
 /** Write the whole updated root node back to the document position (one undo step). */
-function writeRoot(tab: Tab, editing: FormulaEditDef, newRoot: unknown) {
+function writeRoot(tab: Tab, editing: FormulaEditDef, newRoot: JsonValue) {
   if (editing.type === "def" && editing.defName) {
     const { defName } = editing;
-    transactDoc(tab, (t) => mutateUpdateDef(t, defName, { $expression: newRoot as JsonValue }));
+    transactDoc(tab, (t) => mutateUpdateDef(t, defName, { $expression: newRoot }));
   } else if (editing.type === "event" && editing.path && editing.eventKey) {
     const { eventKey, path } = editing;
-    transactDoc(tab, (t) =>
-      mutateUpdateProperty(t, path, eventKey, { $expression: newRoot } as JxNodeValue),
-    );
+    transactDoc(tab, (t) => mutateUpdateProperty(t, path, eventKey, { $expression: newRoot }));
   }
 }
 
@@ -288,15 +302,14 @@ function selectionKey(editing: FormulaEditDef): string {
  *
  * The document reports a chip by its key and a button by nothing at all, so the objects behind them
  * — the tab, the target, the root node, the sub-node a commit replaces — live here, rewritten by
- * every projection. Held rather than recomputed at click time for the reason `panels/git-panel.ts`
- * states about its own seat: a callback captured at mount would reach the FIRST projection's
- * document for the rest of the window.
+ * every projection. Held rather than recomputed at click time because a callback captured at mount
+ * would reach the FIRST projection's document for the rest of the window.
  */
 interface Resolved {
   tab: Tab;
   editing: FormulaEditDef;
-  root: Record<string, unknown>;
-  selected: Record<string, unknown>;
+  root: JsonObject;
+  selected: JsonObject;
   selectedPath: NodePath;
   stateEntries: Record<string, JxStateDefinition>;
   preview: ExpressionPreview | null;
@@ -304,19 +317,27 @@ interface Resolved {
   /** Chip key → node path, so a chip click needs no path parsing (a `switch` case may hold "/"). */
   chipPaths: Map<string, NodePath>;
   /** Rail entry name → the value its tree draws. */
-  scopeValues: Map<string, unknown>;
+  scopeValues: Map<string, ScopeValue>;
 }
 
 let _resolved: Resolved | null = null;
 
-/** Replace the selected sub-node inside the root and write the whole root back. */
-function writeSelected(next: unknown): void {
+/**
+ * Replace the selected sub-node inside the root and write the whole root back.
+ *
+ * Typed as the expression editor's own change callback, which is one of its two callers; the other
+ * is a catalog pick's `onChange`.
+ */
+const writeSelected: Parameters<typeof mountExpressionEditor>[2] = (next) => {
   const held = _resolved;
   if (!held) {
     return;
   }
-  writeRoot(held.tab, held.editing, replaceAtPath(held.root, held.selectedPath, next));
-}
+  /* SAFETY: both callers hand back an expression node built of JSON operator/operand values: the
+     expression editor's edited tree, and the node a catalog pick inserts (a JxExpressionNode). */
+  const node = next as JsonValue;
+  writeRoot(held.tab, held.editing, replaceAtPath(held.root, held.selectedPath, node));
+};
 
 // ─── The projection ──────────────────────────────────────────────────────────
 
@@ -354,13 +375,13 @@ function resultOf(
 }
 
 /** The live data context — a SECOND opinion now that the page itself is on screen, not the only one. */
-function railOf(scope: Record<string, unknown> | null | undefined): {
-  entries: LogicScopeEntryView[];
-  values: Map<string, unknown>;
-} {
+function railOf(scope: Tab["session"]["canvas"]["scope"] | undefined) {
   const entries: LogicScopeEntryView[] = [];
-  const values = new Map<string, unknown>();
-  for (const [name, value] of Object.entries(scope ?? {})) {
+  const values = new Map<string, ScopeValue>();
+  /* SAFETY: the canvas scope's one writer (iframe-host.ts, on a `dataScope` message) stores that
+     message's `scope`, a JsonObject of deep-cloned values (serialize-scope.ts). */
+  const snapshot = (scope ?? {}) as JsonObject;
+  for (const [name, value] of Object.entries(snapshot)) {
     entries.push({ key: name, name, type: dataTypeLabel(value) });
     values.set(name, unwrapSignal(value));
   }
@@ -422,7 +443,7 @@ export function workspaceView(): LogicWorkspaceView {
     };
   }
 
-  const stateEntries = (tab.doc.document?.state ?? {}) as Record<string, JxStateDefinition>;
+  const stateEntries = tab.doc.document.state ?? {};
   /* Live-context evaluation in the canvas iframe with snapshot fallback (M6). The canvas is no
      longer unmounted while this surface is open — that is the entire point of the move — so the
      live path is the ORDINARY case now rather than the one that never happened. An event target's
@@ -595,7 +616,10 @@ const ACTIONS: LogicWorkspaceActions = {
 };
 
 /** Vendor a packaged formula's state entry into the document, as one undo step. */
-function insertDef(defName: string, def: unknown): void {
+function insertDef(defName: string, def: JxStateDefinition): void {
+  /* SAFETY: the only def the editor and the catalog insert is a packaged formula's vendored entry
+     (formula-catalog.ts `ensure`): `$description`, `$expression` and `parameters`, all JSON from
+     @jxsuite/formulas. */
   transactDoc(activeTab.value, (t) => mutateAddDef(t, defName, def as Record<string, JsonValue>));
 }
 
@@ -750,7 +774,7 @@ export function formulaEditorCommands(): AnyCommand[] {
         if (!tab) {
           throw new RangeError(`command "formula.editDef" needs an open document`);
         }
-        const defs = tab.doc.document?.state ?? {};
+        const defs = tab.doc.document.state ?? {};
         if (!(defName in defs)) {
           const defined = Object.keys(defs);
           throw new RangeError(

package/src/panels/frontmatter-fields.ts

@@ -9,17 +9,18 @@
  *
  * {@link projectFmField} is the half that says WHAT ONE OF THEM LOOKS LIKE — which control it draws,
  * what that control currently holds, and how to read the control's answer back into a frontmatter
- * value. It is a projection rather than a renderer, and that is the whole of why it lives here:
- * both surfaces that edit frontmatter are Jx documents now (the Document Header card,
- * `src/surfaces/doc-header.json`, and the Navigator's Page panel, `src/surfaces/panel-page.json`),
- * and a document draws its own markup. What they must not each decide is that a `$ref` field is a
- * picker, that `"uri-reference"` is a media format, or that an array is a comma-separated line — so
- * they do not: they ask here and draw the answer.
+ * value. It is a projection rather than a renderer, and that is the whole of why it lives here: the
+ * surface that edits frontmatter is a Jx document (the Inspector's Page tab,
+ * `src/surfaces/panel-page.json`), and a document draws its own markup. What it must not decide for
+ * itself is that a `$ref` field is a picker, that `"uri-reference"` is a media format, or that an
+ * array is a comma-separated line — so it does not: it asks here and draws the answer. (The
+ * Document Header card that once drew the same rows above the canvas is gone, studio.md §4.2.)
  *
  * It replaces `renderFmField`, which was a lit template and could therefore only ever have ONE of
  * the two hosts. The Page panel was the last one, and the renderer went with it.
  */
 
+import { isBoolean, isString } from "@jxsuite/schema/guards";
 import { previewAssetSrc } from "../canvas/asset-refs";
 import { IMAGE_EXTENSIONS, extensionOf } from "../files/media-upload";
 import { referenceEntryState } from "../ui/form-controls";
@@ -29,12 +30,14 @@ import { referenceTarget } from "../ui/schema-form";
 import type { JsonValue } from "../types";
 import type { Tab } from "../tabs/tab";
 import type { ProjectConfig } from "@jxsuite/schema/types";
+import type { SurfaceOption } from "../ui/surface";
 
 export interface FmSchemaEntry {
   type?: string;
   enum?: string[];
   format?: string;
-  properties?: Record<string, unknown>;
+  /** A nested object field's own field schemas. */
+  properties?: Record<string, FmSchemaEntry>;
   /** `#/content/<type>` — a relationship to another collection (site-architecture.md §6.1). */
   $ref?: string;
 }
@@ -42,7 +45,8 @@ export interface FmSchemaEntry {
 export interface FmField {
   field: string;
   entry: FmSchemaEntry;
-  value: JsonValue;
+  /** What the document holds under the key; `undefined` for a schema field it does not set. */
+  value: JsonValue | undefined;
 }
 
 export interface FmFieldSet {
@@ -62,16 +66,23 @@ export interface FmFieldSet {
  *
  * @param {Tab} tab
  * @param {ProjectConfig | null | undefined} projectConfig
- * @param {Set<string>} reserved — keys managed by dedicated controls elsewhere
+ * @param {ReadonlySet<string>} reserved — keys managed by dedicated controls elsewhere
  * @returns {FmFieldSet}
  */
 export function collectFmFields(
   tab: Tab,
   projectConfig: ProjectConfig | null | undefined,
-  reserved: Set<string>,
+  reserved: ReadonlySet<string>,
 ): FmFieldSet {
-  const fm = tab.doc.content?.frontmatter || {};
+  /* SAFETY: `FormatFrontmatter` holds `JxDocumentValue`, which is the JSON value space seen through
+     the typed interfaces a document's declared keys use (JxRef, JxStatement, CemEvent, ...). Every
+     frontmatter value is parsed from the file by a format class's split or JSON-cloned from one, so
+     each is plain JSON data, and viewing it as JsonValue reads the same data without those views. */
+  const fm = tab.doc.content.frontmatter as Record<string, JsonValue | undefined>;
   const collection = findContentTypeSchema(tab.documentPath, projectConfig);
+  /* SAFETY: a collection schema is JSON Schema, and the only keywords an FmSchemaEntry reads —
+     `type`, `format`, `$ref` (strings) and `enum` (a list of choices) — carry those shapes there;
+     `required` is already typed `string[]` on ContentTypeSchema. */
   const schema = collection?.schema as
     | { properties?: Record<string, FmSchemaEntry>; required?: string[] }
     | undefined;
@@ -84,16 +95,16 @@ export function collectFmFields(
       if (reserved.has(field)) {
         continue;
       }
-      fields.push({ entry: fieldSchema, field, value: fm[field] as JsonValue });
+      fields.push({ entry: fieldSchema, field, value: fm[field] });
     }
     for (const [field, value] of Object.entries(fm)) {
       if (schemaProps[field] || field.startsWith("$") || reserved.has(field)) {
         continue;
       }
       fields.push({
-        entry: { type: typeof value === "boolean" ? "boolean" : "string" },
+        entry: { type: isBoolean(value) ? "boolean" : "string" },
         field,
-        value: value as JsonValue,
+        value,
       });
     }
   } else {
@@ -102,9 +113,9 @@ export function collectFmFields(
         continue;
       }
       fields.push({
-        entry: { type: typeof value === "boolean" ? "boolean" : "string" },
+        entry: { type: isBoolean(value) ? "boolean" : "string" },
         field,
-        value: value as JsonValue,
+        value,
       });
     }
   }
@@ -112,12 +123,6 @@ export function collectFmFields(
   return { collection, fields, hasSchema: Boolean(schemaProps), requiredFields };
 }
 
-/** One choice in a row's picker — the shape `jx-select` reads. */
-export interface FmChoice {
-  value: string;
-  label: string;
-}
-
 /**
  * One frontmatter field as a surface draws it. Every field is present whatever the `kind`, because
  * a document's binding renders a value and its `$switch` chooses on one: a row that omitted
@@ -140,7 +145,7 @@ export interface FmRowView {
   /** A text row's placeholder. Empty draws none. */
   placeholder: string;
   /** A picker's rows, in the order they are offered. Empty on every other kind. */
-  options: FmChoice[];
+  options: SurfaceOption[];
   /** A sentence under the control — an empty collection, or a listing that failed. */
   note: string;
   /** Whether {@link FmRowView.note} has anything in it; `$switch` is a document's conditional. */
@@ -162,8 +167,8 @@ export interface FmRowProjection {
 }
 
 /** A frontmatter value as the text a field shows. An object is not a string and never pretends. */
-function text(value: unknown): string {
-  return typeof value === "string" ? value : "";
+function text(value: JsonValue | undefined): string {
+  return isString(value) ? value : "";
 }
 
 /** A blank row, so every kind carries every field a surface's bindings read. */
@@ -188,7 +193,7 @@ function blankRow(label: string): FmRowView {
  *
  * @param {string} field The frontmatter key.
  * @param {FmSchemaEntry} entry Its schema, or the type inferred from the value it already holds.
- * @param {unknown} value What the document says today.
+ * @param {JsonValue | undefined} value What the document says today.
  * @param {Set<string>} requiredFields The collection's required keys, for the label's marker.
  * @param {{ rerender: () => void }} opts How a surface is repainted when a referenced collection's
  *   entry ids land — the one asynchronous read a row can start.
@@ -197,7 +202,7 @@ function blankRow(label: string): FmRowView {
 export function projectFmField(
   field: string,
   entry: FmSchemaEntry,
-  value: unknown,
+  value: JsonValue | undefined,
   requiredFields: Set<string>,
   opts: { rerender: () => void },
 ): FmRowProjection {
@@ -294,7 +299,7 @@ export function projectFmField(
     return {
       parse: (raw) => {
         /* NaN is deleted rather than written. The two surfaces this replaced disagreed here: the
-           Page panel's `spNumberField` refused a non-number and the Document Header card wrote
+           Page panel's `spNumberField` refused a non-number and the old Document Header card wrote
            `NaN` into the frontmatter, where it round-trips to `null`. One answer, and it is the
            one that cannot corrupt the document. */
         const trimmed = String(raw).trim();

package/src/panels/git-diff-open.ts

@@ -130,10 +130,14 @@ export function openDiffTab(path: string): Tab {
  * leave the comparison for Design without reopening anything; a file it cannot gets the stub tab
  * above. Both are keyed by the path, so §14.1 holds either way — one path, one tab.
  *
- * `files/files.ts` is imported dynamically because it imports `cleanupGitPanel` from
- * `panels/git-panel.ts`, which imports this module: a static edge back would close that cycle.
- * `openFileInTab` answers `void` when it reveals a tab that was already open, so the tab is
- * resolved from the workspace either way.
+ * The document tab opens IN `git-diff`, and an already-open one is moved into it before it is
+ * revealed: a comparison belongs to Publish (studio.md §22.1), and a tab activated in its edit mode
+ * would enter Design, frame and all, for the moment before the mode followed.
+ *
+ * `files/files.ts` is imported dynamically because it imports `cleanupSourceControl` from
+ * `publish/source-control.ts`, which imports this module: a static edge back would close that
+ * cycle. `openFileInTab` answers `void` whether it opens a new tab or reveals one that was already
+ * open, so the tab is resolved from the workspace by its path.
  *
  * Answers null when the file could not be opened at all, which the caller states rather than
  * silently leaving the stage on someone else's document.
@@ -143,6 +147,6 @@ export async function openComparisonTab(path: string): Promise<Tab | null> {
     return openDiffTab(path);
   }
   const files = await import("../files/files");
-  const opened = await files.openFileInTab(path, {});
-  return opened ?? [...workspace.tabs.values()].find((tab) => tab.documentPath === path) ?? null;
+  await files.openFileInTab(path, { canvasMode: "git-diff" });
+  return [...workspace.tabs.values()].find((tab) => tab.documentPath === path) ?? null;
 }