@uniweb/build 0.63.3 → 0.64.0

package/src/uwx/site.js

@@ -56,8 +56,7 @@ import {
   isIgnoredFolder,
   parseNumericPrefix,
   compareFilenames,
-  parseWildcardArray,
-  applyWildcardOrder,
+  orderFolders,
   processMarkdownFile,
   declaredFetch,
   checkDeclaration,
@@ -65,15 +64,19 @@ import {
   assertRouteFolder,
   mountEntriesOf,
   rootOrderConfig,
+  composeLocalizedRoute,
+  isValidSlugSegment,
 } from '../site/content-collector.js'
 import { refuseBinding, refuseUnder, refuseOutsideLanguage, warnDuplicateBindings } from '../site/data-fetcher.js'
-import { readLayoutFolder } from '../site/layout-folder.js'
+import { readLayoutFolder, layoutAreaRoute } from '../site/layout-folder.js'
 import { normalizeHideIn } from '../site/nav-visibility.js'
 import { resolveDefaultLocale, validateLanguageConfig, queryDataUrl } from '@uniweb/core'
 import { emitEntitySyncPackage } from './entity-document.js'
 import { loadLocaleTranslations, localizeScalar, localizeScalarList, localizeContentDoc, localesDir, isLocalizedContent } from './locale-sync.js'
 import { unwrapLocalized } from './backfill.js'
 import { loadFreeformTranslation } from '../i18n/freeform.js'
+import { resolveLocaleList } from '../i18n/locales.js'
+import { translationContext } from '../i18n/extract.js'
 import { updateBackendState, readBackendState } from './sync-store.js'
 import { upsertYamlScalar } from './yaml-upsert.js'
 import { resolveQueriesConfig } from './queries-config.js'
@@ -141,6 +144,89 @@ function stripCredentials(block, label) {
 // processMarkdownFile only destructures type/component/preset/input/props/
 // fetch/data/id out of frontmatter, so `background:` and `theme:` stay
 // inside section.params — lift them into the entity type's dedicated fields.
+// The `type` a push sends for a section whose file names none — the Model requires one. A pull does
+// not write it back into a file that names none (`sectionRecordToFile`): absent, the foundation's
+// `defaultSection` renders it, which is not always `Content`.
+export const FILLED_SECTION_TYPE = 'Content'
+
+const AUTHORED_SLUG = Symbol('authoredSlug')
+const isPlainRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+
+/**
+ * Post-pass: a page's localized URL segments ride in its localized `slug`, beside the source one —
+ * the slot the site-content Model declares for them. From the form the site keeps them in, read as
+ * the build reads it (`buildRouteTranslations`): the pages' own `slug: { <locale>: <segment> }` when
+ * any page declares one, else `site.yml`'s `i18n.routeTranslations`, a whole route per locale, taken
+ * apart into each page's segment. ⛔ Until 2026-09-26 only the source slug was sent, so a clone lost
+ * every localized URL — measured on the `international` template, whose `/acerca-de` came back as
+ * `/about`.
+ *
+ * A route whose localized form is not its parent's plus one segment cannot be said per page, and is
+ * named rather than dropped in silence. Mutates the records in place.
+ */
+function localizeRouteSlugs(pages, siteYml, sourceLocale) {
+  const languages = Array.isArray(siteYml?.languages) ? new Set(siteYml.languages) : null
+  const carried = (locale, segment) =>
+    locale !== sourceLocale && (!languages || languages.has(locale)) && isValidSlugSegment(segment)
+  // Each page with the route the build gives it (`buildRouteOf`).
+  const visit = (records, parentRoute, fn) => {
+    for (const record of records || []) {
+      const route = buildRouteOf(record, parentRoute, sourceLocale)
+      fn(record, route, parentRoute)
+      visit(record.$children, route, fn)
+    }
+  }
+  let ownForm = false
+  visit(pages, '/', (record) => { if (record[AUTHORED_SLUG]) ownForm = true })
+  if (ownForm) {
+    visit(pages, '/', (record) => {
+      for (const [locale, segment] of Object.entries(record[AUTHORED_SLUG] || {})) {
+        if (carried(locale, segment)) record.slug[locale] = segment
+      }
+    })
+    return
+  }
+  const map = siteYml?.i18n?.routeTranslations
+  if (!isPlainRecord(map)) return
+  const segments = new Map() // canonical route → { locale: segment }, as the build composes them
+  visit(pages, '/', (record, route, parentRoute) => {
+    if (record.is_dynamic || record.is_index) return
+    for (const [locale, table] of Object.entries(map)) {
+      const display = isPlainRecord(table) ? table[route] : undefined
+      if (typeof display !== 'string') continue
+      const parts = display.split('/').filter(Boolean)
+      const segment = parts.pop()
+      if (`/${parts.join('/')}` !== composeLocalizedRoute(parentRoute, locale, segments)) {
+        console.warn(
+          `uwx/site: \`i18n.routeTranslations\` gives ${route} the ${locale} URL ${display}, which is not ` +
+            `its parent's plus one segment — it is not sent. Give the page \`slug: { ${locale}: … }\` instead.`
+        )
+        continue
+      }
+      if (!carried(locale, segment)) continue
+      record.slug[locale] = segment
+      segments.set(route, { ...(segments.get(route) || {}), [locale]: segment })
+    }
+  })
+}
+
+/**
+ * The route the build gives a page record: an index page takes its parent's, a parametric one is
+ * `:<param>` (`[...path]` is `:path*`), any other its slug under its parent. One rule, exported for the
+ * pull (`site-project.js`), which must address a page as the push does.
+ *
+ * @param {object} record - a page record (`slug`, `is_index`, `is_dynamic`)
+ * @param {string} parentRoute - its parent's route, `/` at the top
+ * @param {string} sourceLocale
+ * @returns {string}
+ */
+export function buildRouteOf(record, parentRoute, sourceLocale) {
+  if (record?.is_index) return parentRoute
+  const slug = unwrapLocalized(record?.slug, sourceLocale)
+  const segment = record?.is_dynamic ? (slug === CATCH_ALL_MARKER ? ':path*' : `:${slug}`) : slug
+  return parentRoute === '/' ? `/${segment}` : `${parentRoute}/${segment}`
+}
+
 // Post-pass: wrap every section's `content` (page sections + their `$children`,
 // recursing into child pages, plus layout sections) into per-locale form. Mutates
 // the records in place. Only called for multi-locale sites. Each target locale is
@@ -153,9 +239,13 @@ async function localizeContentTree(pages, layoutSections, sourceLocale, targetLo
 
   const localizeSection = async (record, page) => {
     if (!record.content) return
-    let localized = localizeContentDoc(record.content, sourceLocale, targetLocales, translations)
+    const stableId = record.stable_id || record.$id
+    // Resolved in the section's context, as the build resolves it (`translationContext`): a
+    // context-specific override applies here and nowhere else. ⛔ Until 2026-09-26 every section was
+    // resolved with none, so an override never reached a backend.
+    let localized = localizeContentDoc(record.content, sourceLocale, targetLocales, translations, translationContext({ stableId }, page?.route))
     if (page) {
-      const section = { stableId: record.stable_id || record.$id }
+      const section = { stableId }
       for (const locale of targetLocales) {
         // loadFreeformTranslation returns { content, frontmatter, … } — the doc is `.content`.
         const body = (await loadFreeformTranslation(section, page, locale, freeformBase))?.content
@@ -175,19 +265,36 @@ async function localizeContentTree(pages, layoutSections, sourceLocale, targetLo
       if (Array.isArray(s.$children)) await visitSections(s.$children, page)
     }
   }
-  const visitPages = async (pgs, routePrefix) => {
+  // A page is addressed by the route the build gives it (`buildRouteOf`): a free-form translation is
+  // looked up by it, and a translation's context names it. ⛔ Until 2026-09-26 this was the slug path,
+  // so a homepage was `home` where the build reads `/`, and its sections' free-form files were never sent.
+  const visitPages = async (pgs, parentRoute) => {
     for (const p of pgs || []) {
-      // `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 route = buildRouteOf(p, parentRoute, sourceLocale)
       const page = { route, id: p.stable_id }
+      localizePageMeta(p, route, sourceLocale, translations)
       if (Array.isArray(p.page_sections)) await visitSections(p.page_sections, page)
       if (Array.isArray(p.$children)) await visitPages(p.$children, route)
     }
   }
-  await visitPages(pages, '')
-  await visitSections(layoutSections, null) // layout sections have no free-form home
+  await visitPages(pages, '/')
+  // A layout area's section has its free-form home at the area's route, as the build reads it
+  // (`layoutAreaRoute`). ⛔ This said "layout sections have no free-form home" until 2026-09-26.
+  for (const s of layoutSections || []) await localizeSection(s, { route: layoutAreaRoute(s.layout_name, s.area || s.stable_id) })
+}
+
+// ⭐ A page's title, label, description and keywords are resolved in the page's context, as the
+// build translates them (`i18n/merge.js::translatePageMeta`, `<route>:_meta`): an override for one
+// page applies there and nowhere else. ⛔ Until 2026-09-26 they were resolved with no page, so an
+// override never reached a backend — nor, until the same day, an entry's default.
+function localizePageMeta(page, route, sourceLocale, translations) {
+  const context = { page: route, section: '_meta' }
+  const again = (value) =>
+    value && typeof value === 'object' && typeof value[sourceLocale] === 'string'
+      ? localizeScalar(value[sourceLocale], sourceLocale, translations, context)
+      : value
+  for (const key of ['title', 'label', 'description']) if (page[key] !== undefined) page[key] = again(page[key])
+  if (Array.isArray(page.keywords)) page.keywords = page.keywords.map(again)
 }
 
 function mapSectionData(section) {
@@ -197,7 +304,7 @@ function mapSectionData(section) {
   delete params.background
   delete params.theme
 
-  const data = { type: section.type || 'Content' } // entity type requires `type`
+  const data = { type: section.type || FILLED_SECTION_TYPE } // entity type requires `type`
   setIf(data, 'stable_id', section.stableId ?? undefined)
   setIf(data, 'preset', section.preset ?? undefined)
   setIf(data, 'input', section.input ?? undefined)
@@ -214,10 +321,10 @@ function buildPageData(config, ctx) {
   const { slug, mode, isDynamic, paramName, isRoot, siteIndex, sourceLocale, translations, where } =
     ctx
   // The page `slug` is the localized route source — a `{lang: slug}` map (the
-  // site-content Model declares it localized; greenlit 2026-06-13). A single-locale
-  // site emits one entry (`{ en: "home" }`); per-locale slug overrides for
-  // multi-locale localized routes (from i18n.routeTranslations) are follow-on
-  // producer work. `mode` is the plain delivery mode.
+  // site-content Model declares it localized; greenlit 2026-06-13). The source
+  // entry is the folder name; the other locales' segments are added by
+  // `localizeRouteSlugs`, once the whole tree is known. `mode` is the plain
+  // delivery mode.
   const data = { slug: { [sourceLocale]: slug }, mode } // both required by the entity type
   setIf(data, 'stable_id', config.id)
   setIf(data, 'title', localizeScalar(config.title, sourceLocale, translations))
@@ -350,21 +457,14 @@ async function orderedSubfolders(dirPath, inheritedMode, parentConfig) {
       order: typeof config.order === 'number' ? config.order : undefined,
     })
   }
-  // Mirror content-collector's pageFolders sort: explicit order, then
-  // numeric-prefix filename order.
-  folders.sort(
-    (a, b) =>
-      (a.order ?? Infinity) - (b.order ?? Infinity) ||
-      compareFilenames(a.dirName, b.dirName)
-  )
-  // Then the parent's `pages:` wildcard, exactly as a normal build applies it.
-  if (Array.isArray(parentConfig?.pages)) {
-    const parsed = parseWildcardArray(parentConfig.pages)
-    if (parsed && parsed.mode !== 'all') {
-      return applyWildcardOrder(folders, parsed)
-    }
-  }
-  return folders
+  // Explicit order, then numeric-prefix filename order, then the parent's `pages:` wildcard —
+  // one function, which the pull reproduces a level's order with too (`site-project.js`).
+  // ⚠️ It does NOT match the build's own page-folder sort in one case, and the note that said
+  // "mirror content-collector's pageFolders sort" here read as if it did: the collector compares
+  // a level's folder names whole, as strings, and matches `pages:` against them whole, where
+  // this strips a numeric prefix (`2-about` is `about`, and `10-` sorts after `2-`). Only a level
+  // with numbered page folders can tell them apart, and which rule is right for them is open.
+  return orderFolders(folders, parentConfig?.pages)
 }
 
 const DYNAMIC_RE = /^\[(.+)\]$/
@@ -668,6 +768,9 @@ async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, pare
     // natural handle — spec default). The path is NEVER the identity.
     const id = data.stable_id || slug
     const record = withIdentity(id, data)
+    // A page's own localized URL segments, for `localizeRouteSlugs` — under a symbol, so they
+    // are never serialized as a field of the record.
+    if (!dyn && isPlainRecord(f.config?.slug)) record[AUTHORED_SLUG] = f.config.slug
 
     if (mode === 'page') {
       const sections = await collectPageSectionsNested(f.path, siteRoot, f.config)
@@ -1135,7 +1238,7 @@ function secretsNested(provisioned) {
 // ROUND-TRIP LAW). `site-project.js::SETTINGS_TO_SITE_YML` plus its explicit
 // branches is the other half, and `producer-list-drift.test.js` fails if a key
 // emitted here has neither.
-function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translations } = {}) {
+function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translations, languages = null } = {}) {
   const settings = {}
 
   // Site-wide values an author declares once and references from page content as
@@ -1169,7 +1272,13 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
   // ⇒ `settings` is where they live. `publish_languages` rides VERBATIM, dangling
   // codes included: sync carries the full working set and only *publish* filters,
   // which preserves a locale's publish intent across a remove + re-add in `languages:`.
-  setIf(settings, 'languages', siteYml.languages)
+  // ⭐ A site that declares no `languages:` has the languages its translation files make — the build's
+  // rule (`i18n/locales.js`) — and sends that list (`languages`, below), as it sends a derived
+  // `deferred:`: a host may serve a site in the languages it declares and no others, and the site's
+  // localized URLs with them. The pull does not write it back where the files already say it
+  // (`siteContentDocumentToProject`). ⛔ Until 2026-09-26 only a declared list was sent, so the
+  // `international` template, which declares none, sent no language but its source.
+  setIf(settings, 'languages', siteYml.languages ?? languages ?? undefined)
   setIf(settings, 'default_language', siteYml.defaultLanguage)
   setIf(settings, 'publish_languages', siteYml.publishLanguages)
 
@@ -1287,7 +1396,10 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // Target-locale translations (locales/{locale}.json) for wrapping localized
   // scalars back into per-locale form. Source-locale-only when no target locales /
   // no locale files exist (single-locale sites are unaffected).
-  const targetLocales = (Array.isArray(siteYml.languages) ? siteYml.languages : []).filter(
+  // ⭐ The site's locales by the build's own rule (`i18n/locales.js`): an explicit
+  // `languages:` list, else every translation file. ⛔ Until 2026-09-25 only an explicit list
+  // counted, so a site with none — the `international` template — pushed no translations.
+  const targetLocales = resolveLocaleList(siteYml.languages, localesDir(siteRoot)).filter(
     (l) => l !== sourceLocale
   )
   const translations = targetLocales.length > 0 ? loadLocaleTranslations(siteRoot, targetLocales) : null
@@ -1502,6 +1614,7 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
     // — as the build does — pushed no homepage at all.
     const top = rootOrderConfig({ pages: siteYml.pages, index: siteYml.index }, rootConfig)
     pages = await walkPagesNested({ ...ctx, siteIndex: top.homepage }, pagesPath, '', rootMode, { pages: top.pages }, true)
+    localizeRouteSlugs(pages, siteYml, sourceLocale)
   }
 
   const layoutSections = await collectLayoutNested(layoutDir, siteRoot)
@@ -1535,7 +1648,9 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   doc.$schema = SITE_MODEL_NAME
   doc.info = info
   // Emitted only when the file declares something — see `settingsNested`.
-  const settings = settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translations })
+  // The languages the site's translation files make, for a site that declares none (`settingsNested`).
+  const languages = targetLocales.length > 0 ? [sourceLocale, ...targetLocales] : null
+  const settings = settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translations, languages })
   if (settings) doc.settings = settings
   doc.pages = pages
   doc.layout_sections = layoutSections