@uniweb/kit 0.9.5 → 0.9.7

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "description": "Standard component library for Uniweb foundations",
   "type": "module",
   "exports": {
     ".": "./src/index.js",
+    "./xref": "./src/xref/index.js",
     "./theme-tokens.css": "./src/theme-tokens.css"
   },
   "files": [
@@ -38,7 +39,7 @@
     "fuse.js": "^7.0.0",
     "shiki": "^3.0.0",
     "tailwind-merge": "^2.6.0",
-    "@uniweb/core": "0.7.5"
+    "@uniweb/core": "0.7.7"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

package/src/xref/Ref.jsx

@@ -0,0 +1,142 @@
+/**
+ * Cross-reference renderer.
+ *
+ * Foundations that want `[#id]` cross-reference rendering import this
+ * component from `@uniweb/kit/xref` and register it in their
+ * foundation.js's `defaultInsets` map:
+ *
+ *   import { Ref } from '@uniweb/kit/xref'
+ *   export default {
+ *     defaultInsets: { Ref },
+ *     xref: { kinds: { ... } },
+ *     // ...
+ *   }
+ *
+ * Content-reader compiles `[#id]` markdown markers to
+ * `inset_ref { component: 'Ref', key: <id> }` regardless of foundation
+ * choice; the runtime's inset resolver looks up the component name in
+ * the foundation's defaultInsets to find this renderer.
+ *
+ * Resolution flow at render time:
+ *   1. Read `getXrefRegistry(block.website)` — the per-document
+ *      registry the runtime populated from `{#id}` attributes when the
+ *      foundation declared `xref:`.
+ *   2. Pick the active xref-style preset (foundation default + document
+ *      override) and the kind metadata for the registered entry.
+ *   3. Render via the style's label + counter + locator.
+ *
+ * Multi-ref clusters (`[#a;#b]`) split on `;` and render same-kind
+ * groups using the style's `labelPlural`. Mixed-kind clusters fall
+ * back to comma-separated singular rendering with a console warning.
+ *
+ * Missing ids render `[?<id-with-typo>]` so the failing key is visible
+ * in the output — easier to debug than the bare `[?]` we use for
+ * missing cite keys.
+ */
+
+import React from 'react'
+import { getXrefRegistry } from './registry.js'
+import { resolveXrefStyle, getKindMeta } from './styles.js'
+
+function splitKeys(raw) {
+    return String(raw || '')
+        .split(';')
+        .map((k) => k.trim().replace(/^#/, ''))
+        .filter(Boolean)
+}
+
+function formatLocator(params) {
+    const { page, locator, label = 'page' } = params || {}
+    const value = page || locator
+    if (!value) return ''
+    const labels = {
+        page: 'p.',
+        chapter: 'chap.',
+        section: '§',
+        paragraph: '¶',
+    }
+    const lab = labels[label] || `${label}.`
+    return ` (${lab} ${value})`
+}
+
+function renderEntry(entry, kindMeta) {
+    const label = kindMeta?.label || ''
+    const sep = kindMeta?.sep ?? ' '
+    const counter = entry.counterText
+    return label ? `${label}${sep}${counter}` : counter
+}
+
+function renderGroupSameKind(entries, kindMeta) {
+    if (entries.length === 1) {
+        return renderEntry(entries[0], kindMeta)
+    }
+    const label = kindMeta?.labelPlural || kindMeta?.label || ''
+    const sep = kindMeta?.sep ?? ' '
+    const counters = entries.map((e) => e.counterText)
+    let body
+    if (counters.length === 2) {
+        body = counters.join(' and ')
+    } else {
+        body = counters.slice(0, -1).join(', ') + ', and ' + counters[counters.length - 1]
+    }
+    return label ? `${label}${sep}${body}` : body
+}
+
+export function Ref({ params, block }) {
+    const website = block?.website
+    const registry = getXrefRegistry(website)
+    const entries = registry?.entries || {}
+    const styleName = website?.config?.book?.xrefStyle || 'humanities'
+    const style = resolveXrefStyle(styleName, website?.config)
+
+    const ids = splitKeys(params?.key)
+    if (ids.length === 0) {
+        return <span className="xref xref--missing" title="No id">[?]</span>
+    }
+
+    const resolved = ids.map((id) => {
+        const entry = entries[id]
+        return entry ? { id, entry, kindMeta: getKindMeta(style, entry.kind) } : { id, missing: true }
+    })
+
+    if (resolved.length === 1 && resolved[0].missing) {
+        return (
+            <span className="xref xref--missing" title={`Missing label: ${resolved[0].id}`}>
+                [?{resolved[0].id}]
+            </span>
+        )
+    }
+
+    const allKinds = resolved.filter((r) => !r.missing).map((r) => r.entry.kind)
+    const sameKind = allKinds.every((k) => k === allKinds[0])
+
+    const locator = formatLocator(params)
+
+    if (!sameKind) {
+        if (typeof console !== 'undefined') {
+            // eslint-disable-next-line no-console
+            console.warn(
+                `[xref] mixed-kind cluster (${[...new Set(allKinds)].join(', ')}) — falling back to comma-separated rendering`,
+            )
+        }
+        const parts = resolved.map((r) =>
+            r.missing ? `[?${r.id}]` : renderEntry(r.entry, r.kindMeta),
+        )
+        return <span className="xref">{parts.join(', ')}{locator}</span>
+    }
+
+    const onlyResolved = resolved.filter((r) => !r.missing)
+    const text = onlyResolved.length > 0
+        ? renderGroupSameKind(
+              onlyResolved.map((r) => r.entry),
+              onlyResolved[0].kindMeta,
+          )
+        : ''
+
+    const missingTail = resolved.filter((r) => r.missing).map((r) => `[?${r.id}]`).join(', ')
+    const body = [text, missingTail].filter(Boolean).join(', ')
+
+    return <span className="xref">{body}{locator}</span>
+}
+
+export default Ref

package/src/xref/index.js

@@ -0,0 +1,27 @@
+/**
+ * @uniweb/kit/xref — cross-reference machinery for foundations that
+ * support `[#id]` markdown markers.
+ *
+ * Foundations using cross-references (academic, documentation, long-form)
+ * import:
+ *   - `Ref` to register in `defaultInsets` so content-reader's
+ *     `inset_ref { component: 'Ref' }` markers resolve.
+ *   - `buildXrefRegistry` if they want to trigger registry construction
+ *     manually (the runtime does it automatically when foundation
+ *     declares `xref:`).
+ *   - `getXrefRegistry` to read the registry from list sections (e.g.
+ *     ListOfFigures).
+ *
+ * Foundations that do NOT use cross-references never import this
+ * subpath; kit's tree-shaking strips the entire xref module from their
+ * bundle.
+ */
+
+export { buildXrefRegistry, getXrefRegistry } from './registry.js'
+export {
+    XREF_STYLES,
+    DEFAULT_XREF_STYLE,
+    resolveXrefStyle,
+    getKindMeta,
+} from './styles.js'
+export { Ref, default as RefDefault } from './Ref.jsx'

package/src/xref/registry.js

@@ -0,0 +1,217 @@
+/**
+ * Cross-reference registry — per-website lookup table from `{#id}` to
+ * counter / kind / metadata.
+ *
+ * The walker visits the parsed document tree (siteContent.pages[].
+ * sections[].content) once, finds 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 registry is consumed
+ * by:
+ *   - The framework's <Ref> component to render `[#id]` cross-references
+ *     as "Figure 3" / "§3.2" / etc.
+ *   - List sections (foundation-side: ListOfFigures / ListOfTables /
+ *     TableOfContents) to enumerate captioned figures/tables/headings.
+ *   - Press LaTeX adapters' \autoref helpers to filter unresolved ids.
+ *
+ * Built-in kinds:
+ *   - heading      → 'section'   (hierarchical: 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 that need additional kinds (e.g.
+ * theorem, lemma, definition for an academic foundation) declare them
+ * via `foundation.xref.kinds`. The id-collection pass uses each kind's
+ * `prefix` field (e.g. `thm` → `theorem`) to classify ids that don't
+ * land on a built-in element type.
+ *
+ * Storage: a WeakMap keyed by Website. The registry is NOT attached as
+ * a property on the Website object — keeping the persistent vanilla-JS
+ * object graph free of feature-specific properties is a deliberate
+ * Uniweb convention. Same pattern as cite-registry.js (book foundation)
+ * and Press's DocumentProvider registration store.
+ *
+ * Lifecycle: built once per website at runtime initialization (see
+ * runtime/src/setup.js / ssr-renderer.js's initPrerender — they detect
+ * `foundation.xref` and trigger the build). Consumers read it via
+ * `getXrefRegistry(website)`. When the website becomes unreachable
+ * (page navigation, editor preview swap), the WeakMap entry is GC-
+ * eligible automatically.
+ *
+ * Output shape per entry:
+ *   {
+ *     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)
+ *     caption,       // (figures, tables) caption attr, when set
+ *     text,          // (sections) heading's plain text content
+ *     latex,         // (equations) latex source for the equation
+ *   }
+ *
+ * `caption`, `text`, and `latex` are populated only for the elements
+ * that carry them — undefined on other kinds.
+ */
+
+const KIND_BY_TYPE = {
+    heading: 'section',
+    image: 'figure',
+    math_display: 'equation',
+    table: 'table',
+}
+
+/**
+ * Per-website registry storage. Keyed by the Website instance (or any
+ * object — the WeakMap doesn't enforce a type). Entries are GC-eligible
+ * once the website becomes unreachable.
+ */
+const REGISTRIES = new WeakMap()
+
+/**
+ * Walk the website's parsed content tree to build the registry. Stores
+ * the result keyed by the website instance.
+ *
+ * @param {Object} website - The Website instance the registry belongs
+ *   to. Used as the WeakMap key. Should expose its parsed content
+ *   either at `website.rawContent` or `website.siteContent` depending
+ *   on how the runtime exposes it; the walker accepts both.
+ * @param {Object} [options]
+ * @param {Object} [options.foundationKinds] - Map of kind → metadata
+ *   the foundation declared via `foundation.xref.kinds`. Drives id-
+ *   prefix classification for non-built-in kinds (e.g. thm-foo →
+ *   theorem) and is referenced when an explicit `kind` attribute on a
+ *   node points at a foundation-declared kind.
+ * @param {Function} [options.onWarn] - Per-warning callback. Default
+ *   logs to console.
+ * @returns {{entries: Object}} The built registry.
+ */
+export function buildXrefRegistry(website, options = {}) {
+    const { foundationKinds = {}, onWarn = (msg) => console.warn(msg) } = options
+
+    const entries = {}
+    const flatCounters = {}
+    const sectionStack = []
+
+    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]
+    }
+
+    let topLevel = null
+
+    function nextHierarchical(level) {
+        if (topLevel == null || level < topLevel) topLevel = level
+        const depth = level - topLevel + 1
+        while (sectionStack.length >= depth) sectionStack.pop()
+        while (sectionStack.length < depth - 1) sectionStack.push(1)
+        sectionStack.push((sectionStack[depth - 1] || 0) + 1)
+        sectionStack.length = depth
+        return sectionStack.slice().join('.')
+    }
+
+    function inferKind(el) {
+        // Built-in: element type matches a registered kind.
+        const builtin = KIND_BY_TYPE[el.type]
+        if (builtin) return builtin
+        // Explicit kind attribute on the element.
+        if (el.attrs?.kind && (KIND_BY_TYPE[el.attrs.kind] || foundationKinds[el.attrs.kind])) {
+            return el.attrs.kind
+        }
+        // Foundation-declared prefix on the id.
+        const id = readId(el)
+        if (id && id.includes('-')) {
+            const prefix = id.slice(0, id.indexOf('-'))
+            if (prefixToKind[prefix]) return prefixToKind[prefix]
+        }
+        return null
+    }
+
+    // Sequence elements expose `id` differently per element type. Most
+    // (heading, image, table) carry it under `attrs`; math_display
+    // promotes it to a top-level field (per @uniweb/semantic-parser's
+    // sequence builder). Read both.
+    function readId(el) {
+        return el.attrs?.id ?? el.id ?? null
+    }
+
+    function visit(el, sourcePath) {
+        let counter = null
+        let counterText = null
+        if (el.type === 'heading') {
+            const level = Math.max(1, Math.min(6, el.level || el.attrs?.level || 1))
+            counterText = nextHierarchical(level)
+            counter = counterText
+        }
+
+        const id = readId(el)
+        if (!id) return
+
+        const kind = inferKind(el)
+        if (!kind) {
+            onWarn(`[xref] {#${id}} on unrecognized element type "${el.type}" — ignored`)
+            return
+        }
+        if (entries[id]) {
+            onWarn(`[xref] duplicate id "${id}" — keeping first registration`)
+            return
+        }
+        if (counter == null) {
+            counter = nextFlat(kind)
+            counterText = String(counter)
+        }
+        const entry = { id, kind, counter, counterText, sourcePath: sourcePath || '' }
+        const caption = el.attrs?.caption
+        if ((kind === 'figure' || kind === 'table') && caption) {
+            entry.caption = String(caption)
+        }
+        if (el.type === 'heading' && el.text) {
+            entry.text = String(el.text)
+        }
+        if (el.type === 'math_display' && el.latex) {
+            entry.latex = String(el.latex)
+        }
+        entries[id] = entry
+    }
+
+    // Walk the Website's object graph: pages → bodyBlocks. Each Block's
+    // `parsedContent.sequence` is a flat document-order array of
+    // semantic elements (heading, paragraph, image, list, blockquote,
+    // codeBlock, table, math_display, divider, …). Iterating the
+    // sequence is enough — the registry's id-bearing kinds (heading,
+    // image, math_display, table) all live at sequence level.
+    //
+    // Website.pages, Page.bodyBlocks, and Block.parsedContent.sequence
+    // are framework invariants — always arrays. No defensive guards.
+    for (const page of website.pages) {
+        for (const block of page.bodyBlocks) {
+            for (const el of block.parsedContent.sequence) {
+                visit(el, page.route)
+            }
+        }
+    }
+
+    const registry = { entries }
+    REGISTRIES.set(website, registry)
+    return registry
+}
+
+/**
+ * Read the registry previously built for a website. Returns null if no
+ * registry was built (e.g. the foundation didn't declare `xref` so
+ * runtime initialization didn't trigger `buildXrefRegistry`).
+ *
+ * Consumers (Ref renderer, ListOfFigures section, press LaTeX inset
+ * formatters) handle the null case gracefully — typically by treating
+ * it as an empty entries map, which renders cross-refs as "[?<id>]"
+ * placeholders.
+ */
+export function getXrefRegistry(website) {
+    if (!website || typeof website !== 'object') return null
+    return REGISTRIES.get(website) || null
+}

package/src/xref/styles.js

@@ -0,0 +1,103 @@
+/**
+ * Cross-reference style catalog.
+ *
+ * Cross-references are framework-managed (parallel to citestyle's nine
+ * citation styles, but framework-internal because there's no CSL-for-
+ * xrefs standard). Foundations pick a preset; documents may override
+ * per-kind.
+ *
+ * Each preset is a map from kind name to:
+ *   {
+ *     label,         // singular label, e.g. "Figure"
+ *     labelPlural,   // plural label, e.g. "Figures"
+ *     counter,       // 'arabic' | 'hierarchical' | null (no counter)
+ *     sep,           // separator between label and counter ("" | " ")
+ *   }
+ *
+ * The catalog ships four presets:
+ *   - humanities   (default — "Figure 3", "§3.2", "Equation 1")
+ *   - engineering  ("Fig. 3", "Sec. 3.2", "Eq. 1")
+ *   - german       ("Abb. 3", "Abschn. 3.2", "Gl. 1")
+ *   - plain        (counters only — "3", "3.2", "1")
+ *
+ * Foundations override the preset by declaring `xref.kinds` in
+ * foundation.js (additive: new kinds and overrides for existing kinds).
+ * Documents override per-kind via `book.xref.<kind>:` in document.yml.
+ */
+
+const HUMANITIES = {
+    figure:   { label: 'Figure',   labelPlural: 'Figures',   counter: 'arabic', sep: ' ' },
+    equation: { label: 'Equation', labelPlural: 'Equations', counter: 'arabic', sep: ' ' },
+    section:  { label: '§',        labelPlural: '§§',        counter: 'hierarchical', sep: '' },
+    table:    { label: 'Table',    labelPlural: 'Tables',    counter: 'arabic', sep: ' ' },
+}
+
+const ENGINEERING = {
+    figure:   { label: 'Fig.',     labelPlural: 'Figs.',     counter: 'arabic', sep: ' ' },
+    equation: { label: 'Eq.',      labelPlural: 'Eqs.',      counter: 'arabic', sep: ' ' },
+    section:  { label: 'Sec.',     labelPlural: 'Secs.',     counter: 'hierarchical', sep: ' ' },
+    table:    { label: 'Tab.',     labelPlural: 'Tabs.',     counter: 'arabic', sep: ' ' },
+}
+
+const GERMAN = {
+    figure:   { label: 'Abb.',     labelPlural: 'Abb.',      counter: 'arabic', sep: ' ' },
+    equation: { label: 'Gl.',      labelPlural: 'Gl.',       counter: 'arabic', sep: ' ' },
+    section:  { label: 'Abschn.',  labelPlural: 'Abschn.',   counter: 'hierarchical', sep: ' ' },
+    table:    { label: 'Tab.',     labelPlural: 'Tab.',      counter: 'arabic', sep: ' ' },
+}
+
+const PLAIN = {
+    figure:   { label: '',         labelPlural: '',          counter: 'arabic', sep: '' },
+    equation: { label: '',         labelPlural: '',          counter: 'arabic', sep: '' },
+    section:  { label: '',         labelPlural: '',          counter: 'hierarchical', sep: '' },
+    table:    { label: '',         labelPlural: '',          counter: 'arabic', sep: '' },
+}
+
+export const XREF_STYLES = {
+    humanities: HUMANITIES,
+    engineering: ENGINEERING,
+    german: GERMAN,
+    plain: PLAIN,
+}
+
+export const DEFAULT_XREF_STYLE = 'humanities'
+
+/**
+ * Resolve the active xref-style for a document. Reads:
+ *   - presetName (book.xrefStyle: in document config).
+ *   - `book.xref.<kind>:` per-kind overrides on top of the preset.
+ *   - Foundation-declared kinds (`foundation.xref.kinds`) extend the
+ *     preset with whatever the foundation provides.
+ *
+ * Returns a plain map keyed by kind name; per-kind values are merged
+ * objects (preset + foundation extensions + document overrides).
+ */
+export function resolveXrefStyle(presetName, config) {
+    const preset = XREF_STYLES[presetName] || XREF_STYLES[DEFAULT_XREF_STYLE]
+    const merged = { ...preset }
+
+    // Foundation extensions: kinds declared by the foundation (e.g.
+    // theorem, lemma, proof for a math foundation).
+    const foundationKinds = globalThis.uniweb?.foundationConfig?.xref?.kinds
+    if (foundationKinds && typeof foundationKinds === 'object') {
+        for (const [kind, meta] of Object.entries(foundationKinds)) {
+            merged[kind] = { ...merged[kind], ...meta }
+        }
+    }
+
+    // Document overrides: `book.xref.<kind>:` granular tweaks.
+    const docOverrides = config?.book?.xref || config?.xref || null
+    if (docOverrides && typeof docOverrides === 'object') {
+        for (const [kind, meta] of Object.entries(docOverrides)) {
+            if (meta && typeof meta === 'object') {
+                merged[kind] = { ...merged[kind], ...meta }
+            }
+        }
+    }
+
+    return merged
+}
+
+export function getKindMeta(style, kind) {
+    return style?.[kind] || null
+}