@uniweb/core 0.7.30 → 0.7.32

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@uniweb/core",
-  "version": "0.7.30",
+  "version": "0.7.32",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {
     ".": "./src/index.js",
-    "./locale-config": "./src/locale-config.js"
+    "./locale-config": "./src/locale-config.js",
+    "./section-id": "./src/section-id.js"
   },
   "files": [
     "src"
@@ -31,8 +32,8 @@
     "vitest": "^4.1.7"
   },
   "dependencies": {
-    "@uniweb/semantic-parser": "1.1.19",
-    "@uniweb/theming": "0.1.14"
+    "@uniweb/theming": "0.1.14",
+    "@uniweb/semantic-parser": "1.1.20"
   },
   "scripts": {
     "test": "vitest run"

package/src/block.js

@@ -8,6 +8,70 @@
 import { parseContent as parseSemanticContent } from '@uniweb/semantic-parser'
 import { normalizeTokenValue } from '@uniweb/theming'
 
+/**
+ * Lift container fences out of a content document.
+ *
+ * A ` ```@Component{params} ` fence parses to an `inset_block` node carrying a
+ * body of real block content. This rewrites each one to the `inset_placeholder`
+ * a leaf inset leaves behind, so a container resolves through exactly the same
+ * path: `getInset(refId)` → a Block → the foundation's component. Kit and the
+ * SSR renderer already handle placeholders, so neither needs to know containers
+ * exist.
+ *
+ * PURE with respect to the input. `blockData.content` is shared with the sync /
+ * pull machinery, which must keep seeing `inset_block` — that is the canonical
+ * stored shape. Nodes on the path to a container are cloned; everything else is
+ * passed through by reference, so a document with no containers costs one array
+ * walk and allocates nothing.
+ *
+ * Containers are NOT recursed into here. A container's body becomes its child
+ * Block's content, and that Block's constructor lifts its own containers — so
+ * nesting resolves one level at a time, each at the level that owns it.
+ *
+ * @param {Object} content - ProseMirror document (never mutated)
+ * @returns {{ content: Object, refs: Array<{refId, type, params, content}> }}
+ */
+function liftContainers(content) {
+  if (!content || !Array.isArray(content.content)) return { content, refs: [] }
+
+  const refs = []
+
+  const visit = (nodes) => {
+    let changed = false
+    const out = nodes.map((node) => {
+      if (!node) return node
+
+      if (node.type === 'inset_block') {
+        const { component, ...params } = node.attrs || {}
+        const refId = `container_${refs.length}`
+        refs.push({
+          refId,
+          type: component,
+          params,
+          content: { type: 'doc', content: node.content || [] },
+        })
+        changed = true
+        return { type: 'inset_placeholder', attrs: { refId, embedKind: 'block' } }
+      }
+
+      if (Array.isArray(node.content)) {
+        const inner = visit(node.content)
+        if (inner !== node.content) {
+          changed = true
+          return { ...node, content: inner }
+        }
+      }
+      return node
+    })
+    return changed ? out : nodes
+  }
+
+  const next = visit(content.content)
+  return next === content.content
+    ? { content, refs }
+    : { content: { ...content, content: next }, refs }
+}
+
 export default class Block {
   constructor(blockData, id, page) {
     this.id = id
@@ -22,8 +86,17 @@ export default class Block {
     // 1. Raw ProseMirror content (from content collection)
     // 2. Pre-parsed content with main/items structure
     // For now, store raw and parse on demand
-    this.rawContent = blockData.content || {}
-    this.parsedContent = this.parseContent(blockData.content)
+    //
+    // Container fences (```@Component around a body) arrive as `inset_block`
+    // nodes and are lifted out HERE, into the same placeholder + refId shape
+    // the build gives leaf insets. Doing it at render-graph construction
+    // rather than at build time is deliberate: `inset_block` is the canonical
+    // STORED shape, so the content that syncs and round-trips must keep
+    // carrying it. `blockData.content` is left untouched — the lift produces a
+    // new tree and only this Block's view of it changes.
+    const lifted = liftContainers(blockData.content)
+    this.rawContent = lifted.content || {}
+    this.parsedContent = this.parseContent(lifted.content)
 
     // Merge fetched data from prerender (if present)
     // Prerender stores fetched data in blockData.parsedContent.data
@@ -114,6 +187,30 @@ export default class Block {
       }
     }
 
+    // Containers, appended AFTER the leaf insets so `block.insets[0]` keeps
+    // meaning what it meant to every foundation already using <Visual>.
+    // Unlike a leaf inset, a container's body becomes the child Block's
+    // content, so the foundation's component receives a fully parsed
+    // `content` — title, paragraphs, items, sequence — exactly as a section
+    // does. Nested containers resolve for free: the child Block runs this
+    // same constructor over its own body.
+    for (let i = 0; i < lifted.refs.length; i++) {
+      const ref = lifted.refs[i]
+      this.insets.push(
+        new Block(
+          {
+            type: ref.type,
+            params: ref.params || {},
+            content: ref.content,
+            stableId: ref.refId,
+            refId: ref.refId,
+          },
+          `${id}_container_${i}`,
+          this.page
+        )
+      )
+    }
+
     // Fetch configuration (from section frontmatter)
     // Supports local files (path) or remote URLs (url)
     this.fetch = blockData.fetch || null

package/src/section-id.js

@@ -0,0 +1,67 @@
+/**
+ * The DOM id of a rendered section — one rule, shared by everything that
+ * needs to name a section.
+ *
+ * A section's id is written by the renderer and read by anything that links
+ * to a section: the search index's anchors, a table of contents, a deep link
+ * someone pastes. Those only agree if they derive the id the same way, and
+ * they cannot check each other — a mismatch produces no error anywhere. The
+ * link simply lands on the page and does not scroll, and if the target is the
+ * page you are already on, nothing visibly happens at all.
+ *
+ * That is not hypothetical. The renderers moved from the positional `id` to
+ * `stableId` (so an id survives reordering) and the search extractor was not
+ * updated, so it kept emitting `Section1` while the DOM said
+ * `section-what-is-uniweb`. Every section-level search result on every site
+ * pointed at a fragment that did not exist, and no test failed.
+ *
+ * So this is deliberately the ONLY place the rule is written down, and it
+ * captures both halves — which identity to use AND how to spell it. A helper
+ * that only formatted a value the caller picked would have prevented the
+ * spelling half of that bug and none of the identity half.
+ *
+ * **Zero imports, and it must stay that way.** `@uniweb/projections` consumes
+ * this through the leaf subpath `@uniweb/core/section-id` because its
+ * environment contract forbids the bare `@uniweb/core` entry (that pulls in
+ * semantic-parser and theming). Adding an import here would break that
+ * package's `tests/environment.test.js`.
+ */
+
+/** Prefix for every section wrapper id. */
+const PREFIX = 'section-'
+
+/**
+ * The DOM id for a section, from either a Block or the raw section data.
+ *
+ * Accepts both shapes on purpose: the runtime holds `Block` instances while
+ * build-time consumers hold plain objects off the wire. Both carry the same
+ * two fields, so one function serves both rather than each growing its own.
+ *
+ * `stableId` is preferred because it is derived from the section's filename
+ * (or an authored `id:`) and therefore survives reordering; the positional
+ * `id` is the fallback for content that has no stable identity.
+ *
+ * @param {{stableId?: string, id?: string|number}} section - A Block, or a
+ *   section object from site content.
+ * @returns {string} e.g. `section-hero`. Returns `section-unknown` rather
+ *   than an id ending in `undefined` when a section carries no identity at
+ *   all — a wrong-but-obvious anchor beats a malformed one.
+ */
+export function sectionDomId(section) {
+  if (!section) return `${PREFIX}unknown`
+  const id = section.stableId || section.id
+  return `${PREFIX}${id === undefined || id === null || id === '' ? 'unknown' : id}`
+}
+
+/**
+ * The same id as a URL fragment, for building a link to a section.
+ *
+ * Exists so a caller composing an href never has to remember whether the
+ * `#` is already included — the concatenation is the part people get wrong.
+ *
+ * @param {{stableId?: string, id?: string|number}} section
+ * @returns {string} e.g. `#section-hero`
+ */
+export function sectionHash(section) {
+  return `#${sectionDomId(section)}`
+}