@uniweb/build 0.14.12 → 0.14.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.14.12",
+  "version": "0.14.14",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -59,22 +59,22 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.33.2",
     "yaml": "^2.5.0",
-    "@uniweb/theming": "0.1.3",
-    "@uniweb/content-writer": "0.2.5"
+    "@uniweb/content-writer": "0.2.5",
+    "@uniweb/theming": "0.1.4"
   },
   "optionalDependencies": {
     "@uniweb/content-reader": "1.1.12",
-    "@uniweb/schemas": "0.2.3",
-    "@uniweb/runtime": "0.8.17"
+    "@uniweb/runtime": "0.8.18",
+    "@uniweb/schemas": "0.2.3"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
-    "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "0.7.12"
+    "@uniweb/core": "0.7.13"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/uwx/collections-project.js

@@ -6,8 +6,9 @@
 //
 // Identity & placement. A record's on-disk home is `(collection, slug)`:
 //   - `slug` and `collection` come from the FOLDER document — each ref leaf is
-//     `{ entry: <uuid>, path_segment: <slug> }` inside a branch whose
-//     `path_segment` is the collection name (folder.js `defaultEntries`). The
+//     `{ entry: { model, entity: <uuid> }, path_segment: <slug> }` inside a branch
+//     (its `$children`) whose `path_segment` is the collection name (folder.js
+//     `defaultContents`). The
 //     folder is the authoritative organization on a read (the record document's
 //     own `$id` envelope is not guaranteed to be echoed back), with the record
 //     document's `$id` (`<collection>/<slug>`) used as a fallback when present.
@@ -108,24 +109,28 @@ function briefHasContentBody(declaration) {
   return Object.values(brief?.fields || {}).some((f) => isContentBodyField(f))
 }
 
-// Build `uuid → { collection, slug }` from the folder document's ref leaves. A
-// leaf sits in a branch whose `path_segment` is the collection; the leaf's
-// `path_segment` is the slug and its `entry` is the record uuid. Nested branches
+// Build `uuid → { collection, slug }` from the folder document's ref leaves. The
+// folder is a self-nesting tree under `contents`, nesting via `$children` (the
+// site-content invariant — folder.js). A leaf sits in a branch whose
+// `path_segment` is the collection; the leaf's `path_segment` is the slug and its
+// `entry` is the entity_ref open form `{ model, entity: <uuid> }`. Nested branches
 // are walked; the collection is the NEAREST enclosing branch segment (correct for
 // the default one-branch-per-collection org; a deeply nested virtual org may
 // differ — see the module header).
 function indexFolder(folderDoc) {
   const byUuid = new Map()
-  const walk = (entries, collection) => {
-    for (const node of entries || []) {
+  const walk = (nodes, collection) => {
+    for (const node of nodes || []) {
       if (node?.kind === 'branch') {
-        walk(node.entries, node.path_segment ?? collection)
+        walk(node.$children, node.path_segment ?? collection)
       } else if (node?.kind === 'ref' && node.entry) {
-        byUuid.set(node.entry, { collection, slug: node.path_segment })
+        // `entry` is `{ model, entity: <uuid> }`; tolerate a bare uuid defensively.
+        const uuid = typeof node.entry === 'object' ? node.entry.entity : node.entry
+        if (uuid) byUuid.set(uuid, { collection, slug: node.path_segment })
       }
     }
   }
-  walk(folderDoc?.entries, null)
+  walk(folderDoc?.contents, null)
   return byUuid
 }
 
@@ -245,7 +250,7 @@ export function declarationsToCollectionsYml({ document, siteRoot }) {
  * Project a pulled folder + its record entities to `collections/**` files.
  *
  * @param {object} params
- * @param {object} params.folderDoc   - the `@uniweb/folder` document `{ $uuid?, entries }`
+ * @param {object} params.folderDoc   - the `@uniweb/folder` document `{ contents }` (no `$uuid`)
  * @param {object[]} params.recordDocs - record `$`-documents `{ $uuid?, $id?, $model, <brief> }`
  * @param {string} params.siteRoot
  * @param {object} params.opts

package/src/uwx/site-project.js

@@ -99,6 +99,7 @@ const INFO_TO_SITE_YML = {
   search: 'search',
   paths: 'paths',
   data: 'data',
+  template: 'template',
 }
 
 /**
@@ -390,12 +391,16 @@ function pruneOrphanPageDirs(pagesDir, keepDirs, report) {
 // wipe it).
 function projectPages(pages, pagesDir, sourceLocale, report, prune, ctx) {
   writePagesTree(pages, pagesDir, sourceLocale, report, ctx)
-  if (prune) prunePagesTree(pages, pagesDir, report)
+  if (prune) prunePagesTree(pages, pagesDir, sourceLocale, report)
 }
 
 // The directory name for a page record (slug, or `[param]/` for a dynamic page).
-function pageDirName(record) {
-  return record.is_dynamic ? `[${record.param_name || record.slug}]` : record.slug
+// `slug` is a localized `{lang: value}` map on the wire (a page route stays
+// localized); the directory uses the canonical SOURCE-locale slug. `param_name`
+// is already a plain string.
+function pageDirName(record, sourceLocale) {
+  const slug = unwrapLocalized(record.slug, sourceLocale)
+  return record.is_dynamic ? `[${record.param_name || slug}]` : slug
 }
 
 // Pass 1 — write + relocate every page dir, its page.yml/folder.yml, and its
@@ -404,7 +409,8 @@ function pageDirName(record) {
 // producer's slugPath, normalizeRouteForPath strips any leading slash on both).
 function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix = '') {
   for (const record of pages || []) {
-    const pageDir = join(pagesDir, pageDirName(record))
+    const slug = unwrapLocalized(record.slug, sourceLocale) // localized {lang:value} → canonical
+    const pageDir = join(pagesDir, pageDirName(record, sourceLocale))
     // Relocate the whole page dir if this uuid moved to a new slug, then record it.
     placeByUuid(ctx, record.$uuid, pageDir)
 
@@ -417,7 +423,7 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
     if (Array.isArray(record.keywords)) record.keywords.forEach((kw) => ctx.collector?.add(kw))
     else ctx.collector?.add(record.keywords)
 
-    const route = routePrefix ? `${routePrefix}/${record.slug}` : record.slug
+    const route = routePrefix ? `${routePrefix}/${slug}` : slug
     const pageContext = { route, id: record.stable_id }
 
     let sectionsArray = []
@@ -456,16 +462,16 @@ function collectSectionFileBases(pageSections) {
 
 // Pass 2 — prune orphan section files (per page dir) and orphan page dirs (per
 // level), AFTER every relocation in pass 1. Guarded against wiping an empty level.
-function prunePagesTree(pages, pagesDir, report) {
+function prunePagesTree(pages, pagesDir, sourceLocale, report) {
   const incomingDirs = new Set()
   for (const record of pages || []) {
-    incomingDirs.add(pageDirName(record))
-    const pageDir = join(pagesDir, pageDirName(record))
+    incomingDirs.add(pageDirName(record, sourceLocale))
+    const pageDir = join(pagesDir, pageDirName(record, sourceLocale))
     if (record.mode === 'page') {
       const keep = collectSectionFileBases(record.page_sections)
       if (keep.size > 0) pruneOrphanSectionFiles(pageDir, keep, report)
     }
-    prunePagesTree(record.$children || [], pageDir, report)
+    prunePagesTree(record.$children || [], pageDir, sourceLocale, report)
   }
   if (incomingDirs.size > 0) pruneOrphanPageDirs(pagesDir, incomingDirs, report)
 }

package/src/uwx/site.js

@@ -49,6 +49,7 @@ import { normalizeHideIn } from '../site/nav-visibility.js'
 import { emitEntitySyncPackage } from './entity-document.js'
 import { LOCALIZED_FIELD_ASSUMPTION } from './localize.js'
 import { loadLocaleTranslations, localizeScalar, localizeScalarList, localizeContentDoc, localesDir, isLocalizedContent } from './locale-sync.js'
+import { unwrapLocalized } from './backfill.js'
 import { loadFreeformTranslation } from '../i18n/freeform.js'
 import { upsertYamlScalar } from './yaml-upsert.js'
 import { resolveCollectionsConfig } from './collections-config.js'
@@ -99,7 +100,10 @@ async function localizeContentTree(pages, layoutSections, sourceLocale, targetLo
   }
   const visitPages = async (pgs, routePrefix) => {
     for (const p of pgs || []) {
-      const route = routePrefix ? `${routePrefix}/${p.slug}` : p.slug
+      // `slug` is a localized `{lang:value}` map; the free-form route is the
+      // canonical (source-locale) path, so unwrap before building it.
+      const slug = unwrapLocalized(p.slug, sourceLocale)
+      const route = routePrefix ? `${routePrefix}/${slug}` : slug
       const page = { route, id: p.stable_id }
       if (Array.isArray(p.page_sections)) await visitSections(p.page_sections, page)
       if (Array.isArray(p.$children)) await visitPages(p.$children, route)
@@ -535,7 +539,13 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   const translations = targetLocales.length > 0 ? loadLocaleTranslations(siteRoot, targetLocales) : null
 
   const info = {}
-  info.name = localizeScalar(siteYml.name, sourceLocale, translations)
+  // `name` is an identity LABEL (the author's own handle for the site, like a
+  // filename) — single-language by nature, and it must ALWAYS render: under locale
+  // projection a localized field with no entry for the requested locale is dropped,
+  // so a `{en:…}`-only name would vanish. It therefore ships as a plain string, never
+  // a localized `{lang:value}` map. Genuine content fields (`description` below, page
+  // title/slug/label/keywords, the body) stay localized. (uwx-format.md → identity-label names.)
+  info.name = siteYml.name
   setIf(info, 'description', localizeScalar(siteYml.description, sourceLocale, translations))
   if (themeYml && Object.keys(themeYml).length > 0) info.theme = themeYml
   setIf(info, 'languages', siteYml.languages)
@@ -554,6 +564,10 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   setIf(info, 'search', siteYml.search)
   setIf(info, 'paths', siteYml.paths)
   setIf(info, 'data', siteYml.data ?? siteYml.fetch)
+  // `template: true` designates this site as a clonable SITE-TEMPLATE: on push the
+  // backend applies a clonability designation to this site-content entity (it is
+  // NOT a registry artifact). Verbatim; absent → a normal (non-template) site.
+  setIf(info, 'template', siteYml.template)
 
   const ctx = { siteRoot, siteIndex: siteYml.index, sourceLocale, translations }
   const pagesPath = siteYml.paths?.pages

package/src/vite-foundation-plugin.js

@@ -13,6 +13,7 @@ import { join, resolve } from 'node:path'
 import { buildSchema } from './schema.js'
 import { generateEntryPoint, shouldRegenerateForFile } from './generate-entry.js'
 import { processAllPreviews } from './images.js'
+import { generateFoundationVars } from './theme/index.js'
 
 /**
  * Build schema.json with preview image references
@@ -300,6 +301,45 @@ async function buildSSRBundle(outDir) {
   }
 }
 
+/**
+ * Append the foundation's theme-variable DEFAULTS as a `:root{}` baseline to the
+ * built CSS (`assets/style.css`), so a runtime-loaded foundation carries its own
+ * var defaults wherever it loads (registry ref / URL — where the site build can't
+ * read them). Context-aware vars (color/gradient) are excluded: those are applied
+ * per light/dark context by the site theme, not as a flat default. Idempotent
+ * (marker-guarded), and a no-op when the foundation declares no vars or ships no
+ * stylesheet to carry them.
+ */
+async function emitFoundationVarsCss(outDir, schema) {
+  const rawVars = schema?._self?.vars
+  if (!rawVars || Object.keys(rawVars).length === 0) return
+
+  const CONTEXT_AWARE = new Set(['color', 'gradient'])
+  const flatVars = Object.fromEntries(
+    Object.entries(rawVars).filter(
+      ([, cfg]) => !(cfg && typeof cfg === 'object' && CONTEXT_AWARE.has(cfg.type))
+    )
+  )
+
+  const rootCss = generateFoundationVars(flatVars)
+  if (!rootCss) return
+
+  const cssPath = join(outDir, 'assets', 'style.css')
+  if (!existsSync(cssPath)) {
+    console.warn(
+      `Foundation declares ${Object.keys(flatVars).length} theme var(s) but has no assets/style.css to carry their defaults — skipped.`
+    )
+    return
+  }
+
+  const marker = '/* uniweb:foundation-var-defaults */'
+  const existing = await readFile(cssPath, 'utf-8')
+  if (existing.includes(marker)) return
+
+  await writeFile(cssPath, `${existing.trimEnd()}\n\n${marker}\n${rootCss}\n`, 'utf-8')
+  console.log(`Emitted ${Object.keys(flatVars).length} foundation theme-var default(s) to assets/style.css`)
+}
+
 /**
  * Vite plugin for foundation builds
  */
@@ -359,6 +399,18 @@ export function foundationBuildPlugin(options = {}) {
 
       console.log(`Generated meta/schema.json with ${Object.keys(schema).length - 1} components`)
 
+      // Emit the foundation's theme-variable DEFAULTS as a :root{} baseline into
+      // the delivered CSS. A runtime-loaded foundation (registry ref / URL) is
+      // loaded with only its dist/ — the site build can't read these defaults
+      // (they live in schema._self.vars, which the site never sees), so without
+      // this the foundation renders with its theme vars undefined (e.g. collapsed
+      // section spacing where components use py-[var(--section-padding-y)]).
+      // Shipping the defaults in the foundation's own CSS makes it self-sufficient
+      // in every load mode; a site's theme.yml overrides still win (the site theme
+      // loads after the foundation CSS). Bundled sites already get these via the
+      // site build's theme.css — this is harmless redundancy there.
+      await emitFoundationVarsCss(outDir, schema)
+
       // Emit runtime-pin.json so the edge isolate (under Strategy S) can
       // side-load the matching runtime/{ver}/ssr.js. Lands silently before
       // the dual-mode resolver ships; foundations published in the dual-mode