@uniweb/build 0.11.2 → 0.11.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -51,14 +51,15 @@
     "jest": "^29.7.0"
   },
   "dependencies": {
+    "@citestyle/bibtex": "^1.0.0",
     "esbuild": "^0.21.0 || ^0.23.0 || ^0.24.0 || ^0.25.0 || ^0.27.0",
     "js-yaml": "^4.1.0",
     "sharp": "^0.33.2",
     "@uniweb/theming": "0.1.3"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "0.8.4",
-    "@uniweb/content-reader": "1.1.5",
+    "@uniweb/content-reader": "1.1.7",
+    "@uniweb/runtime": "0.8.6",
     "@uniweb/schemas": "0.2.1"
   },
   "peerDependencies": {
@@ -68,7 +69,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "0.7.3"
+    "@uniweb/core": "0.7.5"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/content/index.js

@@ -1,13 +1,38 @@
 /**
  * Clean Content Entry Point
  *
- * Exposes only collectSiteContent and its clean dependency chain
- * (Node builtins, js-yaml, @uniweb/theming). No Vite, sharp, or React.
- *
- * Used by Studio's sidecar (Bun-compiled binary) where those heavy
- * peer/native dependencies aren't available.
+ * Exposes content-collection helpers and their clean dependency chain
+ * (Node builtins, js-yaml, @uniweb/theming, @uniweb/core). No Vite,
+ * sharp, or React. Used by Studio's sidecar (Bun-compiled binary) and
+ * by @uniweb/unipress (CLI compile path) where those heavy peer/native
+ * dependencies aren't available.
  *
  * @module @uniweb/build/content
  */
 
 export { collectSiteContent } from '../site/content-collector.js'
+
+// Collections + fetch resolution. Pure functions on the clean dep
+// chain — re-exported here so headless callers (unipress, sidecars)
+// can resolve `collections:` declarations without importing
+// `@uniweb/build/site` (which pulls Vite via its plugin index).
+export {
+  processCollections,
+  writeCollectionFiles,
+  getCollectionLastModified,
+} from '../site/collection-processor.js'
+export {
+  parseFetchConfig,
+  executeFetch,
+  applyFilter,
+  applySort,
+  applyPostProcessing,
+  mergeDataIntoContent,
+  singularize,
+} from '../site/data-fetcher.js'
+
+// Cross-reference registry. Walks the document tree, finds every
+// block-level element with a {#id} attribute, registers the id with
+// its inferred kind + counter. Consumed by the framework's <Ref>
+// component to render `[#id]` cross-references.
+export { buildXrefRegistry } from '../site/xref-registry.js'

package/src/site/collection-processor.js

@@ -5,8 +5,15 @@
  * Collections are defined in site.yml and processed at build time.
  *
  * Features:
- * - Discovers markdown (.md), data (.yml/.yaml), and JSON (.json) files in collection folders
- * - Parses frontmatter for metadata (markdown), full YAML (data items), or JSON (data items)
+ * - Discovers markdown (.md), data (.yml/.yaml), JSON (.json), and BibTeX (.bib)
+ *   files in collection folders
+ * - Parses frontmatter for metadata (markdown), full YAML or JSON (data items),
+ *   or BibTeX → CSL-JSON (bibliography items)
+ * - Pure-data formats (YAML, JSON, BibTeX) accept either one record per file
+ *   (mapping at the top, slug from filename) or many records per file (array
+ *   at the top, each item carries its own slug; BibTeX always produces an
+ *   array, with the cite key as slug). Multiple files in the same folder
+ *   merge — the loader flattens one level after collecting them.
  * - Converts markdown body to ProseMirror JSON
  * - Supports filtering, sorting, and limiting
  * - Auto-generates excerpts and extracts first images (markdown items only)
@@ -29,6 +36,7 @@ import { readFile, readdir, stat, writeFile, mkdir, copyFile } from 'node:fs/pro
 import { join, basename, extname, dirname, relative, resolve } from 'node:path'
 import { existsSync } from 'node:fs'
 import yaml from 'js-yaml'
+import { parseBibtex } from '@citestyle/bibtex'
 import { applyFilter, applySort } from './data-fetcher.js'
 import { resolveAssetPath, walkContentAssets, isLocalAssetPath } from './assets.js'
 
@@ -393,21 +401,35 @@ async function processDataItemAssets(data, itemPath, siteRoot, collectionName, b
  * Process a single data item from a YAML file
  *
  * YAML items are pure data — no ProseMirror conversion, no body, no excerpt,
- * no image extraction, no lastModified. The output is slug + YAML fields.
+ * no image extraction, no lastModified.
+ *
+ * A YAML file containing a top-level array returns all items (single-file
+ * collection); each item must carry its own `slug`. A YAML file containing
+ * a mapping returns a single item with `slug` derived from the filename.
+ * Mirrors `processJsonItem` for parity across pure-data formats.
  *
  * @param {string} dir - Collection directory path
  * @param {string} filename - YAML filename (.yml or .yaml)
- * @returns {Promise<Object|null>} Processed item or null if unpublished
+ * @returns {Promise<Object|Array|null>} Processed item(s) or null if unpublished
  */
 async function processDataItem(dir, filename, siteRoot, collectionName, basePath) {
   const filepath = join(dir, filename)
   const raw = await readFile(filepath, 'utf-8')
-  const slug = basename(filename, extname(filename))
   const data = yaml.load(raw) || {}
 
-  // Skip unpublished items
-  if (data.published === false) return null
+  // Array → multiple items (single-file collection)
+  if (Array.isArray(data)) {
+    for (const item of data) {
+      if (item && typeof item === 'object') {
+        await processDataItemAssets(item, filepath, siteRoot, collectionName, basePath)
+      }
+    }
+    return data
+  }
 
+  // Mapping → single item
+  if (data.published === false) return null
+  const slug = basename(filename, extname(filename))
   const item = { slug, ...data }
   await processDataItemAssets(item, filepath, siteRoot, collectionName, basePath)
   return item
@@ -447,6 +469,29 @@ async function processJsonItem(dir, filename, siteRoot, collectionName, basePath
   return item
 }
 
+/**
+ * Process a single BibTeX file into an array of CSL-JSON bibliography items.
+ *
+ * Each `@entry{key, ...}` becomes one item. The BibTeX cite key is preserved
+ * as `id` (CSL-JSON convention) and copied to `slug` so per-record file
+ * emission and runtime lookups behave the same as for other formats.
+ *
+ * No asset processing — bibliography records reference URLs and DOIs, not
+ * local files.
+ *
+ * @param {string} dir - Collection directory path
+ * @param {string} filename - BibTeX filename (.bib)
+ * @returns {Promise<Array<Object>>} Array of CSL-JSON items, each with `slug`
+ */
+async function processBibtexItem(dir, filename) {
+  const filepath = join(dir, filename)
+  const raw = await readFile(filepath, 'utf-8')
+  const entries = parseBibtex(raw)
+  return entries
+    .filter(entry => entry && entry.id)
+    .map(entry => ({ slug: entry.id, ...entry }))
+}
+
 /**
  * Process a single content item from a markdown file
  *
@@ -512,12 +557,16 @@ async function collectItems(siteDir, config, collectionsBase, basePath) {
   const files = await readdir(collectionDir)
   const itemFiles = files.filter(f =>
     !f.startsWith('_') &&
-    (f.endsWith('.md') || f.endsWith('.yml') || f.endsWith('.yaml') || f.endsWith('.json'))
+    (f.endsWith('.md') || f.endsWith('.yml') || f.endsWith('.yaml') || f.endsWith('.json') || f.endsWith('.bib'))
   )
 
-  // Process all collection files (markdown → content items, YAML/JSON → data items)
+  // Process all collection files (markdown → content items, YAML/JSON → data
+  // items, BibTeX → CSL-JSON bibliography items).
   let items = await Promise.all(
     itemFiles.map(file => {
+      if (file.endsWith('.bib')) {
+        return processBibtexItem(collectionDir, file)
+      }
       if (file.endsWith('.json')) {
         return processJsonItem(collectionDir, file, siteDir, config.name, basePath)
       }
@@ -528,7 +577,8 @@ async function collectItems(siteDir, config, collectionsBase, basePath) {
     })
   )
 
-  // Flatten arrays from JSON files that contain multiple items
+  // Flatten one level: array-form YAML/JSON files and every .bib file
+  // contribute their entries individually.
   items = items.flat()
 
   // Filter out nulls (unpublished items)
@@ -673,7 +723,7 @@ export async function getCollectionLastModified(siteDir, config) {
   const files = await readdir(collectionDir)
   const itemFiles = files.filter(f =>
     !f.startsWith('_') &&
-    (f.endsWith('.md') || f.endsWith('.yml') || f.endsWith('.yaml') || f.endsWith('.json'))
+    (f.endsWith('.md') || f.endsWith('.yml') || f.endsWith('.yaml') || f.endsWith('.json') || f.endsWith('.bib'))
   )
 
   let lastModified = null

package/src/site/content-collector.js

@@ -181,13 +181,19 @@ async function readYamlFile(filePath) {
 /**
  * Extract inset references from a ProseMirror document.
  *
- * Walks top-level nodes for `inset_ref` (produced by content-reader
- * for `![alt](@ComponentName){params}` syntax). Each ref is removed from the
- * document and replaced with an `inset_placeholder` node carrying a
- * unique refId. The extracted refs are returned as an array.
+ * Walks the document recursively for `inset_ref` nodes (produced by
+ * content-reader for the `![alt](@ComponentName){params}` /
+ * `[text](@ComponentName){params}` / `[@key]{params}` forms). Each ref
+ * is removed and replaced in-place with an `inset_placeholder` node
+ * carrying a unique refId. The extracted refs are returned as an array.
+ *
+ * Inline insets (mid-paragraph) are kept as inline placeholders so the
+ * paragraph's text flow is preserved; block-level insets (own line)
+ * stay at the document root. Both share the same refId/getInset(refId)
+ * lookup machinery — only the position differs.
  *
  * @param {Object} doc - ProseMirror document (mutated in place)
- * @returns {Array} Array of { refId, type, params, description }
+ * @returns {Array} Array of { refId, type, params, description, embedKind }
  */
 function extractInsets(doc) {
   if (!doc?.content || !Array.isArray(doc.content)) return []
@@ -195,25 +201,34 @@ function extractInsets(doc) {
   const insets = []
   let refIndex = 0
 
-  for (let i = 0; i < doc.content.length; i++) {
-    const node = doc.content[i]
-    if (node.type === 'inset_ref') {
-      const { component, alt, ...params } = node.attrs || {}
-      const refId = `inset_${refIndex++}`
-      insets.push({
-        refId,
-        type: component,
-        params: Object.keys(params).length > 0 ? params : {},
-        title: alt || null,
-      })
-      // Replace in-place with placeholder
-      doc.content[i] = {
-        type: 'inset_placeholder',
-        attrs: { refId },
+  function visit(nodes) {
+    if (!Array.isArray(nodes)) return
+    for (let i = 0; i < nodes.length; i++) {
+      const node = nodes[i]
+      if (!node) continue
+      if (node.type === 'inset_ref') {
+        const { component, alt, embedKind, ...params } = node.attrs || {}
+        const refId = `inset_${refIndex++}`
+        insets.push({
+          refId,
+          type: component,
+          embedKind: embedKind || 'visual',
+          params: Object.keys(params).length > 0 ? params : {},
+          title: alt || null,
+        })
+        nodes[i] = {
+          type: 'inset_placeholder',
+          attrs: { refId, embedKind: embedKind || 'visual' },
+        }
+        continue
+      }
+      if (Array.isArray(node.content)) {
+        visit(node.content)
       }
     }
   }
 
+  visit(doc.content)
   return insets
 }
 

package/src/site/xref-registry.js

@@ -0,0 +1,153 @@
+/**
+ * Cross-reference registry — populated at content-collection time.
+ *
+ * Walks the parsed document tree to find every block-level element
+ * carrying a {#id} attribute, infers the element's kind from its node
+ * type, and records the entry with a per-kind counter. The result
+ * attaches to siteContent.xref and is consumed by the framework's
+ * <Ref> component to render `[#id]` cross-references.
+ *
+ * Built-in kinds:
+ *   - heading      → 'section'   (hierarchical counter: 1, 1.1, 1.1.1, 2, …)
+ *   - image        → 'figure'    (flat arabic counter)
+ *   - math_display → 'equation'  (flat arabic counter)
+ *   - table        → 'table'     (flat arabic counter)
+ *
+ * Foundation extensions: foundations may declare additional kinds via
+ * `foundation.xref.kinds`. The id-collection pass uses the foundation's
+ * declared `prefix` (e.g. `thm` → `theorem`) to classify ids that don't
+ * land on a built-in element type.
+ *
+ * The registry is per-document, not per-page: counters span the whole
+ * document so authors get consistent numbering even when their document
+ * spans multiple pages. (For page-local counter resets, foundations can
+ * declare `resetOn: 'chapter'` on a kind — applied during render, not
+ * here.)
+ *
+ * Output shape:
+ *   {
+ *     entries: {
+ *       <id>: {
+ *         id,            // the id itself
+ *         kind,          // 'figure' | 'equation' | 'section' | 'table' | <foundation-declared>
+ *         counter,       // number for flat kinds, dotted string for hierarchical
+ *         counterText,   // displayable counter ('3', '3.2')
+ *         sourcePath,    // page route the id was declared on (for back-refs)
+ *       },
+ *     },
+ *   }
+ */
+
+const KIND_BY_TYPE = {
+  heading: 'section',
+  image: 'figure',
+  math_display: 'equation',
+  table: 'table',
+}
+
+export function buildXrefRegistry(siteContent, options = {}) {
+  const { foundationKinds = {}, onWarn = (msg) => console.warn(msg) } = options
+
+  const entries = {}
+  const flatCounters = {}     // kind -> next integer counter (figure, equation, table, foundation-declared kinds)
+  const sectionStack = []     // hierarchical counters per heading level
+
+  // Index foundation prefixes for id-prefix inference.
+  const prefixToKind = {}
+  for (const [kind, meta] of Object.entries(foundationKinds)) {
+    if (meta?.prefix) prefixToKind[meta.prefix] = kind
+  }
+
+  function nextFlat(kind) {
+    flatCounters[kind] = (flatCounters[kind] || 0) + 1
+    return flatCounters[kind]
+  }
+
+  // Track the shallowest heading depth seen — chapter content commonly
+  // starts at h2 (chapter title is rendered separately as h1 by the
+  // foundation), so the first encountered level becomes the document's
+  // top counter level. Re-anchoring: if a later heading appears at a
+  // shallower level than `topLevel`, drop topLevel down to match.
+  let topLevel = null
+
+  function nextHierarchical(level) {
+    if (topLevel == null || level < topLevel) topLevel = level
+    const depth = level - topLevel + 1  // 1-based depth from the document's top level
+
+    // Trim deeper levels when surfacing back to a shallower heading.
+    while (sectionStack.length >= depth) sectionStack.pop()
+    while (sectionStack.length < depth - 1) sectionStack.push(1) // implicit parents start at 1
+    sectionStack.push((sectionStack[depth - 1] || 0) + 1)
+    sectionStack.length = depth
+    return sectionStack.slice().join('.')
+  }
+
+  function inferKind(node) {
+    // 1. Node-type-based: built-ins.
+    const builtin = KIND_BY_TYPE[node.type]
+    if (builtin) return builtin
+    // 2. Explicit kind attribute on the node ({.kind} or kind=…).
+    if (node.attrs?.kind && (KIND_BY_TYPE[node.attrs.kind] || foundationKinds[node.attrs.kind])) {
+      return node.attrs.kind
+    }
+    // 3. Foundation-declared prefix on the id.
+    const id = node.attrs?.id
+    if (id && id.includes('-')) {
+      const prefix = id.slice(0, id.indexOf('-'))
+      if (prefixToKind[prefix]) return prefixToKind[prefix]
+    }
+    return null
+  }
+
+  function visit(node, sourcePath) {
+    if (!node || typeof node !== 'object') return
+
+    // Headings get a hierarchical counter regardless of whether they
+    // carry an id — the {#id} just labels them; the counter itself is
+    // assigned by tree position.
+    let counter = null
+    let counterText = null
+    if (node.type === 'heading') {
+      const level = Math.max(1, Math.min(6, node.attrs?.level || 1))
+      counterText = nextHierarchical(level)
+      counter = counterText
+    }
+
+    const id = node.attrs?.id
+    if (id) {
+      const kind = inferKind(node)
+      if (!kind) {
+        onWarn(`[xref] {#${id}} on unrecognized element type "${node.type}" — ignored`)
+      } else if (entries[id]) {
+        onWarn(`[xref] duplicate id "${id}" — keeping first registration`)
+      } else {
+        if (counter == null) {
+          counter = nextFlat(kind)
+          counterText = String(counter)
+        }
+        entries[id] = { id, kind, counter, counterText, sourcePath: sourcePath || '' }
+      }
+    } else if (node.type === 'heading') {
+      // Heading without an id still advances the counter — but we don't
+      // register it (no way to reference it). The advance is needed so
+      // that the *next* labeled heading gets the right hierarchical
+      // counter.
+      // counter already computed above; just no entry.
+    }
+
+    if (Array.isArray(node.content)) {
+      for (const child of node.content) visit(child, sourcePath)
+    }
+  }
+
+  for (const page of siteContent.pages || []) {
+    for (const section of page.sections || []) {
+      const content = section.content
+      if (content?.type === 'doc' && Array.isArray(content.content)) {
+        for (const child of content.content) visit(child, page.route)
+      }
+    }
+  }
+
+  return { entries }
+}