@jxsuite/studio 6.1.1 → 8.0.0

package/src/browse/preview-root.ts

@@ -0,0 +1,78 @@
+/// <reference lib="dom" />
+/**
+ * A live preview's root: the shadow root an island shows a rendered document or component in (the
+ * Site panel's component cards and the Content home's cards, `specs/studio.md` §5.7 and §9.1.2).
+ *
+ * A module of its own, apart from `library-preview.ts`, because what a preview IS (the render, the
+ * cache, the visibility gate) and where it is SHOWN are separate questions, and the second is plain
+ * DOM that every surface hosting a preview answers the same way.
+ *
+ * @docs studio/interface
+ */
+
+import { isFunction } from "@jxsuite/schema/guards";
+import { projectPreviewSheets } from "./preview-style";
+
+/**
+ * The one rule a preview needs that its box cannot give it from outside: an image whose prop
+ * defaults to nothing draws a broken-image icon and its alt text, which in a thumbnail is noise,
+ * not the component. Everything else about the box (its size, its scale, its light surface) is the
+ * surface document's, on the island itself.
+ */
+const PREVIEW_RULES = 'img:not([src]), img[src=""] { visibility: hidden; }';
+
+const _previewSheets = new WeakMap<Document, CSSStyleSheet>();
+
+/** The preview rules as a sheet of `doc`'s own (a constructed sheet is adoptable only there). */
+function previewSheetFor(doc: Document): CSSStyleSheet | null {
+  const known = _previewSheets.get(doc);
+  if (known) {
+    return known;
+  }
+  const Sheet = doc.defaultView?.CSSStyleSheet;
+  if (!isFunction(Sheet)) {
+    return null;
+  }
+  const sheet = new Sheet();
+  sheet.replaceSync(PREVIEW_RULES);
+  _previewSheets.set(doc, sheet);
+  return sheet;
+}
+
+/**
+ * Show a rendered preview in its island, inside a shadow root of the island's own.
+ *
+ * **A preview is a page's part, rendered in Studio's window, and the shadow root is what keeps it a
+ * guest there.** It used to be appended straight into the island, so a component's own ids joined
+ * Studio's: Elite Equipment Rental's `<h2 id="equipment">` was the document's `#equipment`, an
+ * `aria-labelledby` or a fragment link anywhere in the chrome could resolve to a thumbnail, and two
+ * cards of one component made the id a duplicate. Ids, `getElementById` and Studio's linked
+ * stylesheets all stop at the root's boundary; inherited properties (the island's text colour and
+ * size) still cross it, which is what the light document surface relies on.
+ *
+ * The runtime's rules are not lost: the Jx runtime writes every element's style into sheets it
+ * adopts on the document (`openSink` in `@jxsuite/runtime`), keyed on each element's `data-jx`
+ * hash, and those sheets are adopted into the root too, so a component draws as it did. They are
+ * read at each fill, so a sheet the runtime opened since the last one is included.
+ *
+ * @param slot The island the surface document drew empty.
+ * @param rendered The preview, from `previewFor` (`library-preview.ts`).
+ */
+export function mountPreview(slot: HTMLElement, rendered: HTMLElement): void {
+  const root = slot.shadowRoot ?? slot.attachShadow({ mode: "open" });
+  const own = previewSheetFor(slot.ownerDocument);
+  /* The project's sheets first, the runtime's after them: on the page, the site's stylesheet is
+     in the document and the runtime's rules are adopted after it, so a component's own rule wins
+     over a site rule of equal specificity there, and must here. */
+  root.adoptedStyleSheets = [
+    ...projectPreviewSheets(),
+    ...slot.ownerDocument.adoptedStyleSheets,
+    ...(own ? [own] : []),
+  ];
+  root.replaceChildren(rendered);
+}
+
+/** The preview an island is showing, or null while it shows none. */
+export function shownPreview(slot: Element): Element | null {
+  return slot.shadowRoot?.firstElementChild ?? null;
+}

package/src/browse/preview-style.ts

@@ -0,0 +1,155 @@
+/// <reference lib="dom" />
+/**
+ * The project's stylesheet, as a live preview's root adopts it.
+ *
+ * A component card or a page card in the Site panel and the Content home draws a part of a page in
+ * Studio's own window, inside a shadow root of its box (`preview-root.ts`). It drew that part with
+ * the runtime's rules alone: none of the site's tokens, typography or linked stylesheets, which is
+ * where most of a component's look lives, so a museum card or a site header drew as an empty white
+ * box. A page draws with two things this module supplies: `project.json`'s `style`, emitted by the
+ * builder the canvas and the build share (`@jxsuite/site/site-style`), and the stylesheets the
+ * project's `$head` links.
+ *
+ * Both address the page's `:root` and `body`, which a shadow root does not have: inside it the box
+ * the preview is drawn in is `:host`. The project block is emitted with `:host` as its root and
+ * body, and a linked sheet's own `:root`, `html` and `body` selectors are re-pointed at `:host`
+ * through the CSSOM, rule by rule, so a site's custom properties and body typography reach the
+ * preview the way they reach the page. A web font is the one thing that does not: `@font-face` is
+ * not honoured inside a shadow root, so a preview draws in the fallback face.
+ *
+ * Built once per project configuration and shared by every preview of it.
+ *
+ * @docs studio/interface
+ */
+
+import { buildSiteStyleCSS } from "@jxsuite/site/site-style";
+import { isFunction, isNonNullObject, isString } from "@jxsuite/schema/guards";
+import { previewAssetSrcFor } from "../canvas/asset-refs";
+import { projectState } from "../store";
+import type { JxHeadEntry, ProjectConfig } from "@jxsuite/schema/types";
+
+/** The preview box, as a project sheet names the page's root and body inside a shadow root. */
+const HOST_ROOTS = { body: ":host", root: ":host" };
+
+/** Every sheet built for a configuration, settled or in flight. */
+const _sheets = new WeakMap<ProjectConfig, Promise<CSSStyleSheet[]>>();
+/** The settled answers, for the synchronous mount. */
+const _settled = new WeakMap<ProjectConfig, CSSStyleSheet[]>();
+
+/** A selector of the page's root or body re-pointed at the preview box; `null` when unchanged. */
+export function hostSelector(selector: string): string | null {
+  const rewritten = selector
+    .replaceAll(/:root\b/g, ":host")
+    .replaceAll(/(^|[\s,>+~(])(?:html|body)(?![\w-])/g, "$1:host")
+    .replaceAll(/:host(?:\s*>?\s*:host)+/g, ":host");
+  return rewritten === selector ? null : rewritten;
+}
+
+/** What holds rules: a sheet, or a grouping rule (`@media`, `@supports`, a nesting style rule). */
+type RuleContainer = CSSStyleSheet | CSSGroupingRule;
+
+/**
+ * Re-point every style rule under `container` (at any depth of grouping or nesting) at the box.
+ *
+ * A rule is REPLACED by its own text under the new selector rather than assigned a new
+ * `selectorText`: the assignment is settable in browsers but not in every CSSOM, and replacing it
+ * keeps its declarations, its nested rules and its place in source order either way. A rewritten
+ * selector the engine cannot parse keeps the rule as it was.
+ */
+function rehostRules(container: RuleContainer): void {
+  for (let index = 0; index < container.cssRules.length; index += 1) {
+    const rule = container.cssRules[index];
+    const rewritten = rule instanceof CSSStyleRule ? hostSelector(rule.selectorText) : null;
+    if (rule instanceof CSSStyleRule && rewritten !== null) {
+      const text = `${rewritten}${rule.cssText.slice(rule.cssText.indexOf("{"))}`;
+      try {
+        container.insertRule(text, index);
+        container.deleteRule(index + 1);
+      } catch {
+        // Unparseable under the new selector: the original stays.
+      }
+    }
+    const current = container.cssRules[index];
+    if (current instanceof CSSGroupingRule) {
+      rehostRules(current);
+    }
+  }
+}
+
+/** The stylesheet `href`s the project's `$head` links, in order. */
+export function headStylesheetHrefs(head: readonly JxHeadEntry[] | undefined): string[] {
+  const hrefs: string[] = [];
+  for (const entry of head ?? []) {
+    if (!isNonNullObject(entry) || String(entry.tagName).toLowerCase() !== "link") {
+      continue;
+    }
+    const { href, rel } = entry.attributes ?? {};
+    if (isString(href) && href !== "" && isString(rel) && rel.split(/\s+/).includes("stylesheet")) {
+      hrefs.push(href);
+    }
+  }
+  return hrefs;
+}
+
+/** One linked stylesheet as a preview sheet, or null when it cannot be read. */
+async function linkedSheet(href: string): Promise<CSSStyleSheet | null> {
+  const url = previewAssetSrcFor(href, "project.json");
+  try {
+    const response = await fetch(url);
+    if (!response.ok) {
+      return null;
+    }
+    const absolute = new URL(url, location.href).href;
+    // Its own URL as the base, so the sheet's relative `url()` references resolve as they do on the
+    // Page and not against Studio's address.
+    const sheet = new CSSStyleSheet({ baseURL: absolute });
+    sheet.replaceSync(await response.text());
+    rehostRules(sheet);
+    return sheet;
+  } catch {
+    return null;
+  }
+}
+
+/** Build every sheet for one configuration: the linked sheets in `$head` order, then the block. */
+async function buildSheets(config: ProjectConfig): Promise<CSSStyleSheet[]> {
+  const linked = await Promise.all(
+    headStylesheetHrefs(config.$head).map((href) => linkedSheet(href)),
+  );
+  const sheets = linked.filter((sheet): sheet is CSSStyleSheet => sheet !== null);
+  const { style } = config;
+  if (isNonNullObject(style)) {
+    const block = new CSSStyleSheet();
+    block.replaceSync(
+      buildSiteStyleCSS(style, config.$media ?? {}, (value) => value, undefined, HOST_ROOTS),
+    );
+    sheets.push(block);
+  }
+  return sheets;
+}
+
+/**
+ * Read the open project's preview sheets, building them on first ask. A preview awaits this before
+ * it is shown, so {@link projectPreviewSheets} has the answer by the time a box is filled.
+ */
+export function loadProjectPreviewSheets(): Promise<CSSStyleSheet[]> {
+  const config = projectState?.projectConfig;
+  if (!config || !isFunction(globalThis.CSSStyleSheet)) {
+    return Promise.resolve([]);
+  }
+  let pending = _sheets.get(config);
+  if (!pending) {
+    pending = buildSheets(config).then((sheets) => {
+      _settled.set(config, sheets);
+      return sheets;
+    });
+    _sheets.set(config, pending);
+  }
+  return pending;
+}
+
+/** The open project's preview sheets as far as they are built: none until the first read lands. */
+export function projectPreviewSheets(): readonly CSSStyleSheet[] {
+  const config = projectState?.projectConfig;
+  return (config && _settled.get(config)) ?? [];
+}

package/src/canvas/asset-refs.ts

@@ -53,6 +53,9 @@ export function assetContextFor(
   const space = over?.space ?? "site";
   const mount = contentMountFor(
     documentPath,
+    /* SAFETY: `content` is the parser extension's opaque project section, which its project
+       fragment schema defines as a map of section entries; contentMountFor reads only each entry's
+       optional `source` and skips an entry without one. */
     projectState?.projectConfig?.content as Record<string, ContentSectionEntry> | undefined,
     projectLocales(),
   );
@@ -61,13 +64,16 @@ export function assetContextFor(
   if (space === "site" && !mount) {
     return null;
   }
-  return {
+  const context: AssetContext = {
     documentDir: dirOfPath(documentPath ?? ""),
-    ...(over?.fileBaseUrl === undefined ? {} : { fileBaseUrl: over.fileBaseUrl }),
     lanes: BUILD_LANES,
     mounts: mount ? [mount] : [],
     space,
   };
+  if (over?.fileBaseUrl !== undefined) {
+    context.fileBaseUrl = over.fileBaseUrl;
+  }
+  return context;
 }
 
 /**
@@ -91,14 +97,38 @@ export function assetContextFor(
  * @returns {string} A src the parent realm can load
  */
 export function previewAssetSrc(value: string): string {
+  return previewAssetSrcFor(value, activeTab.value?.documentPath);
+}
+
+/**
+ * {@link previewAssetSrc} for a value authored in a NAMED document rather than the focused one.
+ *
+ * A project-level surface (Project Settings › Overview previewing the `$head` favicon of
+ * `project.json`) is about the project whatever tab is in front, so it names its document instead
+ * of asking which one has the focus.
+ *
+ * @param {string} value - The reference as the author wrote it
+ * @param {string | null | undefined} documentPath - Project-relative path of the authoring document
+ * @returns {string} A src the parent realm can load
+ */
+export function previewAssetSrcFor(value: string, documentPath: string | null | undefined): string {
   if (!value) {
     return value;
   }
-  const ctx = assetContextFor(activeTab.value?.documentPath, hostAssetDeclarations());
+  const ctx = assetContextFor(documentPath, hostAssetDeclarations());
   const versioned = ctx && { ...ctx, versions: assetVersionsSnapshot() };
   return loopbackAssetSrc(resolveAssetRef(value, versioned) ?? value);
 }
 
+/**
+ * The registered host's media declarations: its asset space, and the base project files serve
+ * under.
+ */
+export interface HostAssetDeclarations {
+  space?: "site" | "repo" | undefined;
+  fileBaseUrl: string;
+}
+
 /**
  * What the registered host says about media — the platform's `assetSpace`, and the base project
  * files are served under.
@@ -108,14 +138,14 @@ export function previewAssetSrc(value: string): string {
  * The canvas pipeline builds the same two values from the same two places; the difference is only
  * that it already has the document in hand.
  *
- * @returns {{ space?: "site" | "repo"; fileBaseUrl: string }} The host's declarations
+ * @returns {HostAssetDeclarations} The host's declarations
  */
-export function hostAssetDeclarations(): {
-  space?: "site" | "repo" | undefined;
-  fileBaseUrl: string;
-} {
-  return {
+export function hostAssetDeclarations(): HostAssetDeclarations {
+  const declarations: HostAssetDeclarations = {
     fileBaseUrl: documentBase(projectState?.projectRoot),
-    ...(hasPlatform() ? { space: getPlatform().assetSpace } : {}),
   };
+  if (hasPlatform()) {
+    declarations.space = getPlatform().assetSpace;
+  }
+  return declarations;
 }

package/src/canvas/asset-resolve.ts

@@ -45,29 +45,24 @@
 
 import {
   assetUrlFor,
+  CONTENT_SECTION_KEY,
   encodeProjectPath,
   isNonRelativeRef,
   joinProjectPath,
+  LOCALE_PLACEHOLDER,
   projectPathForRef,
+  SAFE_CONTENT_TYPE_NAME,
   splitRefSuffix,
 } from "@jxsuite/schema/asset-paths";
 import type { AssetLane, AssetMount } from "@jxsuite/schema/asset-paths";
+import { isString } from "@jxsuite/schema/guards";
 import type { ContentSectionEntry } from "../types";
 
-/** Content type names safe in a URL path segment. Mirrors `SAFE_TYPE_NAME` in the content loader. */
-const SAFE_TYPE_NAME = /^[\w.~-]+$/;
-
-/** The project.json section key content types live under; also their URL namespace. */
-const SECTION_KEY = "content";
-
-/**
- * The placeholder a content type's `source` may carry to say "one directory per locale".
- *
- * Held here rather than imported out of the parser extension's content loader ({@link
- * file://../../../../extensions/parser/src/content-loader.ts}): that module reads the filesystem
- * and this one runs in a browser. It is also an extension, and core may not import one.
- */
-const LOCALE_PLACEHOLDER = "{locale}";
+/* The content namespace, the URL-safe name test and the `{locale}` token come from
+   `@jxsuite/schema/asset-paths`, the one module both this browser-side resolver and the parser
+   extension's content loader may import: the loader reads the filesystem, and it is an extension,
+   which core may not import. Re-exported so Studio's content modules keep one local import. */
+export { LOCALE_PLACEHOLDER } from "@jxsuite/schema/asset-paths";
 
 /**
  * Everything the canvas needs to resolve one reference, as PLAIN DATA.
@@ -127,7 +122,7 @@ export interface AssetContext {
  * @returns {string} The versioned URL
  */
 export function withVersion(url: string, version: string | undefined): string {
-  if (typeof version !== "string" || version === "") {
+  if (!isString(version) || version === "") {
     return url;
   }
   const hashAt = url.indexOf("#");
@@ -172,7 +167,7 @@ function ownVersion(
     return undefined;
   }
   const version: unknown = versions[path];
-  return typeof version === "string" ? version : undefined;
+  return isString(version) ? version : undefined;
 }
 
 /**
@@ -184,13 +179,14 @@ function ownVersion(
  * file tree cannot reach in the first place.
  *
  * @param {string | null | undefined} documentPath - Project-relative path of the open document
- * @param {Record<string, ContentSectionEntry> | null | undefined} content - Project.json `content`
+ * @param {Record<string, ContentSectionEntry | null | undefined> | null | undefined} content -
+ *   Project.json `content`
  * @param {readonly string[]} [locales] - Canonical locale tags, for `{locale}` sources
  * @returns {AssetMount | null} The mount, project-relative
  */
 export function contentMountFor(
   documentPath: string | null | undefined,
-  content: Record<string, ContentSectionEntry> | null | undefined,
+  content: Record<string, ContentSectionEntry | null | undefined> | null | undefined,
   locales: readonly string[] = [],
 ): AssetMount | null {
   if (!documentPath || !content) {
@@ -204,7 +200,7 @@ export function contentMountFor(
     }
   };
   for (const [name, def] of Object.entries(content)) {
-    if (!def?.source || !SAFE_TYPE_NAME.test(name)) {
+    if (!def?.source || !SAFE_CONTENT_TYPE_NAME.test(name)) {
       continue;
     }
     const dir = normalizeSource(def.source);
@@ -222,7 +218,7 @@ export function contentMountFor(
     if (/\.[a-z0-9]+$/i.test(dir)) {
       continue;
     }
-    consider(dir, `/${SECTION_KEY}/${name}`);
+    consider(dir, `/${CONTENT_SECTION_KEY}/${name}`);
   }
   return best;
 }
@@ -256,15 +252,15 @@ function localeMountFor(
     return null;
   }
   const segment = path.slice(head.length).split("/")[0] ?? "";
-  if (segment === "" || !SAFE_TYPE_NAME.test(segment)) {
+  if (segment === "" || !SAFE_CONTENT_TYPE_NAME.test(segment)) {
     return null;
   }
   const canonical = locales.find((tag) => tag.toLowerCase() === segment.toLowerCase());
-  if (canonical === undefined || !SAFE_TYPE_NAME.test(canonical)) {
+  if (canonical === undefined || !SAFE_CONTENT_TYPE_NAME.test(canonical)) {
     return null;
   }
   const dir = `${head}${segment}${tail}`.replace(/\/+$/, "");
-  return { dir, urlPrefix: `/${SECTION_KEY}/${name}/${canonical}` };
+  return { dir, urlPrefix: `/${CONTENT_SECTION_KEY}/${name}/${canonical}` };
 }
 
 /** Strip `./` and any trailing slash from a configured `source`, the way collectionDirs does. */

package/src/canvas/canvas-helpers.ts

@@ -5,7 +5,8 @@
  * multiple canvas-related modules: element lookup, zoom, panel resolution, inline bubbling.
  */
 
-import { getNodeAtPath, parentElementPath } from "../store";
+import { getNodeAtPath } from "@jxsuite/schema/doc-ops";
+import { parentElementPath } from "../store";
 import { displayTagName } from "@jxsuite/schema/guards";
 import { activeCanvasSurface, activeMediaOfPane } from "./canvas-surface";
 import { isInlineInContext } from "../editor/inline-edit";
@@ -46,7 +47,7 @@ export function panelOfSurface(surface: CanvasSurface): CanvasPanel | null {
   }
   const activeMedia = activeMediaOfPane(surface.paneId);
   for (const p of canvasPanels) {
-    if (activeMedia === null && (p.mediaName === "base" || p.mediaName === null)) {
+    if (activeMedia === null && p.mediaName === "base") {
       return p;
     }
     if (p.mediaName === activeMedia) {
@@ -78,10 +79,10 @@ export function bubbleInlinePath(doc: JxMutableNode | undefined, path: JxPath) {
     return path;
   }
   let currentPath = path;
-  while (currentPath.length >= 2) {
+  // `parentElementPath` is null exactly when the path is too short to have a parent element.
+  for (let pPath = parentElementPath(currentPath); pPath; pPath = parentElementPath(currentPath)) {
     const node = getNodeAtPath(doc, currentPath);
-    const pPath = parentElementPath(currentPath);
-    const parentNode = pPath ? getNodeAtPath(doc, pPath) : null;
+    const parentNode = getNodeAtPath(doc, pPath);
     if (!node || !parentNode) {
       break;
     }
@@ -90,7 +91,7 @@ export function bubbleInlinePath(doc: JxMutableNode | undefined, path: JxPath) {
     if (!isInlineInContext(childTag, parentTag)) {
       break;
     }
-    currentPath = pPath as JxPath;
+    currentPath = pPath;
   }
   return currentPath;
 }