@uniweb/build 0.52.3 → 0.52.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.52.3",
+  "version": "0.52.5",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,12 +57,12 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/content-reader": "^1.2.5",
-    "@uniweb/schemas": "^0.2.15",
-    "@uniweb/semantic-parser": "^1.4.0",
     "@uniweb/projections": "^0.7.3",
-    "@uniweb/theming": "^0.1.15",
-    "@uniweb/content-writer": "^0.3.4"
+    "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/schemas": "^0.3.1",
+    "@uniweb/content-reader": "^1.2.5",
+    "@uniweb/content-writer": "^0.3.4",
+    "@uniweb/theming": "^0.1.15"
   },
   "optionalDependencies": {
     "@uniweb/runtime": "^0.26.4"

package/src/docs.js

@@ -31,6 +31,13 @@ function generateComponentDocs(name, meta) {
     lines.push('')
   }
 
+  // The standard section type this component claims. `family` replaced the
+  // retired `category:` / `purpose:` pair, which this generator never emitted.
+  if (meta.family) {
+    lines.push(`*Family:* \`${meta.family}\``)
+    lines.push('')
+  }
+
   // Parameters (shown first - most important for content authors)
   if (meta.params && Object.keys(meta.params).length > 0) {
     lines.push('### Parameters')
@@ -66,33 +73,48 @@ function generateComponentDocs(name, meta) {
     }
   }
 
-  // Presets
-  if (meta.presets && meta.presets.length > 0) {
+  // Presets — named param combinations. `meta.presets` is a KEYED OBJECT
+  // ({ name: { label, params } }), not an array: this read `meta.presets.length`
+  // until 2026-09-16, which is `undefined > 0` on an object, so every preset in
+  // every foundation was dropped from COMPONENTS.md with nothing reporting it.
+  const presets = Object.entries(meta.presets || {})
+  if (presets.length > 0) {
     lines.push('### Presets')
     lines.push('')
 
-    for (const preset of meta.presets) {
-      const settings = preset.settings
-        ? Object.entries(preset.settings)
+    for (const [name, preset] of presets) {
+      const settings = preset?.params
+        ? Object.entries(preset.params)
             .map(([k, v]) => `${k}: ${v}`)
             .join(', ')
         : ''
-      lines.push(`- **${preset.name}**${settings ? ` — ${settings}` : ''}`)
+      const label = preset?.label || name
+      lines.push(`- **${name}**${label !== name ? ` — ${label}` : ''}${settings ? ` (${settings})` : ''}`)
     }
     lines.push('')
   }
 
-  // Content Elements (condensed - less important)
-  if (meta.elements && Object.keys(meta.elements).length > 0) {
-    const elements = Object.entries(meta.elements)
-    const elementList = elements.map(([key, el]) => {
-      return el.required ? `${key} (required)` : key
-    }).join(', ')
-
+  // Content expectations — what an author writes in the markdown. The key is
+  // `content`; this read `meta.content` as `meta.elements` until 2026-09-16 —
+  // the pre-rename name, which nothing has produced since. A dead branch reads
+  // exactly like a component that declares nothing, so the whole section was
+  // missing from every generated catalog.
+  //
+  // A value is either a label string ('Description [1-2]') or { label, hint }.
+  // The LABEL is the point: `paragraphs` alone tells an author nothing, and the
+  // count hint is the part that says how much to write.
+  const elements = Object.entries(meta.content || {})
+  if (elements.length > 0) {
     lines.push('### Content')
     lines.push('')
-    lines.push(elementList)
-    lines.push('')
+
+    for (const [key, el] of elements) {
+      const label = typeof el === 'string' ? el : el?.label || ''
+      lines.push(`**${key}**${label ? ` — ${label}` : ''}`)
+      const hint = typeof el === 'object' && el?.hint ? el.hint : ''
+      if (hint) lines.push(`  ${hint}`)
+      lines.push('')
+    }
   }
 
   return lines.join('\n')

package/src/i18n/extract.js

@@ -327,7 +327,8 @@ function visitTranslatableBlocks(nodes, visit) {
  * Determine field name for heading based on level and index
  */
 function getHeadingField(level, index) {
-  // First H1 is title, first H2 is subtitle, H3 before H1 could be pretitle
+  // First H1 is title, first H2 is subtitle. A pretitle is a `#>` label line
+  // (or, in older content, a smaller heading above the title).
   // This is simplified - semantic-parser does this more intelligently
   if (level === 1) return index.h1 === 0 ? 'title' : `heading.${index.h1}`
   if (level === 2) return index.h2 === 0 ? 'subtitle' : `heading.h2.${index.h2}`

package/src/uwx/site-diff.js

@@ -23,7 +23,7 @@
 // Units are DISJOINT: a page's hash excludes its sections, a section's excludes its
 // children, so a change lands in exactly one unit and is never double-reported.
 // Naming comes from the projector's own helpers (`pageDirName`,
-// `safeStableIdFilename`) rather than a local copy, so a label always names a file
+// `sectionFileBase`) rather than a local copy, so a label always names a file
 // that really exists.
 //
 // It needs TWO bases, and that is the non-obvious part.
@@ -47,7 +47,7 @@
 // reported as unattributed rather than guessed at.
 
 import { entityContentHash } from './records.js'
-import { recordStableId, safeStableIdFilename, pageDirName, layoutSectionPaths } from './site-project.js'
+import { sectionFileBase, pageDirName, layoutSectionPaths } from './site-project.js'
 import { LOCALIZED_FIELD_ASSUMPTION } from './localize.js'
 
 // A unit's own content, with the nested collections that are their own units
@@ -95,10 +95,10 @@ export function collectSiteUnits(doc, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.
 export function walkSiteUnits(doc, cb, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale) {
   const walkSections = (sections, dir) => {
     for (const record of sections || []) {
-      const id = recordStableId(record)
-      // Anonymous and id-less: the projector cannot place it either, so there is
-      // no file to name and nothing to attribute.
-      if (id) cb(`${dir}/${safeStableIdFilename(id)}.md`, record, 'section')
+      // The projector's own file rule, so a unit's path here is the file it is
+      // written to — including an app-created section named from its `$uuid`.
+      const base = sectionFileBase(record)
+      if (base) cb(`${dir}/${base}.md`, record, 'section')
       walkSections(record.$children, dir)
     }
   }

package/src/uwx/site-project.js

@@ -464,6 +464,42 @@ export function safeStableIdFilename(stableId) {
   return base ? `${base}-${hash}` : `s-${hash}`
 }
 
+/**
+ * The `.md` file base a page section is written to — the ONE rule the projector,
+ * the prune keep-set and the push/pull unit walk (`site-diff.js::walkSiteUnits`)
+ * all use, so the path a pull harvests a `$uuid` under is the path the next push
+ * stamps it back onto.
+ *
+ * `stable_id || $id` when the record has one (unchanged). ⛔ A section with
+ * neither — what the app's editor creates: a `$uuid` and no stable id — used to be
+ * SKIPPED, silently, by all three. A pull then left its file out, and a push after
+ * any local edit sent the page without it, which the backend deletes (a
+ * package's absence of a stored `page_sections` item under a page it sends is a
+ * delete). So such a section is named from its identity instead:
+ * `<type-kebab>-<last 8 hex of $uuid>`, e.g. `hero-95993360`.
+ *
+ * The derived base is already filesystem-safe and starts with a letter, so the
+ * build reads it back verbatim as the section's stable id (no numeric prefix to
+ * strip) and `safeStableIdFilename` returns it unchanged — the push path equals
+ * the pull path. The first push after such a pull therefore gives the item that
+ * stable id; the `$uuid` is re-stamped by path, so the item keeps its identity.
+ *
+ * @returns {string|null} null only for a record with no stable id and no `$uuid`
+ */
+export function sectionFileBase(record) {
+  const id = recordStableId(record)
+  if (id) return safeStableIdFilename(id)
+  const hex = typeof record?.$uuid === 'string' ? record.$uuid.replace(/-/g, '').toLowerCase() : ''
+  if (!/^[0-9a-f]{8,}$/.test(hex)) return null
+  const kebab = String(record?.type || '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  const stem = /^[a-z]/.test(kebab) ? kebab : 'section'
+  return `${stem}-${hex.slice(-8)}`
+}
+
 /**
  * Write a page's `page_sections` tree to clean `<stableId>.md` files in `pageDir`
  * and return the `page.yml::sections:` array that captures order + nesting — the
@@ -483,12 +519,13 @@ export function pageSectionsToFiles({ pageDir, pageSections, ctx, pageContext })
   const buildEntries = (records) => {
     const entries = []
     for (const record of records || []) {
-      const stableId = recordStableId(record)
-      if (!stableId) continue // anonymous and id-less → cannot place; skip
-      // Filesystem-safe filename (= stableId when already safe); the true stableId
-      // rides in frontmatter `id:`. The sections: leaf uses the same base so the
-      // producer's filename-based resolution matches.
-      const fileBase = safeStableIdFilename(stableId)
+      // Filesystem-safe filename (= stableId when already safe; derived from `$uuid`
+      // for an app-created section with no stable id); the true stableId rides in
+      // frontmatter `id:`. The sections: leaf uses the same base so the producer's
+      // filename-based resolution matches.
+      const fileBase = sectionFileBase(record)
+      if (!fileBase) continue // no stable id AND no `$uuid` → nothing to name it by
+      const stableId = recordStableId(record) || fileBase
       const filePath = join(pageDir, `${fileBase}.md`)
       // If this uuid's section moved (an app-side stableId rename), relocate its
       // `.md` in place before writing; then record its current path in the index.
@@ -672,8 +709,8 @@ function collectSectionFileBases(pageSections) {
   const bases = new Set()
   const walk = (records) => {
     for (const record of records || []) {
-      const id = recordStableId(record)
-      if (id) bases.add(safeStableIdFilename(id))
+      const base = sectionFileBase(record)
+      if (base) bases.add(base)
       if (Array.isArray(record.$children)) walk(record.$children)
     }
   }