@jxsuite/compiler 5.1.3 → 6.0.1

package/src/site/site-build.ts

@@ -69,7 +69,7 @@ import type { AssetMount } from "@jxsuite/schema/asset-paths";
 import type { FormatEntry, FormatRegistry } from "@jxsuite/schema/format-registry";
 import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
 import { resolveLayout } from "./layout-resolver.ts";
-import { mergeHead, renderHead } from "@jxsuite/site/head-merger";
+import { mergeHead, renderHead, withPageDescription } from "@jxsuite/site/head-merger";
 import { unregisteredHeadRelations } from "./link-relations.ts";
 import { injectContext } from "./context-injection.ts";
 import { compile, compileServer, compileSiteServer } from "../compiler.ts";
@@ -84,18 +84,22 @@ import {
   collectServerEntries,
   collectStyles,
   colorSchemePrePaintScript,
+  createSlotFill,
+  definitionHasSlot,
   escapeStyleText,
   evaluateStaticTemplate,
   isComponentFullyStatic,
   isSingleExpression,
   liftPropsAttributes,
+  nextSlotId,
   preRenderComponentHtml,
   pureSchemeOf,
   renderStaticNode,
   resolveHostStyle,
   resolveRefValue,
 } from "../shared.ts";
-import type { ComponentPrerenderContext } from "../shared.ts";
+import type { ComponentPrerenderContext, StaticChild } from "../shared.ts";
+import { SLOT_ATTR } from "@jxsuite/runtime";
 import { resolvePrototypes } from "./prototype-resolver.ts";
 import { transformImageNodes } from "./image-transform.ts";
 import { collectCspSources, emptyCspSources } from "./csp.ts";
@@ -1343,7 +1347,10 @@ async function compilePage(
   // Extract head arrays before they get lost in the merge
   /* SAFETY: `_pageHead` is written only by `resolveLayout`, which copies the page's `$head` (a
      JxHeadEntry[]) into it when the page has one. */
-  const pageHead = (pageDoc.$head ?? layoutDoc._pageHead ?? []) as JxHeadEntry[];
+  const pageHead = withPageDescription(
+    (pageDoc.$head ?? layoutDoc._pageHead ?? []) as JxHeadEntry[],
+    pageDoc.description,
+  );
   const layoutHead = layoutDoc.$head ?? [];
   /* SAFETY: `_pageTitle` is written only by `resolveLayout`, which copies the page's `title` (a
      string) into it when the page has one. */
@@ -1423,7 +1430,9 @@ async function compilePage(
     media: { ...projectConfig.$media, ...layoutDoc.$media },
     rules: [],
   };
-  expandComponents(layoutDoc, componentDefs, slotCss, projectConfig.defaults);
+  // One counter per page, so every `data-jx-slots` id on it is unique (spec.md §8.5).
+  const slotIds = { n: 0 };
+  expandComponents(layoutDoc, componentDefs, slotCss, projectConfig.defaults, slotIds);
 
   // Strip resolved timing: "compiler" state entries — they're now baked into the tree
   // And keeping them would cause isDynamic() to misclassify the page as dynamic.
@@ -2208,19 +2217,21 @@ interface SlotCssCollector {
  * @param {Map<string, JxElement>} componentDefs
  * @param {SlotCssCollector} [slotCss]
  * @param {ProjectConfig["defaults"]} [defaults] - Read for `defaults.shadow` (spec.md §16.6)
+ * @param {{ n: number }} [slotIds] - The page's `data-jx-slots` counter
  */
 function expandComponents(
   node: JxElement | string | (JxElement | string)[],
   componentDefs: Map<string, JxElement>,
   slotCss?: SlotCssCollector,
   defaults?: ProjectConfig["defaults"],
+  slotIds?: { n: number },
 ) {
   if (!isNonNullObject(node)) {
     return;
   }
   if (Array.isArray(node)) {
     for (const n of node) {
-      expandComponents(n, componentDefs, slotCss, defaults);
+      expandComponents(n, componentDefs, slotCss, defaults, slotIds);
     }
     return;
   }
@@ -2228,7 +2239,7 @@ function expandComponents(
   // Recurse into children first (bottom-up expansion)
   if (Array.isArray(node.children)) {
     for (const child of node.children) {
-      expandComponents(child, componentDefs, slotCss, defaults);
+      expandComponents(child, componentDefs, slotCss, defaults, slotIds);
     }
   }
 
@@ -2256,17 +2267,12 @@ function expandComponents(
      * was given. Instances written inside `def` itself are another matter — those are reached
      * below, through `preRenderComponentHtml`, with `node` as the first frame of the path.
      */
-    const slotContent =
-      Array.isArray(node.children) && node.children.length > 0
-        ? node.children
-            .map((c: JxElement | string) => {
-              if (slotCss && isNonNullObject(c)) {
-                collectStyles(c, slotCss.rules, slotCss.media, "", slotCss.counter, "jxs");
-              }
-              return renderStaticNode(c, {}, null);
-            })
-            .join("\n")
-        : null;
+    const renderSlotted = (c: StaticChild) => {
+      if (slotCss && isNonNullObject(c) && !Array.isArray(c)) {
+        collectStyles(c, slotCss.rules, slotCss.media, "", slotCss.counter, "jxs");
+      }
+      return renderStaticNode(c, {}, null);
+    };
 
     /*
      * In shadow mode the slotted children are NOT substituted into the prerendered markup: they
@@ -2282,9 +2288,28 @@ function expandComponents(
       componentDefs,
       defaults,
       path: [{ key: JSON.stringify(props ?? {}), tag: tagName }],
+      slotIds,
     };
-    const innerHTML = preRenderComponentHtml(def, props, shadow ? null : slotContent, context);
     const isStatic = isComponentFullyStatic(def);
+    const { children } = node;
+    /* Light mode places the children by slot name (spec.md §8.5). A live instance whose definition
+       has a slot is stamped and its groups bracketed, so its element recovers them on upgrade. */
+    const slotId =
+      !shadow && !isStatic && definitionHasSlot(def.children) ? nextSlotId(context) : null;
+    const slotContent = shadow
+      ? (Array.isArray(children) ? children : [])
+          .map((c: StaticChild) => renderSlotted(c))
+          .join("\n")
+      : null;
+    const innerHTML = preRenderComponentHtml(
+      def,
+      props,
+      shadow ? null : createSlotFill(children, {}, renderSlotted, slotId),
+      context,
+    );
+    if (slotId !== null) {
+      node.attributes = { ...node.attributes, [SLOT_ATTR]: String(slotId) };
+    }
 
     /*
      * A declarative shadow root: markup the parser materializes before any script runs, which the

package/src/targets/compile-client.ts

@@ -32,10 +32,12 @@ import {
   isRefObject,
   isSchemaOnly,
   isTemplateString,
+  LIT_PART_GUARD,
   PREFORMATTED_TAGS,
   pureSchemeOf,
   resolveStaticValue,
   srcImportBinding,
+  templateValueSource,
 } from "../shared.ts";
 import {
   bodyReturnsValue,
@@ -141,7 +143,7 @@ export function compileClient(
       // Naked primitive or array → reactive state
       if (isTemplateString(def)) {
         // Template string → computed on state so other computeds can ref it
-        computedEntries.push([key, `() => \`${def}\``]);
+        computedEntries.push([key, `() => ${templateValueSource(def)}`]);
       } else {
         stateEntries.push([key, def]);
       }
@@ -776,15 +778,19 @@ function emitLitMapTemplate(def: JxMutableNode | null | undefined, preformatted
     attrs += ` contenteditable="${def.contentEditable}"`;
   }
 
+  /* A row can hold a component instance, whose children its slots redistribute; a child part
+     there ends at a guard rather than at a sibling that may move (`LIT_PART_GUARD`). */
+  const guard = tag.includes("-") ? LIT_PART_GUARD : "";
+
   // Inner content
   let inner = "";
   if (def.textContent !== undefined) {
     const tc = String(def.textContent);
     if (isTemplateString(tc)) {
-      inner = mapRefsToLit(tc);
+      inner = `${mapRefsToLit(tc)}${guard}`;
     } else if (isRefObject(def.textContent)) {
       const path = refToBindingKey(def.textContent.$ref);
-      inner = `\${state.${path}}`;
+      inner = `\${state.${path}}${guard}`;
     } else {
       inner = escapeHtml(tc);
     }
@@ -792,9 +798,13 @@ function emitLitMapTemplate(def: JxMutableNode | null | undefined, preformatted
     inner = mapRefsToLit(String(def.innerHTML));
   } else if (isMappedArray(def.children)) {
     // Legacy whole-children repeater nested inside a map template.
-    inner = `\n      ${emitArrayHole(def.children)}\n    `;
+    inner = `\n      ${emitArrayHole(def.children)}${guard}\n    `;
   } else if (Array.isArray(def.children)) {
-    const rendered = def.children.map((c) => emitChildLit(c, inPre));
+    const rendered = def.children.map((c) => {
+      const text = emitChildLit(c, inPre);
+      const isPart = isMappedArray(c) || (isString(c) && isTemplateString(c));
+      return isPart ? `${text}${guard}` : text;
+    });
     inner = inPre ? rendered.join("") : `\n      ${rendered.join("\n      ")}\n    `;
   }
 

package/src/targets/compile-element.ts

@@ -10,7 +10,12 @@ import {
   ATTR_HELPER,
   attrHelperSource,
   booleanAttrValue,
+  definitionHasSlot,
+  LIT_PART_GUARD,
   PREFORMATTED_TAGS,
+  SLOT_CAPTURE_HELPER,
+  SLOT_DISTRIBUTE_HELPER,
+  slotHelperSource,
   collectStyles,
   compileExpression,
   compileOperandSource,
@@ -23,6 +28,7 @@ import {
   srcExportName,
   srcImportBinding,
   tagNameToClassName,
+  templateValueSource,
 } from "../shared.ts";
 import {
   bodyReturnsValue,
@@ -436,6 +442,13 @@ export function emitElementModule(
     `import { render, html, nothing } from 'lit-html';`,
     attrHelperSource(),
   );
+  /* Light-DOM slot distribution, by the rule the interpreter applies (spec.md §8.5): only a module
+     whose template draws a slot carries it, and a shadow component never does — its light children
+     ARE the slotted content, and a real `<slot>` distributes them. */
+  const hasSlot = shadow === null && definitionHasSlot(doc.children);
+  if (hasSlot) {
+    lines.push(slotHelperSource());
+  }
 
   /*
    * `$lazy` swaps the static import for a memoized dynamic one. A static import is a download, a
@@ -620,13 +633,14 @@ export function emitElementModule(
     );
   }
 
-  /* Emitted with the same `state.` → `this.state.` rewrite the inline-body path below uses, into a
-     template literal — which is what `evaluateTemplate` is, so the result is a string on both
-     sides rather than a string here and a raw value there. */
+  /* Emitted with the same `state.` → `this.state.` rewrite the inline-body path below uses. A
+     single expression keeps its own type and anything else is a template literal, exactly as the
+     runtime and the build-time scope evaluate it (spec.md §5.3), so a component reads the same
+     value hydrated as it did prerendered. */
   for (const [key, template] of templateEntries) {
     lines.push(
       "",
-      `    ${refAccessor("this.state", escapeToken(key))} = computed(() => \`${template.replaceAll("state.", "this.state.")}\`);`,
+      `    ${refAccessor("this.state", escapeToken(key))} = computed(() => ${templateValueSource(template.replaceAll("state.", "this.state."))});`,
     );
   }
 
@@ -795,19 +809,17 @@ export function emitElementModule(
       lines.push("    }));");
     }
   }
-  const hasSlot = treeHasSlot(doc.children);
   /*
-   * The slot emulation is a light-DOM construction: save the host's children, render over them,
-   * then splice them back where the literal `<slot>` element landed. Inside a shadow root that
+   * The slot emulation is a light-DOM construction: capture the host's children, render over them,
+   * then replace each literal `<slot>` with its group (spec.md §8.5). Inside a shadow root that
    * would be actively wrong — the light children ARE the slotted content and must stay in the
    * light tree, where a real `<slot>` distributes them. This is the single largest behavioural
-   * difference between the two modes, and the reason shadow cannot be the default.
+   * difference between the two modes, and the reason shadow cannot be the default. Captured before
+   * `data-jx-prerendered` goes and before the clear: a prerendered instance's children are its
+   * markup, and capture recovers what the prerender placed from its brackets instead.
    */
-  if (hasSlot && shadow === null) {
-    // Save light DOM children (slotted content) before clearing
-    lines.push(
-      "    const _slotted = Array.from(this.childNodes).filter(n => n.nodeType === 1 || (n.nodeType === 3 && n.textContent.trim()));",
-    );
+  if (hasSlot) {
+    lines.push(`    const _slotted = ${SLOT_CAPTURE_HELPER}(this);`);
   }
   lines.push(
     "    if (this.hasAttribute('data-jx-prerendered')) {",
@@ -848,15 +860,9 @@ export function emitElementModule(
       "    this.#effects.push(effect(() => render(this.template(), _root)));",
     );
   }
-  if (hasSlot && shadow === null) {
-    // Replace <slot> placeholder with saved slotted content
-    lines.push(
-      "    const _slot = this.querySelector('slot');",
-      "    if (_slot && _slotted.length > 0) {",
-      "      for (const n of _slotted) _slot.before(n);",
-      "      _slot.remove();",
-      "    }",
-    );
+  if (hasSlot) {
+    // Once, after the first render: a slot a later render draws stays literal (spec.md §8.5).
+    lines.push(`    ${SLOT_DISTRIBUTE_HELPER}(this, _slotted);`);
   }
   lines.push(
     // Lifecycle: onMount (spec §16.4) — same microtask contract as the runtime
@@ -936,27 +942,39 @@ function emitLitChildren(
   preformatted = false,
   inMap = false,
   scope: HoistScope | null = null,
+  /** The children are an instance's, so each child part ends at a guard rather than a sibling. */
+  guardParts = false,
 ) {
   if (!children) {
     return "";
   }
 
+  const guard = guardParts ? LIT_PART_GUARD : "";
+
   // Legacy whole-children repeater: the array IS the children slot.
   if (isMappedArray(children)) {
-    return emitMappedArray(children, indent);
+    return `${emitMappedArray(children, indent)}${guard}`;
   }
 
   if (!Array.isArray(children)) {
     return "";
   }
 
-  // Mixed children: elements/text plus array pseudo-elements expanded inline among siblings.
+  /* Mixed children: elements/text plus array pseudo-elements expanded inline among siblings. Among
+     an instance's children, a child that emits a lit child part — a binding, a repeater, a chosen
+     tag — is followed by a guard: distribution moves its neighbours, and a part that ended at one
+     would clear its new parent on the next update (`LIT_PART_GUARD`). */
   return children
-    .map((child) =>
-      isMappedArray(child)
-        ? emitMappedArray(child, indent)
-        : emitLitNode(child, preformatted ? "" : indent, preformatted, inMap, scope),
-    )
+    .map((child) => {
+      if (isMappedArray(child)) {
+        return `${emitMappedArray(child, indent)}${guard}`;
+      }
+      const text = emitLitNode(child, preformatted ? "" : indent, preformatted, inMap, scope);
+      const isPart =
+        (isString(child) && child.includes("${")) ||
+        (isNonNullObject(child) && isTagExpression(child.tagName));
+      return isPart ? `${text}${guard}` : text;
+    })
     .join(preformatted ? "" : "\n");
 }
 
@@ -1020,7 +1038,14 @@ function emitLitNode(
     const sharedPre = candidateTags.map((t) => preformatted || PREFORMATTED_TAGS.has(t));
     let innerRef: string | null = null;
     if (scope && sharedPre.every((p) => p === sharedPre[0])) {
-      const sharedInner = emitNodeInner(def, `${indent}  `, sharedPre[0] === true, inMap, scope);
+      const sharedInner = emitNodeInner(
+        def,
+        `${indent}  `,
+        sharedPre[0] === true,
+        inMap,
+        scope,
+        candidateTags.some((t) => t.includes("-")),
+      );
       if (sharedInner.trim() !== "") {
         innerRef = hoistSubtree(scope, sharedInner);
       }
@@ -1180,12 +1205,18 @@ ${no}
     return `${indent}<${tag}${attrsStr}\n${indent}>`;
   }
 
-  const inner = innerOverride ?? emitNodeInner(def, indent, inPre, inMap, scope);
+  // A custom element's children are distributed into its slots, so their parts need guards.
+  const inner = innerOverride ?? emitNodeInner(def, indent, inPre, inMap, scope, tag.includes("-"));
+
+  /* A `<slot>` is replaced after the first render, so no part may end at it or at its last child:
+     one guard before the slot (where an adjacent part ends) and one before `</slot>` (where a last
+     fallback binding ends, and which travels with the fallback when it is shown). */
+  const guard = tag === "slot" ? LIT_PART_GUARD : "";
 
   // Inside a <pre>, the newline before `>` would land in the element's own text.
   return inPre
-    ? `<${tag}${attrsStr}>${inner}</${tag}>`
-    : `${indent}<${tag}${attrsStr}\n${indent}>${inner}</${tag}>`;
+    ? `${guard}<${tag}${attrsStr}>${inner}${guard}</${tag}>`
+    : `${indent}${guard}<${tag}${attrsStr}\n${indent}>${inner}${guard}</${tag}>`;
 }
 
 /**
@@ -1207,6 +1238,8 @@ function emitNodeInner(
   inPre: boolean,
   inMap: boolean,
   scope: HoistScope | null,
+  /** `def` is a custom element, whose children are distributed: see `emitLitChildren`. */
+  guardParts = false,
 ): string {
   if (def.$switch) {
     const switchRef = isRef(def.$switch) ? def.$switch.$ref : def.$switch;
@@ -1232,15 +1265,18 @@ function emitNodeInner(
     return `\${{\n${caseEntries.join(",\n")}\n}[${switchExpr}]}`;
   }
   if (def.textContent !== undefined) {
-    return toLitTextContent(def.textContent);
+    const text = toLitTextContent(def.textContent);
+    const bound =
+      isRef(def.textContent) || (isString(def.textContent) && def.textContent.includes("${"));
+    return guardParts && bound ? `${text}${LIT_PART_GUARD}` : text;
   }
   if (def.innerHTML !== undefined) {
     return def.innerHTML;
   }
   if (def.children) {
     return inPre
-      ? emitLitChildren(def.children, def.style, "", true, inMap, scope)
-      : `\n${emitLitChildren(def.children, def.style, `${indent}  `, false, inMap, scope)}\n${indent}`;
+      ? emitLitChildren(def.children, def.style, "", true, inMap, scope, guardParts)
+      : `\n${emitLitChildren(def.children, def.style, `${indent}  `, false, inMap, scope, guardParts)}\n${indent}`;
   }
   return "";
 }
@@ -1538,27 +1574,3 @@ function emitStyleString(styleDef: JxStyle | null | undefined) {
 
   return parts.join("; ");
 }
-
-/**
- * Check if a children tree contains a `<slot>` element.
- *
- * @param {JxMutableNode["children"]} children
- * @returns {boolean}
- */
-function treeHasSlot(children: JxMutableNode["children"]): boolean {
-  if (!Array.isArray(children)) {
-    return false;
-  }
-  for (const child of children) {
-    if (!isNonNullObject(child)) {
-      continue;
-    }
-    if (child.tagName === "slot") {
-      return true;
-    }
-    if (treeHasSlot(child.children)) {
-      return true;
-    }
-  }
-  return false;
-}