@jxsuite/site 2.7.0 → 2.8.0

package/README.md

@@ -2,7 +2,7 @@
 
 **What a Jx project's page at a route consists of:** routing, layout, `<head>`, context and site style, as pure functions with their IO injected.
 
-Every one of these rules has to be answered identically by four things that cannot share code any other way: the compiler's static build, the Studio canvas, a Bun dev/desktop server, and a Cloudflare Worker serving a live preview. None of them can import `@jxsuite/compiler`, whose dependency graph carries `sharp` and `esbuild`, so neither a browser bundle nor a Worker can load it. And a route is exactly the kind of rule where a silent disagreement is a page that 404s in one surface and renders in another.
+Every one of these rules has to be answered identically by four things that cannot share code any other way: the compiler's static build, the Studio canvas, a Bun dev/desktop server, and a Cloudflare Worker serving a live preview. None of them can import `@jxsuite/compiler`, whose dependency graph carries a native addon and `esbuild`, so neither a browser bundle nor a Worker can load it. And a route is exactly the kind of rule where a silent disagreement is a page that 404s in one surface and renders in another.
 
 So the rules live here, and this package has **no platform imports at all**: no `node:`, no DOM, no filesystem. Where a rule genuinely needs to read something, the reader is a parameter (`LayoutLoader`, `DocumentParser`) and is simply absent where there are no directories.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/site",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "What a Jx project's page at a route consists of — routing, layout, context, head and the document that boots it",
   "license": "MIT",
   "repository": {
@@ -34,7 +34,7 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/runtime": "^7.0.0",
-    "@jxsuite/schema": "^6.0.0"
+    "@jxsuite/runtime": "^7.1.0",
+    "@jxsuite/schema": "^6.0.2"
   }
 }

package/src/routes.ts

@@ -9,9 +9,9 @@
  * another.
  *
  * It lives HERE rather than in `@jxsuite/compiler` for the reason `resolveI18n` does (`i18n.ts`):
- * the compiler's dependency graph carries `sharp` and `esbuild`, so neither a browser bundle nor a
- * Cloudflare Worker can import it. This module is pure string math with no imports at all, so every
- * host that has to know what `/blog/:slug` means can share one answer.
+ * the compiler's dependency graph carries a native addon and `esbuild`, so neither a browser bundle
+ * nor a Cloudflare Worker can import it. This module is pure string math with no imports at all, so
+ * every host that has to know what `/blog/:slug` means can share one answer.
  */
 
 /** Bracket route segments: `[param]` (named) and `[...param]` (catch-all). */

package/src/site-style.ts

@@ -29,6 +29,10 @@
  * to differ was a nested element key, on the belief that "the document's own style pass covers page
  * content": nothing else reads `project.json#/style`, so the canvas simply dropped a site's
  * typography and link rules while the build kept them (#296).
+ *
+ * A block's `$description` is the one thing only the build renders: a static build writes it as a
+ * comment above the rule (`{ comments: true }`, spec.md §9.2), and a host never does, because every
+ * consumer but a static build ignores the description.
  */
 
 import {
@@ -36,11 +40,12 @@ import {
   buildStyleRules,
   isDeclarationAtRule,
   isKeyframesAtRule,
+  commentedRuleText,
   isNestedSelectorKey,
   pureSchemeOf,
 } from "@jxsuite/runtime/css";
 import type { CssBuildOptions } from "@jxsuite/runtime/css";
-import { isNonNullObject } from "@jxsuite/schema/guards";
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
 import type { JxRef, JxStyle } from "@jxsuite/schema/types";
 
 /** Id of the injected site-style tag (replace-in-place, never accumulate). */
@@ -76,9 +81,29 @@ export interface SiteStyleRoots {
   body: string;
 }
 
+/** What a caller may ask of the sheet beyond its rules. */
+export interface SiteStyleOptions {
+  /**
+   * Write each described rule's `$description` as a comment on the line above it. The static
+   * build's switch: the canvas and the live preview leave it off and emit the rule text alone.
+   */
+  comments?: boolean;
+}
+
 /** The page's own root and body. */
 export const PAGE_ROOTS: SiteStyleRoots = { body: "body", root: ":root" };
 
+/**
+ * Hand a block's own `$description` to the first rule its split writes: the root's when it holds a
+ * declaration, the body's otherwise. A block that writes neither rule carries no comment.
+ */
+function describeFirstRule(block: JxStyle, root: JxStyle, body: JxStyle): void {
+  const description = block["$description"];
+  if (isString(description)) {
+    (Object.keys(root).length > 0 ? root : body)["$description"] = description;
+  }
+}
+
 /**
  * Build the site-style sheet text: custom properties on `:root`, plain properties on `body`,
  * selector-keyed blocks (`"h1, h2"`, `a`, `.card`) as rules of their own, `&`-keyed blocks as
@@ -104,6 +129,7 @@ export const PAGE_ROOTS: SiteStyleRoots = { body: "body", root: ":root" };
  *   is dropped, which is what every host does
  * @param {SiteStyleRoots} [roots] - The selectors that stand for the page's root and body; the
  *   page's own `:root` and `body` unless the sheet styles a page drawn inside something else
+ * @param {SiteStyleOptions} [options] - `comments: true` is the static build's form
  * @returns {string}
  * @docs studio/interface/canvas
  */
@@ -113,19 +139,20 @@ export function buildSiteStyleCSS(
   transpose: (value: string) => string,
   resolveValue?: SiteStyleValueResolver,
   roots: SiteStyleRoots = PAGE_ROOTS,
+  options: SiteStyleOptions = {},
 ): string {
   const rules: string[] = [];
   const push = (style: JxStyle, selector: string | null) => {
-    const options: CssBuildOptions = { mediaQueries, scope: selector, transposeValue: transpose };
+    const build: CssBuildOptions = { mediaQueries, scope: selector, transposeValue: transpose };
     /* The selector is closed over here rather than threaded through `buildStyleRules`, whose own
        hook sees a rule TARGET (self / descendant / unscoped) and not the selector it hangs off;
        the compiler's report names the selector, so this is where it is known. Set only when given:
        `exactOptionalPropertyTypes` refuses an explicit `undefined` for an optional hook. */
     if (resolveValue) {
-      options.resolveValue = (property, value) => resolveValue(property, value, selector);
+      build.resolveValue = (property, value) => resolveValue(property, value, selector);
     }
-    for (const rule of buildStyleRules(style, options)) {
-      rules.push(rule.text);
+    for (const rule of buildStyleRules(style, build)) {
+      rules.push(options.comments === true ? commentedRuleText(rule) : rule.text);
     }
   };
 
@@ -157,7 +184,8 @@ export function buildSiteStyleCSS(
       }
       continue;
     }
-    if (isNestedSelectorKey(key) || key.startsWith("@")) {
+    // Metadata is no declaration; the block's own `$description` is placed after the split.
+    if (isNestedSelectorKey(key) || key.startsWith("@") || key.startsWith("$")) {
       continue;
     }
     /* Custom properties go to `:root`; so does `color-scheme`, which is the one non-custom
@@ -172,6 +200,8 @@ export function buildSiteStyleCSS(
     }
   }
 
+  describeFirstRule(siteStyle, rootProps, bodyProps);
+
   // Base rules precede conditional blocks so equal-specificity overrides win by source order.
   push(rootProps, roots.root);
   push(bodyProps, roots.body);
@@ -206,12 +236,16 @@ export function buildSiteStyleCSS(
         }
         continue;
       }
+      if (k.startsWith("$")) {
+        continue;
+      }
       if (k.startsWith("--")) {
         condRoot[k] = v;
       } else {
         condBody[k] = v;
       }
     }
+    describeFirstRule(block, condRoot, condBody);
     push({ [atKey]: condRoot }, roots.root);
     push({ [atKey]: condBody }, roots.body);
     for (const [sel, sub] of condSubs) {