@jxsuite/studio 2.0.0 → 2.1.0

package/src/style/live-preview.ts

@@ -0,0 +1,36 @@
+/**
+ * Pushing a project-style edit to every live canvas — one definition site.
+ *
+ * Plan §9.4's promise is "tune a design token and watch the page change", and until now that was
+ * true of exactly one kind of canvas. `postSiteStyleToLiveHosts` skips stylebook hosts by
+ * construction ({@link file://../canvas/iframe-host.ts}: `host.ready && !host.stylebook`), because
+ * a specimen canvas does not render the site sheet — it renders a GENERATED document whose root
+ * carries the transposed effective style, and its live channel is `styleUpdate`, not
+ * `siteStyleUpdate`. So a token edited in the token editor reached every page canvas immediately
+ * and left the Project Styles canvas — the one the plan puts _beside_ the editor — showing the old
+ * palette until something forced a full re-render.
+ *
+ * Two hosts, two messages, one event. Every surface that writes `projectConfig.style` calls this
+ * instead of picking one of the two posts, which is the only arrangement in which the pair cannot
+ * drift apart again.
+ */
+
+import { postSiteStyleToLiveHosts, postStyleUpdateToStylebookHosts } from "../canvas/iframe-host";
+import { transposeStylebookStyle } from "../panels/stylebook-doc";
+import { getEffectiveStyle } from "../site-context";
+import { activeTab } from "../workspace/workspace";
+
+/**
+ * Re-apply the project's style to every live canvas, in place — no re-render.
+ *
+ * The stylebook post needs the EFFECTIVE style (site merged with the open document's), because a
+ * specimen canvas opened on a component shows that component's `& <tag>` defaults too; posting the
+ * site style alone would silently drop them until the next full render. That is the one thing here
+ * that reads the focused document, and it reads it to refresh a document-level canvas, not to
+ * source a project-level badge.
+ */
+export function pushProjectStylesToCanvas(): void {
+  postSiteStyleToLiveHosts();
+  const style = transposeStylebookStyle(getEffectiveStyle(activeTab.value?.doc.document?.style));
+  postStyleUpdateToStylebookHosts(style as Record<string, unknown>);
+}

package/src/style/project-styles.ts

@@ -0,0 +1,349 @@
+/**
+ * Project Styles — the model behind the project's design tokens and element defaults.
+ *
+ * ## The name and the wire value are different things
+ *
+ * The surface a user reaches is called **Project Styles** (plan §9.4). The canvas view it opens is
+ * the string `"stylebook"`, a member of `CANVAS_MODES` in
+ * {@link file://../canvas/iframe-protocol.ts} and therefore half of a `ParentToIframe` union: the
+ * studio bundle and `dist/iframe-entry.js` agree on it, and changing it means rebuilding both in
+ * lockstep. So it is not a name and may never be renamed to follow one.
+ * {@link PROJECT_STYLES_TITLE} is the name; {@link PROJECT_STYLES_VIEW} is the wire value; a
+ * surface that needs one must not reach for the other.
+ *
+ * ## One vocabulary for the `@` blocks
+ *
+ * A token's value can differ per rendering context, and on disk every such override lives in the
+ * same place — a `@<name>` block beside the token, keyed by a `$media` entry name. Breakpoints and
+ * colour schemes are two _kinds_ of that one thing, and this module models them as one
+ * {@link TokenContext} list so a surface cannot grow a second override path for the second kind (a
+ * per-scheme writer and a per-media writer that disagreed about pruning an emptied block is exactly
+ * what this replaces). Contexts are **defined** in Project Settings › Contexts and only selected or
+ * overridden here — §2 principle 5.
+ *
+ * On-disk format is unchanged by anything in this module: it reads and writes the same
+ * `style["--token"]` and `style["@--ctx"]["--token"]` shapes the compiler already consumes.
+ */
+
+import { parseMediaEntries, schemeOfQuery } from "../utils/canvas-media";
+import { varDisplayName } from "../utils/studio-utils";
+
+import type { JxStyle } from "@jxsuite/schema/types";
+import type { CanvasMode } from "../canvas/iframe-protocol";
+
+/** What the surface is called, everywhere a reader sees it. One definition site. */
+export const PROJECT_STYLES_TITLE = "Project Styles";
+
+/**
+ * The canvas view Project Styles opens — a WIRE value, not a name. See the module doc: it is a
+ * `CANVAS_MODES` member shared with the iframe bundle, and it stays `"stylebook"`.
+ */
+export const PROJECT_STYLES_VIEW: CanvasMode = "stylebook";
+
+// ─── Token groups ────────────────────────────────────────────────────────────
+
+/** The four buckets the token editor lists, in display order. */
+export type TokenGroupId = "color" | "font" | "size" | "other";
+
+export interface TokenGroup {
+  id: TokenGroupId;
+  /** The group heading. */
+  title: string;
+  /** The prefix a token added in this group is named under. */
+  prefix: string;
+}
+
+/**
+ * The groups, in order. `other` is rendered only when something lands in it — a bucket named
+ * "Other" over an empty list teaches nothing (§2 principle 6).
+ *
+ * A group is a name and a prefix and nothing else. The example values an add row hints with are a
+ * property of the FORM, not of the model, and they live beside the form that shows them.
+ */
+export const TOKEN_GROUPS: readonly TokenGroup[] = [
+  { id: "color", prefix: "--color-", title: "Colors" },
+  { id: "font", prefix: "--font-", title: "Fonts" },
+  { id: "size", prefix: "--size-", title: "Sizes & Spacing" },
+  { id: "other", prefix: "--", title: "Other" },
+];
+
+/**
+ * Which group a custom property belongs to, by prefix.
+ *
+ * @param {string} name
+ * @returns {TokenGroupId}
+ */
+export function groupIdOfToken(name: string): TokenGroupId {
+  if (name.startsWith("--color")) {
+    return "color";
+  }
+  if (name.startsWith("--font")) {
+    return "font";
+  }
+  if (name.startsWith("--size") || name.startsWith("--spacing") || name.startsWith("--radius")) {
+    return "size";
+  }
+  return "other";
+}
+
+/**
+ * The label a reader sees for a token: the friendly name it was added under, recovered from the
+ * variable name. `--color-primary-blue` → "Primary Blue".
+ *
+ * The `other` group keeps its raw name deliberately — a token there has no prefix to strip, so "Z
+ * Index Modal" would be a guess at a name its author never typed.
+ *
+ * @param {string} name
+ * @returns {string}
+ */
+export function tokenLabel(name: string): string {
+  const group = groupIdOfToken(name);
+  if (group === "other") {
+    return name;
+  }
+  /*
+   * `varDisplayName` falls back to stripping a bare `--` when the prefix does not match, which is
+   * what turns `--spacing-lg` (group `size`, prefix `--size-`) into "Spacing Lg". The predecessor
+   * chained three prefixes with `||` and never reached the second, because the first always
+   * returns a truthy string.
+   */
+  const { prefix } = TOKEN_GROUPS.find((g) => g.id === group)!;
+  return varDisplayName(name, prefix);
+}
+
+// ─── Tokens ──────────────────────────────────────────────────────────────────
+
+/** One design token declared at the top level of a style block. */
+export interface ProjectToken {
+  /** The custom property, e.g. `--color-primary`. */
+  name: string;
+  group: TokenGroupId;
+  /** What a reader sees — {@link tokenLabel}. */
+  label: string;
+  value: string | number;
+}
+
+/**
+ * Every design token in a style block, in declaration order.
+ *
+ * Non-custom properties (`color: blue`) and object values are not tokens and are skipped — an
+ * object under a `--` key is malformed, and every `@ctx` block is an object by construction.
+ *
+ * @param {JxStyle | null | undefined} style
+ * @returns {ProjectToken[]}
+ */
+export function listTokens(style: JxStyle | null | undefined): ProjectToken[] {
+  if (!style) {
+    return [];
+  }
+  const out: ProjectToken[] = [];
+  for (const [name, value] of Object.entries(style)) {
+    if (!name.startsWith("--")) {
+      continue;
+    }
+    if (typeof value !== "string" && typeof value !== "number") {
+      continue;
+    }
+    out.push({ group: groupIdOfToken(name), label: tokenLabel(name), name, value });
+  }
+  return out;
+}
+
+/**
+ * Group tokens for display: every group in {@link TOKEN_GROUPS} order, each with its members.
+ *
+ * @param {JxStyle | null | undefined} style
+ * @returns {{ group: TokenGroup; tokens: ProjectToken[] }[]}
+ */
+export function groupTokens(
+  style: JxStyle | null | undefined,
+): { group: TokenGroup; tokens: ProjectToken[] }[] {
+  const tokens = listTokens(style);
+  return TOKEN_GROUPS.map((group) => ({
+    group,
+    tokens: tokens.filter((t) => t.group === group.id),
+  }));
+}
+
+// ─── Rendering contexts ──────────────────────────────────────────────────────
+
+/**
+ * What a context IS, for a reader. `size` is a breakpoint, `scheme` is a colour scheme, `feature`
+ * is any other feature query. The distinction decides only how the row is labelled and whether it
+ * is offered unprompted — the on-disk block is the same shape for all three.
+ */
+export type TokenContextKind = "size" | "scheme" | "feature";
+
+/** A declared `$media` entry, seen as a place a token can carry a different value. */
+export interface TokenContext {
+  /** The `$media` entry name, e.g. `--sm` or `--dark`. */
+  name: string;
+  /** The style key its overrides live under, e.g. `@--sm`. */
+  key: string;
+  /** What the reader sees: "Dark" for a scheme, the raw `@--sm` for anything else. */
+  label: string;
+  kind: TokenContextKind;
+  /** Present only when `kind` is `"scheme"`. */
+  scheme?: "light" | "dark";
+}
+
+/**
+ * The contexts a token can be overridden in, derived from `$media`.
+ *
+ * Schemes come first because they are the pair a colour token is always asked about; breakpoints
+ * follow in the order {@link parseMediaEntries} sorts them (the same order the canvas shows its
+ * panels in), then any other feature query. `--` is the base canvas width, not a context.
+ *
+ * @param {Record<string, string> | null | undefined} media
+ * @returns {TokenContext[]}
+ */
+export function listTokenContexts(
+  media: Record<string, string> | null | undefined,
+): TokenContext[] {
+  if (!media) {
+    return [];
+  }
+  const { featureQueries, sizeBreakpoints } = parseMediaEntries(media);
+  const schemes: TokenContext[] = [];
+  const features: TokenContext[] = [];
+  for (const { name, query } of featureQueries) {
+    const scheme = schemeOfQuery(query);
+    if (scheme) {
+      schemes.push({
+        key: `@${name}`,
+        kind: "scheme",
+        label: scheme === "dark" ? "Dark" : "Light",
+        name,
+        scheme,
+      });
+    } else {
+      features.push({ key: `@${name}`, kind: "feature", label: `@${name}`, name });
+    }
+  }
+  const sizes: TokenContext[] = sizeBreakpoints.map(({ name }) => ({
+    key: `@${name}`,
+    kind: "size",
+    label: `@${name}`,
+    name,
+  }));
+  return [...schemes, ...sizes, ...features];
+}
+
+// ─── Overrides ───────────────────────────────────────────────────────────────
+
+/** A token's value in one context, alongside the context it came from. */
+export interface TokenOverride {
+  context: TokenContext;
+  value: string | number;
+}
+
+/**
+ * The block a context's overrides live in, or undefined when the context carries none.
+ *
+ * @param {JxStyle} style
+ * @param {TokenContext} context
+ */
+function overrideBlock(style: JxStyle, context: TokenContext): Record<string, unknown> | undefined {
+  const block = style[context.key];
+  return block && typeof block === "object" ? (block as Record<string, unknown>) : undefined;
+}
+
+/**
+ * A token's value in one context, or undefined when it inherits the base value.
+ *
+ * @param {JxStyle} style
+ * @param {TokenContext} context
+ * @param {string} token
+ * @returns {string | number | undefined}
+ */
+export function readTokenOverride(
+  style: JxStyle,
+  context: TokenContext,
+  token: string,
+): string | number | undefined {
+  const value = overrideBlock(style, context)?.[token];
+  return typeof value === "string" || typeof value === "number" ? value : undefined;
+}
+
+/**
+ * Write or clear a token's override in one context, IN PLACE.
+ *
+ * An empty value clears it, and an emptied block is removed rather than left as `"@--dark": {}` — a
+ * block that exists but says nothing is a diff on every save and a rule the compiler emits for no
+ * reason. The block is recreated on demand, so a caller holding a stale render still writes to the
+ * right place.
+ *
+ * @param {JxStyle} style
+ * @param {TokenContext} context
+ * @param {string} token
+ * @param {string} value — empty clears
+ */
+export function writeTokenOverride(
+  style: JxStyle,
+  context: TokenContext,
+  token: string,
+  value: string,
+): void {
+  if (value) {
+    const block = (style[context.key] ??= {}) as Record<string, unknown>;
+    block[token] = value;
+    return;
+  }
+  const block = overrideBlock(style, context);
+  if (!block) {
+    return;
+  }
+  delete block[token];
+  if (Object.keys(block).length === 0) {
+    delete style[context.key];
+  }
+}
+
+/**
+ * Every context in which a token already carries an override, in {@link listTokenContexts} order.
+ *
+ * @param {JxStyle} style
+ * @param {readonly TokenContext[]} contexts
+ * @param {string} token
+ * @returns {TokenOverride[]}
+ */
+export function tokenOverrides(
+  style: JxStyle,
+  contexts: readonly TokenContext[],
+  token: string,
+): TokenOverride[] {
+  const out: TokenOverride[] = [];
+  for (const context of contexts) {
+    const value = readTokenOverride(style, context, token);
+    if (value !== undefined) {
+      out.push({ context, value });
+    }
+  }
+  return out;
+}
+
+/**
+ * The contexts a token can still be given an override in — the add affordance's menu.
+ *
+ * The predecessor had none: an override row appeared only for a token that already carried an
+ * `@media` block, so the only way to create the first one was to hand-edit `project.json`. This is
+ * the list of contexts that are declared and not yet used, minus the ones already shown unprompted
+ * (`alreadyShown`), so the menu never offers a row the reader is already looking at.
+ *
+ * @param {JxStyle} style
+ * @param {readonly TokenContext[]} contexts
+ * @param {string} token
+ * @param {readonly TokenContext[]} [alreadyShown]
+ * @returns {TokenContext[]}
+ */
+export function addableContexts(
+  style: JxStyle,
+  contexts: readonly TokenContext[],
+  token: string,
+  alreadyShown: readonly TokenContext[] = [],
+): TokenContext[] {
+  const shown = new Set(alreadyShown.map((c) => c.name));
+  return contexts.filter(
+    (context) => !shown.has(context.name) && readTokenOverride(style, context, token) === undefined,
+  );
+}

package/src/style/token-ref.ts

@@ -0,0 +1,123 @@
+/**
+ * Token references — reading `var(--token)` as a binding, and rendering it as a chip.
+ *
+ * A style value that is exactly `var(--something)` is not a value, it is a reference to one. Raw
+ * text says so only to a reader who already knows CSS: `var(--color-brand)` is eleven characters of
+ * syntax around a name, and the thing the author actually wants to know — _which_ token, and what
+ * it currently resolves to — is the part that is not shown. So a bound value renders as a **chip**
+ * (plan §9.4), in the same vocabulary as the provenance chips shipped in P5: the token's friendly
+ * name, and for a colour, its resolved swatch.
+ *
+ * The resolver follows a chain of references, because an alias token (`--color-accent:
+ * var(--color-brand)`) is the normal way a palette is built and a chip that stopped at the first
+ * hop would report `var(--color-brand)` as a colour.
+ */
+
+import { html } from "lit-html";
+import { tokenLabel } from "./project-styles";
+
+import type { JxStyle } from "@jxsuite/schema/types";
+import type { TemplateResult } from "lit-html";
+
+/** A value that is EXACTLY one `var()` reference — not `calc(var(--a) * 2)`, which is a value. */
+const TOKEN_REF_RE = /^var\(\s*(--[\w-]+)\s*\)$/;
+
+/** How many hops the resolver follows before it decides the chain is a cycle. */
+const MAX_HOPS = 10;
+
+/**
+ * The token a value references, or null when the value is not a bare reference.
+ *
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+export function tokenRefName(value: unknown): string | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+  return TOKEN_REF_RE.exec(value)?.[1] ?? null;
+}
+
+/**
+ * The reference form of a token name — the value written into a style field that follows it.
+ *
+ * @param {string} name
+ * @returns {string}
+ */
+export function toTokenRef(name: string): string {
+  return `var(${name})`;
+}
+
+/**
+ * Follow a value's references to the concrete value at the end of the chain.
+ *
+ * Returns undefined when the chain leaves the style block (a token defined by a stylesheet the
+ * editor cannot see) or loops back on itself. A caller shows the raw text in both cases: an
+ * unresolvable reference is still a reference, and inventing a value for it would be worse than
+ * saying nothing.
+ *
+ * @param {JxStyle | null | undefined} style
+ * @param {string | number | null | undefined} value
+ * @returns {string | number | undefined}
+ */
+export function resolveTokenValue(
+  style: JxStyle | null | undefined,
+  value: string | number | null | undefined,
+): string | number | undefined {
+  if (value === null || value === undefined) {
+    return undefined;
+  }
+  let current: string | number = value;
+  const seen = new Set<string>();
+  for (let hop = 0; hop < MAX_HOPS; hop += 1) {
+    const ref = tokenRefName(current);
+    if (!ref) {
+      return current;
+    }
+    if (seen.has(ref)) {
+      return undefined;
+    }
+    seen.add(ref);
+    const next = style?.[ref];
+    if (typeof next !== "string" && typeof next !== "number") {
+      return undefined;
+    }
+    current = next;
+  }
+  return undefined;
+}
+
+/**
+ * Render a bound value as a chip: the referenced token's name, and — for a colour — the swatch it
+ * resolves to. The `title` carries the full reference and its resolution, because the chip is
+ * deliberately short and a reader who needs the literal must still be able to get it.
+ *
+ * The chip is not a control. Following it somewhere would be a second navigation contract on a
+ * surface that already lists every token a scroll away, and a chip that looks clickable and is not
+ * is the defect §6.2 removed from the collapsed-section dot.
+ *
+ * @param {string} name — the referenced token
+ * @param {string | number | undefined} resolved — {@link resolveTokenValue} of the reference
+ * @param {{ swatch?: boolean }} [opts] — `swatch` renders the resolved value as a colour chip
+ * @returns {TemplateResult}
+ */
+export function renderTokenChip(
+  name: string,
+  resolved: string | number | undefined,
+  opts: { swatch?: boolean } = {},
+): TemplateResult {
+  const shown = resolved === undefined ? "unresolved" : String(resolved);
+  return html`
+    <span class="style-token-chip" title="${toTokenRef(name)} → ${shown}">
+      ${
+        opts.swatch && resolved !== undefined
+          ? html`<span
+              class="style-token-chip-swatch"
+              style="background:${String(resolved)}"
+            ></span>`
+          : ""
+      }
+      <span class="style-token-chip-label">${tokenLabel(name)}</span>
+    </span>
+  `;
+}

package/src/tabs/patch-ops.ts

@@ -74,16 +74,28 @@ export interface TransactionRecord {
 export interface PatchConsumer {
   /** Decide whether this batch can be applied surgically in the current canvas state. */
   classify: (tab: Tab, ops: JxPatchOp[]) => { patchable: boolean; reason: string };
-  /** Mark a document root reference as surgically consumed (checked by the canvas doc-effect). */
-  markConsumed: (docRef: object) => void;
+  /**
+   * Mark a document root reference as surgically consumed, in every pane the patch will reach.
+   *
+   * `tab` is what decides those panes — one pane owns it, and a derived pane may be projecting that
+   * pane — and each pane's canvas doc-effect clears only its own mark. A single mark per reference
+   * was consumed by whichever pane's effect ran first, so the second full-rendered every patched
+   * edit while the skip counter reported one skip.
+   */
+  markConsumed: (docRef: object, tab: Tab) => void;
   /**
    * Apply the batch to all ready canvas panels. Throws on any failure (caller escalates). `record`
    * carries the value-carrying `docOps` the iframe consumer posts across the frame boundary; the
    * legacy (parent-DOM) consumer ignores it and reads the post-mutation reactive doc instead.
    */
   apply: (tab: Tab, ops: JxPatchOp[], record?: TransactionRecord) => void;
-  /** Schedule a full canvas render as the fallback path, recording the reason. */
-  escalate: (reason: string) => void;
+  /**
+   * Schedule a full canvas render as the fallback path, recording the reason.
+   *
+   * `tab` names the document that failed to patch, and so the PANE whose stage must be rebuilt: a
+   * stage that is not showing this document is not out of date and must not be re-rendered.
+   */
+  escalate: (reason: string, tab: Tab) => void;
 }
 
 let _consumer: PatchConsumer | null = null;