@jxsuite/studio 6.1.2 → 8.0.0

package/src/style/project-styles.ts

@@ -40,6 +40,40 @@ export const PROJECT_STYLES_TITLE = "Project Styles";
  */
 export const PROJECT_STYLES_VIEW: CanvasMode = "stylebook";
 
+/**
+ * The editor the Variables view draws under: the CSS custom properties of `project.json`'s root
+ * style block (§7.1). A Studio-side editor mode like `media` or `entry`, not a canvas render, so it
+ * is not a member of the iframe protocol's `CANVAS_MODES` and nothing in the frame bundle reads
+ * it.
+ */
+export const PROJECT_VARIABLES_VIEW = "tokens";
+
+/** The Code editor's mode over the same document. */
+const PROJECT_SOURCE_VIEW = "source";
+
+/**
+ * The Styles workspace's three views of the `project.json` tab, by the names `styles.open` takes,
+ * in the order the pane's Editor control offers them: the element defaults (keyed by tag name), the
+ * custom properties, and the file as text. One map, so the argument enum, the tab's mode list and
+ * the editor labels cannot disagree about which mode a view is.
+ */
+export const STYLES_VIEW_MODES = {
+  elements: PROJECT_STYLES_VIEW,
+  variables: PROJECT_VARIABLES_VIEW,
+  code: PROJECT_SOURCE_VIEW,
+} as const;
+
+/** A view `styles.open` can be asked for. */
+export type StylesView = keyof typeof STYLES_VIEW_MODES;
+
+/** Every view name, in the Editor control's order. */
+export const STYLES_VIEWS: readonly StylesView[] = ["elements", "variables", "code"];
+
+/** The `project.json` tab's modes, in that same order. */
+export const STYLES_TAB_MODES: readonly string[] = STYLES_VIEWS.map(
+  (view) => STYLES_VIEW_MODES[view],
+);
+
 // ─── Token groups ────────────────────────────────────────────────────────────
 
 /** The four buckets the token editor lists, in display order. */

package/src/style/stylebook-specimens.ts

@@ -0,0 +1,89 @@
+/**
+ * What each project component's Project Styles card is drawn with.
+ *
+ * The catalogue drew every component as a bare instance with only its declared defaults, and a
+ * component is rarely drawable that way: the museum starter's `<mu-exhibition-card>` formats a
+ * `date` that defaults to `""`, so its card stayed empty and the canvas logged "was not rendered:
+ * RangeError: Invalid time value" for it on every paint (`spec.md` §16.4). The Site panel's
+ * previews already know where a component's sample props live (`browse/component-examples.ts`), so
+ * a card asks the same three sources, in the same order, and draws:
+ *
+ * - `props`: an instance given its sample props, when the definition renders with them;
+ * - `row`: the first row of a list that draws it, when it is only ever used as a list row;
+ * - `bare`: the bare instance, when it renders with its defaults and nothing better was found;
+ * - `none`: no live instance at all (the catalogue's placeholder box), when it renders with none of
+ *   the above, because an instance that throws draws nothing and reports an error nobody can fix.
+ *
+ * Answers are cached per component registry: the registry is replaced whenever the project's
+ * components are re-read, so a changed definition is asked again.
+ *
+ * @docs studio/design/stylebook
+ */
+
+import { componentExampleProps, componentSampleRow } from "../browse/component-examples";
+import type { SampleRow } from "../browse/component-examples";
+import { readDefinition, rendersWith } from "../browse/library-preview";
+import { defineComponent } from "../panels/component-preview";
+import type { ComponentEntry } from "../files/components";
+import type { JsonValue } from "@jxsuite/schema/types";
+
+/** How one component card is drawn; see the module comment. */
+export type StylebookSpecimen =
+  | { kind: "props"; props: Record<string, JsonValue> }
+  | { kind: "row"; sample: SampleRow }
+  | { kind: "bare" }
+  | { kind: "none" };
+
+/** The specimens of the components a catalogue draws, by tag name. */
+export type StylebookSpecimens = ReadonlyMap<string, StylebookSpecimen>;
+
+const cache = new WeakMap<readonly ComponentEntry[], Map<string, Promise<StylebookSpecimen>>>();
+
+/** One component's specimen. A component that is not a project JSON definition is drawn bare. */
+export async function componentSpecimen(component: ComponentEntry): Promise<StylebookSpecimen> {
+  const { path } = component;
+  if (component.source === "npm" || !path?.endsWith(".json")) {
+    return { kind: "bare" };
+  }
+  const definition = await readDefinition(path);
+  if (!definition) {
+    return { kind: "bare" };
+  }
+  const props = await componentExampleProps(definition, path);
+  if (props.size > 0 && (await rendersWith(definition, path, props))) {
+    return { kind: "props", props: Object.fromEntries(props) };
+  }
+  const sample = await componentSampleRow(definition, path);
+  if (sample && (await defineComponent(component))) {
+    return { kind: "row", sample };
+  }
+  return (await rendersWith(definition, path, new Map())) ? { kind: "bare" } : { kind: "none" };
+}
+
+/**
+ * The specimens of every component in `registry`, asked once per registry and component. A
+ * component whose answer cannot be found is drawn bare, as it was before specimens existed.
+ */
+export async function loadStylebookSpecimens(
+  registry: readonly ComponentEntry[],
+  ask: (component: ComponentEntry) => Promise<StylebookSpecimen> = componentSpecimen,
+): Promise<StylebookSpecimens> {
+  let answers = cache.get(registry);
+  if (!answers) {
+    answers = new Map();
+    cache.set(registry, answers);
+  }
+  const known = answers;
+  const entries = await Promise.all(
+    registry.map(async (component): Promise<[string, StylebookSpecimen]> => {
+      const key = component.path ?? component.tagName;
+      let answer = known.get(key);
+      if (!answer) {
+        answer = ask(component).catch((): StylebookSpecimen => ({ kind: "bare" }));
+        known.set(key, answer);
+      }
+      return [component.tagName, await answer];
+    }),
+  );
+  return new Map(entries);
+}

package/src/style/stylebook-target.ts

@@ -0,0 +1,26 @@
+/**
+ * What a tab is styling while it draws the Styles workspace's Elements view: a TAG, not a node.
+ *
+ * The Elements view is a catalogue of specimens, and picking one moves `shell.stylebook.selection`
+ * (`selectStylebookTag`), never the tab's document selection: an `h1` specimen is not a node of
+ * `project.json`, so there is no path that names it. Every place that answers "what am I pointed
+ * at" (the status bar's selection field, the command bar's selection segment, the Inspector's
+ * header) asks this first, and falls back to the document selection only when it says null. Before
+ * they shared it, two of the three read the document selection alone, and the Outline's row click
+ * parked that on the root, so `h1 · Base` was being edited under a header and a path that both said
+ * `div`.
+ *
+ * The answer is null outside the Elements view, which is the whole condition the status bar always
+ * had: the stylebook selection outlives a workspace switch (coming back to Styles finds `h1` still
+ * picked), but a Content page, the Variables view or the Publish home is not editing `h1`.
+ */
+
+import { shell } from "../shell";
+import { PROJECT_STYLES_VIEW } from "./project-styles";
+
+import type { Tab } from "../tabs/tab";
+
+/** The tag the tab's Elements view is styling, or null when the tab is not styling a tag. */
+export function stylebookTarget(tab: Tab | null | undefined): string | null {
+  return tab?.session.ui.canvasMode === PROJECT_STYLES_VIEW ? shell.stylebook.selection : null;
+}

package/src/style/tag-inheritance.ts

@@ -0,0 +1,105 @@
+/**
+ * What a Project Styles tag rule inherits, and from where.
+ *
+ * `project.json`'s style compiles its flat properties to `body` and each bare tag key to a global
+ * rule (`compileStyles`, via `site/site-build.ts`), so an `h1` with no `fontFamily` of its own is
+ * set in whatever `body` says, and a `th` under `table` takes `table`'s colour first. The Style
+ * panel's own walk (`computeInheritedSources`) only follows ONE coordinate across contexts, which
+ * is right for a page element (its ancestors are other nodes, edited elsewhere) and wrong here:
+ * every ancestor of a tag rule is in this same file. Without this, an unset inherited row showed
+ * the CSS initial value as its placeholder, so Font Family on `h1` read "depends on user agent"
+ * while the specimen beside it was drawn in the project's body font.
+ *
+ * Only properties CSS inherits are walked ({@link INHERITED_PROPERTIES}); `margin` on `body` is not
+ * a value an `h1` has.
+ *
+ * @docs studio/design/stylebook
+ */
+
+import { getNestedStyle, isNumber, isString } from "@jxsuite/schema/guards";
+import type { JxStyle } from "@jxsuite/schema/types";
+
+/**
+ * The properties the Style panel draws (`data/css-meta.json`) that CSS defines as inherited.
+ *
+ * A list rather than a lookup because the panel bundle carries no CSS property database: the test
+ * beside this module holds it to `@webref/css` in both directions, so a property is here exactly
+ * when the panel draws it and the specification says `Inherited: yes`.
+ */
+export const INHERITED_PROPERTIES: ReadonlySet<string> = new Set([
+  "color",
+  "cursor",
+  "fontFamily",
+  "fontSize",
+  "fontStyle",
+  "fontVariant",
+  "fontWeight",
+  "letterSpacing",
+  "lineHeight",
+  "listStyleType",
+  "pointerEvents",
+  "textAlign",
+  "textShadow",
+  "textTransform",
+  "visibility",
+  "wordBreak",
+  "wordSpacing",
+]);
+
+/** One inherited value and the rule that supplies it: `body`, or an ancestor tag in the path. */
+export interface TagAncestorSource {
+  value: string | number;
+  donor: string;
+}
+
+/** The declarations of `block` that CSS inherits, layered over `into` as coming from `donor`. */
+function layerInherited(
+  into: Map<string, TagAncestorSource>,
+  block: JxStyle | undefined,
+  donor: string,
+): void {
+  for (const [prop, value] of Object.entries(block ?? {})) {
+    if (INHERITED_PROPERTIES.has(prop) && (isString(value) || isNumber(value))) {
+      into.set(prop, { donor, value });
+    }
+  }
+}
+
+/** The style a tag path addresses (`table th` → `style.table.th`), or undefined when absent. */
+function tagBlock(style: JxStyle | undefined, path: readonly string[]): JxStyle | undefined {
+  let block = style;
+  for (const tag of path) {
+    block = getNestedStyle(block, tag);
+  }
+  return block;
+}
+
+/**
+ * What the tag at `tagPath` inherits from the rules above it, nearest donor winning: `body` (the
+ * flat properties), then each ancestor tag in the path. In a context (`media`, a breakpoint or a
+ * scheme block's name without its `@`), each donor's block in that context is layered over its
+ * base, which is the order the compiled stylesheet applies them in.
+ */
+export function tagAncestorSources(
+  style: JxStyle,
+  tagPath: string,
+  media: string | null,
+): Record<string, TagAncestorSource> {
+  const path = tagPath.split(" ").filter(Boolean);
+  const contextStyle = media ? getNestedStyle(style, `@${media}`) : undefined;
+  const sources = new Map<string, TagAncestorSource>();
+  /* `body` is spelled two ways and both compile to the one rule: the flat properties, and a `body`
+     tag key. The tag key is later in the sheet, so it is layered second. */
+  const ancestors: string[][] = [[], ...(path[0] === "body" ? [] : [["body"]])];
+  for (let depth = 1; depth < path.length; depth += 1) {
+    ancestors.push(path.slice(0, depth));
+  }
+  for (const ancestor of ancestors) {
+    const donor = ancestor.at(-1) ?? "body";
+    layerInherited(sources, tagBlock(style, ancestor), donor);
+    if (contextStyle) {
+      layerInherited(sources, tagBlock(contextStyle, ancestor), donor);
+    }
+  }
+  return Object.fromEntries(sources);
+}

package/src/style/variables-focus.ts

@@ -0,0 +1,61 @@
+/**
+ * Where the Variables view should point next: one custom property, or one group of them.
+ *
+ * The Styles panel (`panels/styles-panel.ts`) lists every CSS custom property and every group, and
+ * choosing one shows it in the Variables view (`style/variables-view.ts`). The panel does not own
+ * the pane, so it does not call into the view: it files a REQUEST here and the view, which watches
+ * {@link variablesFocus}, scrolls the row into view and puts the keyboard on it. A request made
+ * while the view is not on screen yet (the pane was in Elements) is served when the view mounts,
+ * once: {@link VariablesFocusRequest.served} is what tells a new request from one already served.
+ *
+ * The property the view MARKS is `shell.stylebook.variable`, written here too, so the panel and the
+ * editor mark the same row.
+ *
+ * @docs studio/design/tokens
+ */
+
+import { shallowRef } from "../reactivity";
+import { shell } from "../shell";
+import type { TokenGroupId } from "./project-styles";
+
+/** What the Variables view is asked to bring on screen. */
+export type VariablesFocus =
+  /** One custom property, `--accent`: its row is scrolled to and its value field focused. */
+  | { kind: "variable"; name: string }
+  /**
+   * One group (Colors, Fonts, …): its heading is scrolled to, and with `add` its Add row's name
+   * field is focused, which is how "Add variable" reaches the editor's own add flow.
+   */
+  | { kind: "group"; group: TokenGroupId; add: boolean };
+
+/**
+ * One request. `served` is set by the view that brought it on screen, so a second view (another
+ * pane, or the same pane drawn again) does not move the keyboard for a click it has already
+ * answered. A plain field on a SHALLOW ref's value: serving a request is not a change anybody
+ * watches.
+ */
+export interface VariablesFocusRequest {
+  focus: VariablesFocus | null;
+  served: boolean;
+}
+
+/** The latest request. Every assignment is a new request; nothing asked yet is a served `null`. */
+export const variablesFocus = shallowRef<VariablesFocusRequest>({ focus: null, served: true });
+
+/**
+ * Ask the Variables view to bring a property or a group on screen. Choosing the property already
+ * chosen asks again, which brings it back after the author scrolled away.
+ *
+ * @param {VariablesFocus} focus
+ */
+export function requestVariablesFocus(focus: VariablesFocus): void {
+  if (focus.kind === "variable") {
+    shell.stylebook.variable = focus.name;
+  }
+  variablesFocus.value = { focus, served: false };
+}
+
+/** Forget any request not yet served: a project switch, whose views are not this request's. */
+export function resetVariablesFocus(): void {
+  variablesFocus.value = { focus: null, served: true };
+}

package/src/style/variables-view.ts

@@ -0,0 +1,235 @@
+/// <reference lib="dom" />
+/**
+ * The Variables view: the Styles workspace's editor for the project's CSS custom properties
+ * (studio.md §7.1).
+ *
+ * It is the `tokens` editor of the `project.json` tab, beside Elements (the `stylebook` specimens)
+ * and Code (`source`), so the pane's Editor control switches between the three over one document,
+ * one history and one dirty flag. What it draws is the CSS Variables editor that used to be a
+ * Project Settings section (`settings/css-vars-editor.ts`), unchanged, inside a frame of its own
+ * (`surfaces/styles-variables.json`) that says what a variable is, when an edit reaches the file
+ * and where colour schemes are declared.
+ *
+ * **Saving is stated, not implied.** The editor commits every edit through the configuration
+ * chokepoint as it is made (`updateSiteConfig` → `commitProjectConfig`), which writes the whole
+ * document and leaves the tab clean, while an edit in the Elements view is a transaction on the tab
+ * that waits for ⌘S. Both models are kept; what is not allowed is the author learning the
+ * difference from the Save button, so the view says it in words ({@link VARIABLES_SAVING}).
+ *
+ * **One configuration object.** Before the editor draws, the open `project.json` tab is made the
+ * configuration document of record (`projectConfigDocument`), so the object the editor mutates is
+ * the tab's own and an element style edit made a moment ago in Elements is not a rival the commit
+ * would refuse (`tabs/project-config.ts`).
+ *
+ * **It follows the document.** An edit that reaches the tab another way (an undo, the Code view, an
+ * element style edit that wrote a custom property) re-projects the editor, and choosing a variable
+ * or a group in the Styles panel (`style/variables-focus.ts`) points the editor at it.
+ *
+ * Mounted per pane, keyed by pane id, for the reason `media/media-pane.ts` gives: two panes can
+ * each show a view at once.
+ *
+ * @docs studio/design/tokens
+ */
+
+import { effect, effectScope, pauseTracking, resetTracking } from "../reactivity";
+import { projectState } from "../store";
+import { shell } from "../shell";
+import { runActiveReported } from "../commands/run-reported";
+import { projectConfigDocument } from "../tabs/project-config";
+import { PROJECT_CONFIG_PATH } from "../tabs/tab";
+import { paneRegion } from "../ui/regions";
+import { focusCssVar, focusCssVarGroup, renderCssVarsEditor } from "../settings/css-vars-editor";
+import { variablesFocus } from "./variables-focus";
+import type { VariablesFocus } from "./variables-focus";
+import { mountVariablesSurface } from "../surfaces/styles-variables";
+import type { VariablesSurfaceHandle, VariablesView } from "../surfaces/styles-variables";
+import type { Tab } from "../tabs/tab";
+import type { CanvasSurface } from "../canvas/canvas-surface";
+
+/** The view's heading: the name its Editor control row gives it too. */
+export const VARIABLES_TITLE = "Variables";
+
+/** What a variable is, in the words of the platform feature it is. */
+export const VARIABLES_LEDE =
+  "Your site's CSS custom properties, kept in the root style block of project.json. Every page " +
+  "and component can use one in any style value as var(--name).";
+
+/**
+ * When an edit here reaches the file, which is not when an Elements edit does.
+ *
+ * Three sentences, each one rule, with the exception named AS an exception. It was one sentence
+ * saying a change is saved as you make it and the next saying Save writes the value, which a reader
+ * took as the view contradicting itself rather than as undo being the case that waits.
+ */
+export const VARIABLES_SAVING =
+  "Each change here is written to project.json as you make it, so there is nothing to save " +
+  "afterwards. The write also saves any Elements change still waiting for Save, because both " +
+  "live in that file. Undo is the exception: an undone change waits for Save like any other edit.";
+
+/** Where color schemes and breakpoints are declared, which is not here. */
+export const VARIABLES_SCHEMES =
+  "To give a variable another value in a color scheme or at a breakpoint, use Add override " +
+  "under its row. The schemes and breakpoints themselves are declared in Project settings, " +
+  "under Contexts.";
+
+/** What the view draws in `paneId`. Pure: every word is a constant. */
+export function variablesView(paneId: string): VariablesView {
+  return {
+    lede: VARIABLES_LEDE,
+    // The label every door to Contexts wears: the pane context bar's footer and the Colors group's notice.
+    manageLabel: "Manage contexts…",
+    region: paneRegion(paneId, "variables"),
+    saving: VARIABLES_SAVING,
+    schemes: VARIABLES_SCHEMES,
+    title: VARIABLES_TITLE,
+  };
+}
+
+// ─── Mounting ────────────────────────────────────────────────────────────────
+
+interface ActiveVariablesView {
+  paneId: string;
+  tabId: string;
+  wrap: HTMLElement;
+  surface: VariablesSurfaceHandle;
+  scope: { stop: () => void; run: <T>(fn: () => T) => T | undefined };
+}
+
+const _active = new Map<string, ActiveVariablesView>();
+
+/** Whether this tab's view is already mounted in this pane and still in the document. */
+export function variablesViewMounted(paneId: string, tab: Tab): boolean {
+  const view = _active.get(paneId);
+  return (
+    view !== undefined && view.tabId === tab.id && view.wrap.isConnected && view.surface.attached()
+  );
+}
+
+/** Tear one pane's view down (mode change, tab switch, project close). Idempotent. */
+export function detachVariablesView(paneId: string): void {
+  const view = _active.get(paneId);
+  if (!view) {
+    return;
+  }
+  view.scope.stop();
+  view.surface.dispose();
+  _active.delete(paneId);
+}
+
+/** Open Project Settings on Contexts. A refusal is filed under this view's workspace. */
+function manageContexts(): void {
+  void runActiveReported("settings.open", { section: "contexts" }, "Styles");
+}
+
+/**
+ * Make the open `project.json` tab the configuration document, so the object the editor mutates in
+ * place is the tab's own. A no-op with no project, and for any other document.
+ */
+function bindConfiguration(tab: Tab): void {
+  if (projectState && tab.documentPath === PROJECT_CONFIG_PATH) {
+    projectConfigDocument();
+  }
+}
+
+/** Bring what a request names on screen in `host`, the editor island. */
+function serve(host: HTMLElement, focus: VariablesFocus | null): void {
+  if (focus?.kind === "group") {
+    focusCssVarGroup(host, focus.group, { add: focus.add });
+    return;
+  }
+  focusCssVar(host, focus?.name ?? shell.stylebook.variable);
+}
+
+/** Serve the latest request in `host` if no view has served it yet. Whether it did. */
+function serveLatest(host: HTMLElement): boolean {
+  const request = variablesFocus.value;
+  if (request.served) {
+    return false;
+  }
+  request.served = true;
+  serve(host, request.focus);
+  return true;
+}
+
+/** Run `fn` without the calling effect tracking what it reads. */
+function untracked(fn: () => void): void {
+  pauseTracking();
+  try {
+    fn();
+  } finally {
+    resetTracking();
+  }
+}
+
+/**
+ * Draw the Variables view into a pane's stage.
+ *
+ * @param {CanvasSurface} surface
+ * @param {Tab} tab The `project.json` tab, in its `tokens` editor
+ */
+export function renderVariablesMode(surface: CanvasSurface, tab: Tab): void {
+  const { paneId, wrap } = surface;
+  if (variablesViewMounted(paneId, tab)) {
+    return;
+  }
+  detachVariablesView(paneId);
+  bindConfiguration(tab);
+
+  /** The editor island, once the document has created it. */
+  let editorHost: HTMLElement | null = null;
+
+  const mounted = mountVariablesSurface(
+    wrap,
+    variablesView(paneId),
+    { manageContexts },
+    {
+      editorSlot: (host) => {
+        editorHost = host;
+        renderCssVarsEditor(host);
+        /* A request the Styles panel made while the pane was in another view (a variable or a
+           group chosen from Elements) is served now, once. Otherwise the marked property is only
+           MARKED: arriving at the view is not a request to move the keyboard. */
+        if (!serveLatest(host) && shell.stylebook.variable !== null) {
+          focusCssVar(host, shell.stylebook.variable, { reveal: false });
+        }
+      },
+    },
+  );
+  const scope = effectScope();
+  _active.set(paneId, { paneId, scope, surface: mounted, tabId: tab.id, wrap });
+
+  scope.run(() => {
+    /* What the editor shows, read off the TAB so an undo, a Code edit or a transaction that
+       replaced the root re-projects it. Serialised, because a property nested in an `@` block is
+       a change the editor draws and a shallow read would not see. */
+    let seen: string | null = null;
+    effect(() => {
+      const { document } = tab.doc;
+      const key = JSON.stringify([document.style ?? null, document.$media ?? null]);
+      if (key === seen) {
+        return;
+      }
+      const first = seen === null;
+      seen = key;
+      const host = editorHost;
+      if (!first && host) {
+        untracked(() => {
+          bindConfiguration(tab);
+          renderCssVarsEditor(host);
+        });
+      }
+    });
+    /* The Styles panel's variable rows, group headings and "Add variable". Every request is a new
+       value, so choosing the same property again, after scrolling away from it, brings it back
+       again. */
+    effect(() => {
+      void variablesFocus.value;
+      const host = editorHost;
+      if (host) {
+        untracked(() => {
+          serveLatest(host);
+        });
+      }
+    });
+  });
+}