@jxsuite/studio 6.1.1 → 8.0.0

package/src/canvas/canvas-page-context.ts

@@ -0,0 +1,112 @@
+/**
+ * The `$site` and `$page` a page or a collection entry is drawn with on the canvas.
+ *
+ * A built page reads `${$page.locale}`, `${$page.url}` and `${$site.name}` from the state the build
+ * injects (site-architecture.md §10, §13.4). The canvas injected none of it, so every one of those
+ * bindings was undefined there: a component handed `$page.locale` as its locale threw a
+ * `RangeError` and was not rendered, and Preview of a multilingual page drew no list at all. The
+ * injection is `@jxsuite/site/context`'s, the one the build calls, because a host that improvised
+ * its own subset would differ from the build in whichever field it forgot.
+ *
+ * The route is the document's own: a page's URL pattern from its file, with the route parameters
+ * chosen for the preview; an entry's URL from its collection's template page in the entry's own
+ * language (studio.md §22.5), with the entry filling the page's parameter.
+ *
+ * @docs studio/interface/canvas
+ */
+
+import { injectContext } from "@jxsuite/site/context";
+import { documentUrlPattern } from "@jxsuite/site/routes";
+import { isString } from "@jxsuite/schema/guards";
+import { resolveI18n } from "@jxsuite/schema/locale";
+import { collectionForFile } from "../content/collection-match";
+import { collectionPage, entryLocale, entryUrl } from "../content/collection-pages";
+import type { SiteRoute } from "@jxsuite/site/context";
+import type {
+  JxDocument,
+  JxDocumentValue,
+  JxStateDefinition,
+  ProjectConfig,
+} from "@jxsuite/schema/types";
+
+/** The two injected state entries. */
+export interface PageContext {
+  $site: JxStateDefinition;
+  $page: JxStateDefinition;
+}
+
+/** What {@link pageContextFor} reads off the document being drawn. */
+export interface PageContextSource {
+  /** The project-relative path of the page or entry. */
+  documentPath: string;
+  /** Whether it is a collection entry rather than a page. */
+  isEntry: boolean;
+  /** The document's own `title` and `$lang`, which win over the route's. */
+  title?: JxDocumentValue | undefined;
+  lang?: JxDocumentValue | undefined;
+  /** An entry's fields (Markdown frontmatter), which may fill its URL and title. */
+  fields?: Readonly<Record<string, JxDocumentValue | undefined>> | null;
+  /** The route parameters chosen for a dynamic page's preview. */
+  params?: Readonly<Record<string, string>>;
+}
+
+/** The parameters `url` fills in `pattern`, by position: `/blog/:slug` and `/blog/a` → `{slug: a}`. */
+export function routeParams(pattern: string, url: string): NonNullable<SiteRoute["_pathParams"]> {
+  const values = url.split("/");
+  const out: NonNullable<SiteRoute["_pathParams"]> = {};
+  for (const [i, name] of pattern.split("/").entries()) {
+    const value = values[i];
+    if (name.startsWith(":") && value !== undefined) {
+      out[name.slice(1)] = value;
+    }
+  }
+  return out;
+}
+
+/** The route a document is served at, as the build would serve it. */
+async function routeOf(source: PageContextSource): Promise<SiteRoute> {
+  const { documentPath, fields, isEntry, params } = source;
+  if (!isEntry) {
+    return {
+      _pathParams: { ...params },
+      sourcePath: documentPath,
+      urlPattern: documentUrlPattern(documentPath),
+    };
+  }
+  const match = collectionForFile(documentPath);
+  const page = match ? await collectionPage(match.name, entryLocale(documentPath)) : null;
+  const url = entryUrl(page, documentPath, fields);
+  if (!page || url === null) {
+    return { _pathParams: {}, sourcePath: documentPath, urlPattern: page?.pattern ?? "/" };
+  }
+  return { _pathParams: routeParams(page.pattern, url), sourcePath: page.path, urlPattern: url };
+}
+
+/**
+ * The `$site` and `$page` for one document, injected exactly as the build injects them, or `null`
+ * when there is no project configuration to inject from.
+ */
+export async function pageContextFor(
+  source: PageContextSource,
+  projectConfig: ProjectConfig | null | undefined,
+): Promise<PageContext | null> {
+  if (!projectConfig) {
+    return null;
+  }
+  const route = await routeOf(source);
+  const fieldTitle = source.fields?.title;
+  const title = isString(source.title) ? source.title : isString(fieldTitle) ? fieldTitle : null;
+  // A scratch document: the injection writes project state, `$media`, imports and `$elements` onto
+  // The document it is handed, and the canvas composes those its own way. Only the two context
+  // Entries are taken from it.
+  const doc: JxDocument = { state: {} };
+  if (title !== null) {
+    doc.title = title;
+  }
+  if (isString(source.lang)) {
+    doc.$lang = source.lang;
+  }
+  const scratch = injectContext(doc, projectConfig, route, null, resolveI18n(projectConfig).i18n);
+  const { $page, $site } = scratch.state ?? {};
+  return $page === undefined || $site === undefined ? null : { $page, $site };
+}

package/src/canvas/canvas-patcher.ts

@@ -18,7 +18,9 @@
  * edit typed into the first, and how one failed patch would rebuild both.
  */
 
-import { getNodeAtPath, parentElementPath } from "../store";
+import { getNodeAtPath } from "@jxsuite/schema/doc-ops";
+import { isString } from "@jxsuite/schema/guards";
+import { parentElementPath } from "../store";
 import { canvasModeOfPane, surfacesShowingTab } from "./canvas-surface";
 import { toRaw } from "../reactivity";
 import { postPatchToHosts } from "./iframe-host";
@@ -29,6 +31,13 @@ import type { CanvasSurface } from "./surface-registry";
 import type { JxPatchOp, TransactionRecord } from "../tabs/patch-ops";
 import type { Tab } from "../tabs/tab.js";
 import type { JxPath } from "../state";
+import type { JxMutableNode } from "@jxsuite/schema/types";
+
+/** Whether a batch can be applied surgically, and why not when it cannot. */
+export interface PatchVerdict {
+  patchable: boolean;
+  reason: string;
+}
 
 /** Render-side callbacks injected at init so this module stays free of heavy canvas imports. */
 interface CanvasPatcherCtx {
@@ -62,10 +71,17 @@ export function initCanvasPatcher(ctx: CanvasPatcherCtx) {
     apply: applyPatchBatch,
     classify: classifyOps,
     escalate: escalateToFullRender,
-    markConsumed: (docRef: object, tab: Tab) => {
-      markConsumed(
-        docRef,
-        patchableSurfaces(tab).map((surface) => surface.paneId),
+    /* Records that `docRef`'s change has been applied surgically in each patchable pane.
+
+       No empty-list guard, because the list cannot be empty here: `transactDoc` marks only a batch
+       {@link classifyOps} called patchable, and that function rejects `patchableSurfaces(tab).length
+       === 0` before it can say so. A guard on an unreachable value is a branch no test can enter (the
+       gate's own rule), and `_consumed` is a `WeakMap` keyed on a reference `transactDoc` mints fresh
+       per transaction, so there is nothing for one to protect either. */
+    markConsumed: (docRef, tab) => {
+      _consumed.set(
+        toRaw(docRef),
+        new Set(patchableSurfaces(tab).map((surface) => surface.paneId)),
       );
     },
   });
@@ -96,32 +112,16 @@ function patchableSurfaces(tab: Tab | null): CanvasSurface[] {
   });
 }
 
-/**
- * Record that `docRef`'s change has been applied surgically in each of `paneIds`.
- *
- * No empty-list guard, because the list cannot be empty here: `transactDoc` marks only a batch
- * {@link classifyOps} called patchable, and that function rejects `patchableSurfaces(tab).length
- * === 0` before it can say so. A guard on an unreachable value is a branch no test can enter — the
- * gate's own rule — and `_consumed` is a `WeakMap` keyed on a reference `transactDoc` mints fresh
- * per transaction, so there is nothing for one to protect either.
- *
- * @param {object} docRef
- * @param {readonly string[]} paneIds
- */
-function markConsumed(docRef: object, paneIds: readonly string[]) {
-  _consumed.set(toRaw(docRef) as object, new Set(paneIds));
-}
-
 /**
  * One-shot check used by ONE PANE's canvas doc-effect: returns true (and clears that pane's mark)
  * when the given document reference was already applied to that pane's stage surgically, so its
  * full render can be skipped. One-shot so tab switches and repeat triggers still render fully.
  *
- * @param {object} doc
+ * @param {JxMutableNode} doc
  * @param {string} paneId
  */
-export function consumePatchedDocument(doc: object, paneId: string): boolean {
-  const raw = toRaw(doc) as object;
+export function consumePatchedDocument(doc: JxMutableNode, paneId: string): boolean {
+  const raw = toRaw(doc);
   const panes = _consumed.get(raw);
   if (!panes?.has(paneId)) {
     return false;
@@ -221,7 +221,7 @@ function containerVerdict(tab: Tab, parentPath: JxPath, requireArray = true): st
    * definition escalated to a full render — in a component-heavy project, the most common authoring
    * action there is.
    */
-  if (parentPath.length > 0 && typeof parent.tagName === "string" && parent.tagName.includes("-")) {
+  if (parentPath.length > 0 && isString(parent.tagName) && parent.tagName.includes("-")) {
     return "structure-in-custom-element";
   }
   if (parent.innerHTML) {
@@ -253,7 +253,7 @@ function replaceVerdict(tab: Tab, path: JxPath): string | null {
   if (pathHasDynamicSegment(path)) {
     return "replace-on-cases-path";
   }
-  const parentPath = parentElementPath(path) as JxPath | null;
+  const parentPath = parentElementPath(path);
   if (!parentPath) {
     return "replace-no-parent";
   }
@@ -295,7 +295,7 @@ function opVerdict(tab: Tab, op: JxPatchOp): string | null {
       if (!node) {
         return "node-not-found";
       }
-      if (typeof node.tagName === "string" && node.tagName.includes("-")) {
+      if (isString(node.tagName) && node.tagName.includes("-")) {
         return "text-on-custom-element";
       }
       if (node.innerHTML) {
@@ -320,14 +320,14 @@ function opVerdict(tab: Tab, op: JxPatchOp): string | null {
       return containerVerdict(tab, op.parentPath);
     }
     case "remove": {
-      const parentPath = parentElementPath(op.path) as JxPath | null;
+      const parentPath = parentElementPath(op.path);
       return parentPath === null ? "remove-no-parent" : containerVerdict(tab, parentPath);
     }
     case "move": {
       if (pathHasDynamicSegment(op.fromPath)) {
         return "structure-on-cases-path";
       }
-      const fromParentPath = parentElementPath(op.fromPath) as JxPath | null;
+      const fromParentPath = parentElementPath(op.fromPath);
       if (fromParentPath === null) {
         return "move-no-parent";
       }
@@ -347,7 +347,7 @@ function opVerdict(tab: Tab, op: JxPatchOp): string | null {
  * @param {Tab} tab
  * @param {JxPatchOp[]} ops
  */
-export function classifyOps(tab: Tab, ops: JxPatchOp[]): { patchable: boolean; reason: string } {
+export function classifyOps(tab: Tab, ops: JxPatchOp[]): PatchVerdict {
   const reject = (reason: string) => {
     recordEscalation(reason);
     return { patchable: false, reason };

package/src/canvas/canvas-perf.ts

@@ -12,6 +12,9 @@
  * marks with `localStorage["jx-canvas-debug"] = "1"`.
  */
 
+import { isFunction } from "@jxsuite/schema/guards";
+import type { JsonValue } from "@jxsuite/schema/types";
+
 /** Rolling window per span. Bounded so a long session cannot grow the sample arrays. */
 const SAMPLE_LIMIT = 128;
 
@@ -106,7 +109,12 @@ export const canvasPerf: CanvasPerf = {
   timings: {},
 };
 
-(globalThis as Record<string, unknown>).__jxCanvasPerf = canvasPerf;
+declare global {
+  /** The live counters, for inspection from a devtools console or a profiling harness. */
+  var __jxCanvasPerf: CanvasPerf | undefined;
+}
+
+globalThis.__jxCanvasPerf = canvasPerf;
 
 /** Retained duration samples per span, parallel to `canvasPerf.timings`. */
 const samples = new Map<string, number[]>();
@@ -121,13 +129,11 @@ function debugEnabled() {
 
 /** Monotonic clock, or 0 when the environment has no `performance` (durations then read as 0). */
 function now(): number {
-  return typeof performance !== "undefined" && typeof performance.now === "function"
-    ? performance.now()
-    : 0;
+  return typeof performance !== "undefined" && isFunction(performance.now) ? performance.now() : 0;
 }
 
 /** Log a canvas perf event when debug mode is on. */
-export function perfLog(event: string, detail?: unknown) {
+export function perfLog(event: string, detail?: JsonValue) {
   if (debugEnabled()) {
     console.debug(`[jx-canvas] ${event}`, detail ?? "");
   }