@uniweb/build 0.75.0 → 0.76.0

package/src/i18n/model-fields.js

@@ -0,0 +1,97 @@
+/**
+ * ⭐ A RECORD'S FIELDS, WALKED BY ITS MODEL — the shape a push sends it in, lowered by the push's
+ * own rule (`uwx/data-schema.js::toDataSchemaDeclaration`), which marks `localized` exactly the
+ * fields that travel per locale: text — never an enum, a value format (a URL, an email), a
+ * `translatable: false` field, a number, a date, a file or a reference.
+ *
+ * One walk for two things a model describes: a record (`records.js`), and a tagged data block whose
+ * key a section type declares the shape of (`data-strings.js::visitDataBlockStrings`).
+ */
+import { isOpenMapSection } from '../uwx/data-schema.js'
+
+export function isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * ⛔ A RECORD'S SYSTEM FIELDS ARE NEVER PROSE — never extracted, never translated, by
+ * either path. A `$`-prefixed key at any depth is the system's (`$name`, the handle a
+ * parametric page's URL names; `$uuid`; `$branch`, the folder a compiled list holds a
+ * record under), and a top-level `slug` is how a record's reader hands the file's name
+ * on. Until 2026-09-14 they became translation units, and a translation whose source
+ * happened to equal one rewrote it, so a record's page stopped matching its URL.
+ * ⛔ A top-level `path` was one too until 2026-09-27, when the placement it named moved to
+ * `$branch` [Diego]: a field an author names `path` is theirs, and translated as its schema says.
+ *
+ * @param {string|number} key - a field name (an array index is never one)
+ * @param {boolean} topLevel - whether the key sits at the record's own level
+ * @returns {boolean}
+ */
+export function isRecordSystemField(key, topLevel) {
+  if (typeof key !== 'string') return false
+  return key.startsWith('$') || (topLevel && key === 'slug')
+}
+
+/**
+ * Each field of a model that a record holds a value for, in the shape the record is DELIVERED in
+ * (`toDeliveredRecord`): the brief's fields at the top — every field, for a model of one single
+ * section — and each other section under its name, a list of them for a `multiple` one, a nested
+ * section the same way. Calls `visit(holder, name, field, path)` for each.
+ */
+export function eachModelField(record, model, visit) {
+  const sections = Object.entries(model?.sections || {})
+  const flat = sections.length === 1 && !sections[0][1]?.multiple
+  for (const [name, section] of sections) {
+    if (flat || section?.brief) eachSectionField(record, section?.fields, '', visit)
+    else eachSectionValue(record?.[name], section, name, visit)
+  }
+}
+
+function eachSectionValue(value, section, path, visit) {
+  if (!section?.multiple) return eachSectionField(value, section?.fields, path, visit)
+  if (Array.isArray(value)) value.forEach((item, i) => eachSectionField(item, section.fields, `${path}[${i}]`, visit))
+  // An open map as its file holds it: each entry is one of the rows a push sends (`isOpenMapSection`).
+  else if (isOpenMapSection(section) && isPlainObject(value)) {
+    for (const [key, item] of Object.entries(value)) eachSectionField(item, section.fields, `${path}.${key}`, visit)
+  }
+}
+
+export function eachSectionField(holder, fields, path, visit) {
+  if (!isPlainObject(holder)) return
+  for (const [name, field] of Object.entries(fields || {})) {
+    if (holder[name] == null || isRecordSystemField(name, !path)) continue
+    const at = path ? `${path}.${name}` : name
+    if (field?.type === 'section') eachSectionValue(holder[name], field, at, visit)
+    else visit(holder, name, field || {}, at)
+  }
+}
+
+/**
+ * Each string a record's model marks `localized` — a text field's value, or each string of a list
+ * of them — handed to `visit(value, path)`; a different string returned replaces it, in place, as
+ * `data-strings.js::visitDataStrings` does. A rich field is one string here: a data block holds its
+ * markdown as written.
+ *
+ * @param {object} record
+ * @param {object} model - a lowered data schema (`toDataSchemaDeclaration`)
+ * @param {(value: string, path: string) => string|void} visit
+ * @param {string} [prefix] - prepended to each path (`[0]` for a list's first item)
+ */
+export function visitModelStrings(record, model, visit, prefix = '') {
+  const pathOf = (path) => (prefix ? (path.startsWith('[') ? `${prefix}${path}` : `${prefix}.${path}`) : path)
+  eachModelField(record, model, (holder, name, field, path) => {
+    if (!field.localized) return
+    const value = holder[name]
+    if (typeof value === 'string') {
+      if (!value.trim()) return
+      const next = visit(value, pathOf(path))
+      if (typeof next === 'string' && next !== value) holder[name] = next
+    } else if (Array.isArray(value)) {
+      value.forEach((item, i) => {
+        if (typeof item !== 'string' || !item.trim()) return
+        const next = visit(item, pathOf(`${path}[${i}]`))
+        if (typeof next === 'string' && next !== item) value[i] = next
+      })
+    }
+  })
+}

package/src/i18n/records.js

@@ -23,7 +23,8 @@ import { computeHash } from './hash.js'
 import { loadFreeformRecord } from './freeform.js'
 import { resolveQueriesConfig, resolveRecordSchemas, foundationSchemaJson } from '../site/queries-config.js'
 import { dataKeyTypes, keyOfDefaultRef } from '../uwx/data-key-types.js'
-import { toDataSchemaDeclaration, isProseMirrorField, isOpenMapSection } from '../uwx/data-schema.js'
+import { toDataSchemaDeclaration, isProseMirrorField } from '../uwx/data-schema.js'
+import { eachModelField, eachSectionField, isRecordSystemField, isPlainObject } from './model-fields.js'
 import { toDeliveredRecord, contentBodyField, misplacedFields, mergedFromStored, storedFromMerged } from '@uniweb/schemas/conform'
 import { resolveDocForLocale } from './merge.js'
 import { extractUnitsFromDoc } from './extract.js'
@@ -186,7 +187,7 @@ function isFieldTranslatable(fieldDef) {
  * @param {string} ref - the ref it was resolved from
  * @returns {Object|null} the lowered declaration, or null when there is none
  */
-function modelOf(schema, ref) {
+export function modelOf(schema, ref) {
   if (!schema) return null
   try {
     return toDataSchemaDeclaration(schema, { name: ref || '@/record', resolveName: (r) => r })
@@ -208,40 +209,6 @@ function referencedModels(model) {
   return out
 }
 
-/**
- * Each field of a model that a record holds a value for, in the shape the record is DELIVERED in
- * (`toDeliveredRecord`): the brief's fields at the top — every field, for a model of one single
- * section — and each other section under its name, a list of them for a `multiple` one, a nested
- * section the same way. Calls `visit(holder, name, field, path)` for each.
- */
-function eachModelField(record, model, visit) {
-  const sections = Object.entries(model?.sections || {})
-  const flat = sections.length === 1 && !sections[0][1]?.multiple
-  for (const [name, section] of sections) {
-    if (flat || section?.brief) eachSectionField(record, section?.fields, '', visit)
-    else eachSectionValue(record?.[name], section, name, visit)
-  }
-}
-
-function eachSectionValue(value, section, path, visit) {
-  if (!section?.multiple) return eachSectionField(value, section?.fields, path, visit)
-  if (Array.isArray(value)) value.forEach((item, i) => eachSectionField(item, section.fields, `${path}[${i}]`, visit))
-  // An open map as its file holds it: each entry is one of the rows a push sends (`isOpenMapSection`).
-  else if (isOpenMapSection(section) && isPlainObject(value)) {
-    for (const [key, item] of Object.entries(value)) eachSectionField(item, section.fields, `${path}.${key}`, visit)
-  }
-}
-
-function eachSectionField(holder, fields, path, visit) {
-  if (!isPlainObject(holder)) return
-  for (const [name, field] of Object.entries(fields || {})) {
-    if (holder[name] == null || isRecordSystemField(name, !path)) continue
-    const at = path ? `${path}.${name}` : name
-    if (field?.type === 'section') eachSectionValue(holder[name], field, at, visit)
-    else visit(holder, name, field || {}, at)
-  }
-}
-
 /** The fields of a model's brief — what a reference to one of its records is delivered as. */
 function briefFields(model) {
   const sections = Object.values(model?.sections || {})
@@ -360,25 +327,6 @@ function derivesExcerpt(record, whole, dataSchema, config) {
   return derivedExcerptOf(whole ?? record, dataSchema, config) === record.excerpt
 }
 
-/**
- * ⛔ A RECORD'S SYSTEM FIELDS ARE NEVER PROSE — never extracted, never translated, by
- * either path. A `$`-prefixed key at any depth is the system's (`$name`, the handle a
- * parametric page's URL names; `$uuid`; `$branch`, the folder a compiled list holds a
- * record under), and a top-level `slug` is how a record's reader hands the file's name
- * on. Until 2026-09-14 they became translation units, and a translation whose source
- * happened to equal one rewrote it, so a record's page stopped matching its URL.
- * ⛔ A top-level `path` was one too until 2026-09-27, when the placement it named moved to
- * `$branch` [Diego]: a field an author names `path` is theirs, and translated as its schema says.
- *
- * @param {string|number} key - a field name (an array index is never one)
- * @param {boolean} topLevel - whether the key sits at the record's own level
- * @returns {boolean}
- */
-function isRecordSystemField(key, topLevel) {
-  if (typeof key !== 'string') return false
-  return key.startsWith('$') || (topLevel && key === 'slug')
-}
-
 /**
  * A record's handle — `$name`, which the build sets from the record's file (`slug:` or
  * its name). ⭐ Not `slug` alone: a record of a schema whose brief declares a `slug`
@@ -1208,10 +1156,6 @@ function applyFreeform(record, freeform, dataSchema, schemaRef) {
   return out
 }
 
-function isPlainObject(value) {
-  return !!value && typeof value === 'object' && !Array.isArray(value)
-}
-
 /**
  * Apply translations to a collection item (sync, hash-based only) — by the model it is pushed as
  * when it has one (`translateByModel`), else a companion schema's fields, else the heuristic.

package/src/resolve-data-schema.js

@@ -84,6 +84,60 @@ export const SCHEMA_NOT_FOUND = 'SCHEMA_NOT_FOUND'
 const RESERVED_SYSTEM_SCOPE = 'uniweb'
 const packageForScope = (scope) => SCOPE_PACKAGE[scope] ?? `@${scope}/schemas`
 
+/**
+ * A NAMED data schema — a `schemas/` file, `@std/<name>`, `@org/<name>` — validated and
+ * normalized, and refused when a field declares a `default`.
+ *
+ * ⛔ A named schema declares no default — ruled 2026-10-05 [Diego], when the runtime stopped
+ * filling fields: nothing would read one. The runtime fills no field, the declaration a
+ * registry stores carries none (`uwx/data-schema.js`), and the foundation schema an editor
+ * reads leaves `dataSchemas` out (`uwx/registry-package.js`) — so a `default:` here would be a
+ * promise kept nowhere. What an absent field renders as is the component's choice. A default
+ * stays where an editor reads it: a component's own inline field map or form in `data:`.
+ *
+ * @param {object} schema - the schema as authored
+ * @param {string} ref - its ref, for the message
+ * @returns {object} the normalized schema
+ */
+function normalizeNamedSchema(schema, ref) {
+  const normalized = validateAndNormalizeSchema(schema, ref)
+  const paths = fieldsWithDefaults(normalized)
+  if (paths.length > 0) {
+    throw new Error(
+      `Data schema '${ref}': a named data schema declares no default — remove \`default:\` from ` +
+        `${paths.map((p) => `'${p}'`).join(', ')}. A component decides what an absent field ` +
+        `renders as; an editor pre-fills from a component's own inline field map or form in \`data:\`.`
+    )
+  }
+  return normalized
+}
+
+/** The dotted paths of every field in a normalized schema that declares a `default`. */
+function fieldsWithDefaults(schema) {
+  const found = []
+  const walkFields = (fields, prefix) => {
+    if (!fields || typeof fields !== 'object') return
+    for (const [name, spec] of Object.entries(fields)) walkSpec(spec, `${prefix}${name}`)
+  }
+  const walkSpec = (spec, path) => {
+    if (!spec || typeof spec !== 'object') return
+    if (spec.default !== undefined) found.push(path)
+    walkFields(spec.fields, `${path}.`)
+    if (spec.items) walkSpec(spec.items, `${path}[]`)
+    if (spec.values) walkSpec(spec.values, `${path}{}`)
+  }
+  const walkSections = (sections, prefix) => {
+    if (!sections || typeof sections !== 'object') return
+    for (const [name, section] of Object.entries(sections)) {
+      walkFields(section?.fields, `${prefix}${name}.`)
+      walkSections(section?.sections, `${prefix}${name}.`)
+    }
+  }
+  walkFields(schema?.fields, '')
+  walkSections(schema?.sections, '')
+  return found
+}
+
 /**
  * Collect every distinct schema ref used by a foundation's section bindings.
  * Reads `data: { key: '<ref>' }` (short) and `data: { key: { schema: '<ref>' } }`
@@ -94,9 +148,9 @@ const packageForScope = (scope) => SCOPE_PACKAGE[scope] ?? `@${scope}/schemas`
  * (`declaredKeys`, `@uniweb/core/data-keys`) — but only components were scanned
  * here, so a ref at that tier was neither resolved into `dataSchemas` nor
  * rejected when dangling, while the key was still delivered at runtime. The
- * symptom would have been no schema for the editor and no field defaults from
- * `applySchemas`, with no build error. It bit nobody only because every
- * foundation-tier declaration in the templates is ref-less.
+ * symptom would have been no schema for the editor, with no build error. It bit
+ * nobody only because every foundation-tier declaration in the templates is
+ * ref-less.
  *
  * @param {Object} components - Map of componentName → full meta (with `data`)
  * @param {Object|false|null} [foundationData] - the foundation's `main.js` `data:`
@@ -136,7 +190,7 @@ export async function resolveSchemaRef(ref, { srcDir, aliases }) {
         { code: SCHEMA_NOT_FOUND }
       )
     }
-    return validateAndNormalizeSchema(await loadSchemaFile(file), ref)
+    return normalizeNamedSchema(await loadSchemaFile(file), ref)
   }
 
   // ⭐ THE SYSTEM MODELS A SITE'S RECORDS MAY NAME — `@uniweb/link` — resolve from the build's own
@@ -145,7 +199,7 @@ export async function resolveSchemaRef(ref, { srcDir, aliases }) {
   // never a data-schema source. (The whole scope was refused until 2026-09-28.)
   if (scope === RESERVED_SYSTEM_SCOPE) {
     const system = SYSTEM_RECORD_SCHEMAS[name]
-    if (system) return validateAndNormalizeSchema(system, ref)
+    if (system) return normalizeNamedSchema(system, ref)
     const allowed = Object.keys(SYSTEM_RECORD_SCHEMAS).map((n) => `'@${scope}/${n}'`).join(', ')
     throw new Error(
       `'@${scope}' is the reserved platform system namespace: the only data schemas a site's records ` +
@@ -170,7 +224,7 @@ export async function resolveSchemaRef(ref, { srcDir, aliases }) {
           `exists there. Point it at a ${SCHEMA_EXTENSIONS.join(' / ')} file.`
       )
     }
-    return validateAndNormalizeSchema(await loadSchemaFile(file), ref)
+    return normalizeNamedSchema(await loadSchemaFile(file), ref)
   }
 
   // A scope alias ('@org' → a DIR) resolves 'name' to a bare schema FILE in that
@@ -195,7 +249,7 @@ export async function resolveSchemaRef(ref, { srcDir, aliases }) {
       }
       throw new Error(msg)
     }
-    return validateAndNormalizeSchema(await loadSchemaFile(file), ref)
+    return normalizeNamedSchema(await loadSchemaFile(file), ref)
   }
 
   // Every other scope is an org namespace: '@org/name' resolves `name` from that
@@ -207,7 +261,7 @@ export async function resolveSchemaRef(ref, { srcDir, aliases }) {
   if (!schema) {
     throw new Error(`Unknown data schema '${ref}': '${pkg}' exports no schema named '${name}'.`)
   }
-  return validateAndNormalizeSchema(schema, ref)
+  return normalizeNamedSchema(schema, ref)
 }
 
 /**
@@ -224,9 +278,8 @@ export async function resolveSchemaRef(ref, { srcDir, aliases }) {
 export async function buildDataSchemaMap(refs, { srcDir }) {
   // Load the foundation's optional schemas.config.js once; every ref (and every
   // transitively-discovered ref) resolves against the same alias map. This is
-  // the single entry both schema discovery and the runtime-schema build go
-  // through, so editor schema.json, runtime defaults, and `uniweb validate` all
-  // resolve refs identically.
+  // the single entry schema discovery and `uniweb validate` go through, so the
+  // editor's schema.json and the check of a site's data resolve refs identically.
   const aliases = await loadSchemaAliases(srcDir)
   const map = {}
   const queue = Array.from(refs)
@@ -299,7 +352,7 @@ async function collectSchemasFromExports(packageDir) {
   for (const name of names) {
     const schema = get(name)
     if (!schema || typeof schema !== 'object') continue
-    out[`@/${name}`] = validateAndNormalizeSchema(schema, `@/${name}`)
+    out[`@/${name}`] = normalizeNamedSchema(schema, `@/${name}`)
   }
   return out
 }
@@ -309,7 +362,7 @@ async function collectSchemasFromExports(packageDir) {
 async function collectSchemasFromDir(dir) {
   const out = {}
   for (const { file, name } of schemaFilesIn(dir)) {
-    out[`@/${name}`] = validateAndNormalizeSchema(await loadSchemaFile(join(dir, file)), `@/${name}`)
+    out[`@/${name}`] = normalizeNamedSchema(await loadSchemaFile(join(dir, file)), `@/${name}`)
   }
   return out
 }