@jxsuite/studio 6.1.1 → 8.0.0

package/src/panels/stylebook-layers-panel.ts

@@ -1,14 +1,21 @@
 /// <reference lib="dom" />
 /**
- * The Outline panel while the pane is showing Project Styles — the element catalogue and the
- * document's own custom properties.
+ * The Outline panel while the pane is showing a document's Elements view — the element catalogue.
+ *
+ * A page or a component offers **Elements** in its Editor control, which styles that file's element
+ * defaults (`docs/studio/design/stylebook.md`), and the Outline beside it lists the catalogue's
+ * tags instead of the document's tree. `project.json` in the Styles workspace has its own
+ * Navigator, the Styles panel (`panels/styles-panel.ts`), which lists the project's CSS custom
+ * properties too; the variables list this body used to draw beside the Variables view went there
+ * with it.
  *
  * **The body is a Jx document** (`surfaces/panel-stylebook-layers.json`, mounted by
  * `surfaces/panel-stylebook-layers.ts`), so this module renders nothing and projects everything.
- * What stays here is what is a DECISION: how the catalogue's recursive `$sections` flatten into a
- * list, how a child's compound path is spelled, which children are duplicates of each other, which
- * tags the open file has already styled, and which row the current selection marks. The surface
- * reads values.
+ * What stays here is what is a DECISION: which tags the open file has already styled, and what each
+ * row is called. The walk itself (how the catalogue's recursive `$sections` flatten into a list,
+ * how a child's compound path is spelled, which children are duplicates of each other, and which
+ * row the current selection marks) is `stylebook-doc.ts`'s `catalogueRows`, which the Styles
+ * panel's Elements section draws from too. The surface reads values.
  *
  * The panel does not own the panel RECORD — `panels/layers-panel.ts` does, because the Outline is
  * one panel with two bodies and only the record can know which the pane is asking for. That module
@@ -23,16 +30,16 @@ import { activeTab } from "../workspace/workspace";
 import { shell } from "../shell";
 import { componentRegistry } from "../files/components";
 import { mountStylebookLayersSurface } from "../surfaces/panel-stylebook-layers";
+import { catalogueRows } from "./stylebook-doc";
 
 import type { StylebookEntry } from "./stylebook-panel";
 import type {
   StylebookLayersSurfaceHandle,
   StylebookLayersValues,
   StylebookRowView,
-  StylebookVariableView,
 } from "../surfaces/panel-stylebook-layers";
+import { isNonNullObject } from "@jxsuite/schema/guards";
 import type { JxStyle } from "@jxsuite/schema/types";
-import type { ComponentEntry } from "../files/components.js";
 
 /** What the panel is drawn from: the catalogue, and what selecting a row does. */
 export interface StylebookLayersCtx {
@@ -40,9 +47,9 @@ export interface StylebookLayersCtx {
   stylebookMeta: { $sections: { label: string; elements: StylebookEntry[] }[] };
 }
 
-/** The row's own padding at depth 0, and what each level of nesting adds. */
-const INDENT_BASE = 8;
-const INDENT_STEP = 16;
+/** The row's own padding at depth 0, and what each level of nesting adds (the Outline's too). */
+export const INDENT_BASE = 8;
+export const INDENT_STEP = 16;
 
 /**
  * Whether the open file has already written a `& <tag>` block with something in it.
@@ -50,64 +57,9 @@ const INDENT_STEP = 16;
  * @param {JxStyle} rootStyle
  * @param {string} tag
  */
-function hasTagStyle(rootStyle: JxStyle, tag: string) {
+function hasTagStyle(rootStyle: JxStyle, tag: string): boolean {
   const s = rootStyle[`& ${tag}`];
-  return Boolean(s) && typeof s === "object" && Object.keys(s as object).length > 0;
-}
-
-/**
- * The leaf of the current selection.
- *
- * A selection is a compound path (`"ul li"`) and the catalogue draws one row per TAG, so the row
- * that is marked is the one whose tag is the path's last segment. That is what the tree has always
- * done; it is written down here because "selected" meaning something other than "equal" is exactly
- * the kind of thing a reader assumes is a bug.
- */
-function selectedLeaf(selection: string | null): string | null {
-  if (!selection) {
-    return null;
-  }
-  return selection.includes(" ") ? (selection.split(" ").pop() ?? null) : selection;
-}
-
-/**
- * Flatten one catalogue entry and everything under it into rows.
- *
- * Children are deduplicated by tag — a `<ul>` specimen carries two `<li>`s and they are one row,
- * because the row selects a TAG and there is only one `& li` to write.
- */
-function elementRows(
-  entry: StylebookEntry,
-  rootStyle: JxStyle,
-  leaf: string | null,
-  depth: number,
-  parentPath: string,
-  out: StylebookRowView[],
-): void {
-  const { tag } = entry;
-  const fullPath = parentPath ? `${parentPath} ${tag}` : tag;
-  out.push({
-    customized: hasTagStyle(rootStyle, tag),
-    indent: `${INDENT_BASE + depth * INDENT_STEP}px`,
-    key: fullPath,
-    kind: "element",
-    label: entry.text || `<${tag}>`,
-    selected: tag === leaf,
-    tag,
-  });
-  const children = entry.children
-    ? [...new Map(entry.children.map((c: StylebookEntry) => [c.tag, c])).values()]
-    : [];
-  for (const child of children) {
-    elementRows(child, rootStyle, leaf, depth + 1, fullPath, out);
-  }
-}
-
-/** The custom properties the open file declares, in the order it declares them. */
-function variableRows(rootStyle: JxStyle): StylebookVariableView[] {
-  return Object.entries(rootStyle)
-    .filter(([k]) => k.startsWith("--"))
-    .map(([name, value]) => ({ key: name, name, value: String(value) }));
+  return isNonNullObject(s) && Object.keys(s).length > 0;
 }
 
 /**
@@ -121,17 +73,23 @@ function variableRows(rootStyle: JxStyle): StylebookVariableView[] {
  */
 export function stylebookLayersValues(ctx: StylebookLayersCtx): StylebookLayersValues {
   const tab = activeTab.value;
-  const rootStyle = (tab?.doc.document?.style || {}) as JxStyle;
+  const rootStyle: JxStyle = tab?.doc.document?.style || {};
   const { selection } = shell.stylebook;
-  const leaf = selectedLeaf(selection);
 
-  const rows: StylebookRowView[] = [];
-  for (const section of ctx.stylebookMeta.$sections) {
-    for (const entry of section.elements) {
-      elementRows(entry, rootStyle, leaf, 0, "", rows);
-    }
-  }
-  for (const comp of componentRegistry as ComponentEntry[]) {
+  /* The stylebook's own walk (`stylebook-doc.ts` `catalogueRows`), which the Styles panel's
+     Elements section draws from too: the path, the nesting, the deduplication and the leaf mark
+     are one decision, and only the dot and the label are this list's. */
+  const entries = ctx.stylebookMeta.$sections.flatMap((section) => section.elements);
+  const rows: StylebookRowView[] = catalogueRows(entries, selection).map((row) => ({
+    customized: hasTagStyle(rootStyle, row.tag),
+    indent: `${INDENT_BASE + row.depth * INDENT_STEP}px`,
+    key: row.path,
+    kind: "element",
+    label: row.entry.text || `<${row.tag}>`,
+    selected: row.selected,
+    tag: row.tag,
+  }));
+  for (const comp of componentRegistry) {
     rows.push({
       customized: false,
       indent: `${INDENT_BASE}px`,
@@ -145,13 +103,7 @@ export function stylebookLayersValues(ctx: StylebookLayersCtx): StylebookLayersV
     });
   }
 
-  const variables = variableRows(rootStyle);
-  return {
-    hasVariables: variables.length > 0,
-    rows,
-    tab: shell.stylebook.tab,
-    variables,
-  };
+  return { rows };
 }
 
 /**
@@ -161,7 +113,12 @@ export function stylebookLayersValues(ctx: StylebookLayersCtx): StylebookLayersV
  * one Navigator, so a mount into a DIFFERENT node is the old one being replaced, and holding both
  * would leave the first one's effects running against a scope nobody writes any more.
  */
-let standing: { host: HTMLElement; handle: StylebookLayersSurfaceHandle } | null = null;
+let standing: {
+  /** The latest ctx: the handlers read it, not the one the first mount closed over. */
+  ctx: StylebookLayersCtx;
+  host: HTMLElement;
+  handle: StylebookLayersSurfaceHandle;
+} | null = null;
 
 /**
  * Keep the selected row on screen after a repaint.
@@ -174,7 +131,7 @@ function revealSelectedRow(host: HTMLElement): void {
   queueMicrotask(() => {
     host
       .querySelector('[part="row"][aria-current="true"]')
-      ?.scrollIntoView?.({ behavior: "smooth", block: "nearest" });
+      ?.scrollIntoView({ behavior: "smooth", block: "nearest" });
   });
 }
 
@@ -201,12 +158,14 @@ export function mountStylebookLayersPanel(ctx: StylebookLayersCtx, host: HTMLEle
   }
   const values = stylebookLayersValues(ctx);
   if (standing) {
+    standing.ctx = ctx;
     standing.handle.update(values);
   } else {
     standing = {
+      ctx,
       handle: mountStylebookLayersSurface(target, values, {
         selectRow: (path) => {
-          ctx.selectStylebookTag(path, undefined, { panCanvas: true });
+          (standing?.ctx ?? ctx).selectStylebookTag(path, undefined, { panCanvas: true });
         },
       }),
       host: target,
@@ -218,8 +177,8 @@ export function mountStylebookLayersPanel(ctx: StylebookLayersCtx, host: HTMLEle
 /**
  * Take the catalogue down.
  *
- * Called by the Outline's record when the pane is no longer showing Project Styles. Without it the
- * document survives its own irrelevance: lit's branch renders into the range it owns inside
+ * Called by the Outline's record when the pane is no longer showing an Elements view. Without it
+ * the document survives its own irrelevance: lit's branch renders into the range it owns inside
  * `.panel-content` and leaves everything appended after it exactly where it was.
  */
 export function detachStylebookLayers(): void {

package/src/panels/stylebook-panel.ts

@@ -24,19 +24,21 @@ import { projectState, updateSession } from "../store";
 import { createStylebookChromeSurface } from "../surfaces/stylebook-chrome";
 import type { StylebookChromeSurface } from "../surfaces/stylebook-chrome";
 import type { CanvasSurface } from "../canvas/canvas-surface";
-import { tabOfPane } from "../canvas/canvas-surface";
+import { activeMediaOfPane, tabOfPane } from "../canvas/canvas-surface";
 import { activeTab } from "../workspace/workspace";
 import { shell } from "../shell";
 import { componentRegistry } from "../files/components";
-import { getEffectiveMedia, getEffectiveStyle } from "../site-context";
+import { getEffectiveHead, getEffectiveMedia, getEffectiveStyle } from "../site-context";
 import { parseMediaEntries } from "../utils/canvas-media";
 import { mediaDisplayName } from "./shared";
 import { buildStylebookDoc } from "./stylebook-doc";
 import { PROJECT_STYLES_TITLE } from "../style/project-styles";
+import { loadStylebookSpecimens } from "../style/stylebook-specimens";
 import { mountStylebookCanvas, panToStylebookTag } from "../canvas/iframe-host";
 import stylebookMeta from "../../data/stylebook-meta.json";
 import type { CanvasPanelEntry } from "../canvas/canvas-utils";
-import type { CanvasStageView } from "../surfaces/canvas-stage";
+import type { CanvasStageHandle, CanvasStageView } from "../surfaces/canvas-stage";
+import type { TabUi } from "../tabs/tab";
 
 export interface StylebookEntry {
   tag: string;
@@ -61,7 +63,7 @@ interface StylebookCtx {
     surface: CanvasSurface,
     view: CanvasStageView,
     entries: CanvasPanelEntry[],
-  ) => Promise<unknown>;
+  ) => Promise<CanvasStageHandle | null>;
   /** A node the stage drew for a part — here, the empty box the chrome bar stands in. */
   stageHost: (surface: CanvasSurface, part: string) => HTMLElement | null;
   applyTransform: (surface: CanvasSurface) => void;
@@ -123,11 +125,29 @@ function chromeBar(surface: CanvasSurface): HTMLElement {
  * a lit template: the hand-over used to be a `TemplateResult` per artboard, which meant the boards
  * could only be drawn by whoever was already rendering with lit. It is a mount seam instead — the
  * catalogue's bar is a node this module owns, placed in the empty box the stage draws for it, the
- * same way the Compare bar and the Document Header card are.
+ * same way the Compare bar and the writing banner are.
  *
  * @param {StylebookCtx} ctx
  * @returns {Promise<void>} Settles once the artboards are in the page
  */
+/**
+ * The one breakpoint the specimen sheet is drawn at: the one the Context bar's size switcher names
+ * (its `activeMedia`, or the lens a split pane derives), else the base.
+ *
+ * It drew every declared breakpoint side by side, as Design does for a page, and fitting four
+ * artboards into one pane put a 1280px sheet at 24%, where no heading or paragraph can be read; a
+ * sheet of type specimens is read, not compared at a glance. One artboard at the breakpoint being
+ * styled is what the Styles workspace's board shows (Desktop · Tablet · Phone, one at a time), and
+ * it is the breakpoint a style edit lands on, because selecting a specimen writes `activeMedia`.
+ */
+export function stylebookBoards<T extends { name: string }>(
+  boards: readonly T[],
+  active: string | null,
+): T[] {
+  const named = boards.filter((board) => board.name === (active ?? "base"));
+  return named.length > 0 ? named : boards.slice(0, 1);
+}
+
 export async function renderStylebookMode(
   surface: CanvasSurface,
   ctx: StylebookCtx,
@@ -141,6 +161,9 @@ export async function renderStylebookMode(
   const tab = tabOfPane(surface.paneId);
   const filter = shell.stylebook.filter.toLowerCase();
   const { customizedOnly } = shell.stylebook;
+  const generation = surface.renderGeneration;
+  const registry = componentRegistry;
+  const specimensPending = loadStylebookSpecimens(registry);
 
   const effectiveMedia = getEffectiveMedia(tab?.doc.document?.$media);
   const { sizeBreakpoints, baseWidth } = parseMediaEntries(effectiveMedia);
@@ -151,7 +174,7 @@ export async function renderStylebookMode(
      so the field keeps its caret across the stage rebuild a keystroke in it causes. */
   const chromeBarNode = chromeBar(surface);
 
-  (canvasWrap as HTMLElement).style.overflow = "hidden";
+  canvasWrap.style.overflow = "hidden";
 
   /** @type {{ name: string; displayName: string; width: number }[]} */
   const allPanelDefs = [];
@@ -173,7 +196,7 @@ export async function renderStylebookMode(
   /** @type {CanvasPanelEntry[]} */
   let panelEntries;
   if (!hasMedia) {
-    const hasBaseWidth = effectiveMedia && effectiveMedia["--"];
+    const hasBaseWidth = effectiveMedia["--"];
     const label = hasBaseWidth ? `${mediaDisplayName("--")} (${baseWidth}px)` : null;
     panelEntries = [
       ctx.canvasPanelEntry(
@@ -184,7 +207,7 @@ export async function renderStylebookMode(
       ),
     ];
   } else {
-    panelEntries = allPanelDefs.map((def) =>
+    panelEntries = stylebookBoards(allPanelDefs, activeMediaOfPane(surface.paneId)).map((def) =>
       ctx.canvasPanelEntry(def.name, `${def.displayName} (${def.width}px)`, false, def.width),
     );
   }
@@ -219,27 +242,32 @@ export async function renderStylebookMode(
     chromeHost.replaceChildren(chromeBarNode);
   }
 
+  /* What each component card is drawn with (started before the stage was drawn), asked once per
+     registry, so only the first paint after the project's components are read waits for it. A
+     render that began while it was being asked owns the stage now, and this one stops. */
+  const specimens = await specimensPending;
+  if (surface.renderGeneration !== generation) {
+    return;
+  }
+
   // ONE generated doc shared by every panel — per-panel @media differentiation comes from each
   // Iframe's real viewport width, not from a per-panel style flatten.
   const generated = buildStylebookDoc({
-    components: componentRegistry,
+    components: registry,
+    specimens,
     customizedOnly: Boolean(customizedOnly),
-    effectiveMedia: effectiveMedia ?? {},
+    effectiveHead: getEffectiveHead(tab?.doc.document?.$head),
+    effectiveMedia,
     effectiveStyle: getEffectiveStyle(tab?.doc.document?.style),
     filter,
-    meta: stylebookMeta as { $sections: { label: string; elements: StylebookEntry[] }[] },
+    meta: stylebookMeta,
     projectRoot: projectState?.projectRoot ?? null,
   });
 
   const { panels } = surface;
   for (const { panel } of panelEntries) {
     panels.push(panel);
-    mountStylebookCanvas(
-      surface.renderGeneration,
-      generated,
-      panel.canvas as HTMLElement,
-      panel._width,
-    );
+    mountStylebookCanvas(surface.renderGeneration, generated, panel.canvas, panel._width);
   }
   if (hasMedia) {
     ctx.updateActivePanelHeaders(surface);
@@ -259,18 +287,23 @@ export async function renderStylebookMode(
  * @param {string | null} [media]
  */
 export function selectStylebookTag(tag: string, media?: string | null, { panCanvas = false } = {}) {
-  shell.stylebook.selection = tag;
+  const ui: Partial<TabUi> = { activeSelector: tag, rightTab: "style" };
+  if (media !== undefined) {
+    ui.activeMedia = media;
+  }
+  // The session is written BEFORE the stylebook selection moves: writing `shell.stylebook.selection`
+  // Re-runs the Style panel's effect synchronously, and it should find `activeSelector` and the
+  // Breakpoint already in place.
   updateSession(activeTab.value, {
-    // The ROOT path, not an empty selection: stylebook mode has always parked the selection on the
-    // Document element while the Style tab edits a TAG, and widening the field to a list changed
-    // Which literal spells that — `[[]]` is one selected path, the root — not what it means.
-    selection: [[]],
-    ui: {
-      activeSelector: tag,
-      rightTab: "style",
-      ...(media !== undefined ? { activeMedia: media } : {}),
-    },
+    // EMPTY, not the root. A specimen is not a node of the document, so no document path names
+    // What is selected; `stylebookTarget` is how the chrome learns the tag. Parking on the root
+    // `[[]]` made every reader of the document selection (the command bar, the Inspector header)
+    // Name the catalogue's root `div` while `h1` was being edited, and it is what a canvas hit on
+    // A specimen already left behind, so the Outline and the canvas now agree.
+    selection: [],
+    ui,
   });
+  shell.stylebook.selection = tag;
 
   if (tag && panCanvas) {
     panToStylebookTag(tag);