@uniweb/build 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -56,12 +56,12 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/semantic-parser": "~1.6.0",
-    "@uniweb/theming": "~1.2.0",
-    "@uniweb/schemas": "~1.1.0",
     "@uniweb/projections": "~1.1.1",
-    "@uniweb/content-reader": "~1.3.0",
-    "@uniweb/content-writer": "~1.1.0"
+    "@uniweb/content-writer": "~1.1.0",
+    "@uniweb/theming": "~1.2.0",
+    "@uniweb/semantic-parser": "~1.6.0",
+    "@uniweb/schemas": "~1.2.0",
+    "@uniweb/content-reader": "~1.3.0"
   },
   "optionalDependencies": {
     "@uniweb/runtime": "~1.1.1"
@@ -73,8 +73,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "~1.2.0",
-    "@uniweb/runtime": "~1.1.1"
+    "@uniweb/runtime": "~1.1.1",
+    "@uniweb/core": "~1.2.0"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/resolve-data-schema.js

@@ -40,6 +40,7 @@ import { existsSync, readdirSync, statSync } from 'node:fs'
 import { join, resolve, isAbsolute, extname, basename } from 'node:path'
 import { dataRefOf } from '@uniweb/core/data-keys'
 import { SYSTEM_RECORD_SCHEMAS } from '@uniweb/schemas/system'
+import { assertOptionsTargets } from './uwx/data-schema.js'
 import { pathToFileURL } from 'node:url'
 import { createRequire } from 'node:module'
 import yaml from 'js-yaml'
@@ -101,7 +102,7 @@ const packageForScope = (scope) => SCOPE_PACKAGE[scope] ?? `@${scope}/schemas`
  */
 function normalizeNamedSchema(schema, ref) {
   const normalized = validateAndNormalizeSchema(schema, ref)
-  const paths = fieldsWithDefaults(normalized)
+  const paths = fieldsWhere(normalized, (spec) => spec.default !== undefined)
   if (paths.length > 0) {
     throw new Error(
       `Data schema '${ref}': a named data schema declares no default — remove \`default:\` from ` +
@@ -109,11 +110,37 @@ function normalizeNamedSchema(schema, ref) {
         `renders as; an editor pre-fills from a component's own inline field map or form in \`data:\`.`
     )
   }
+  // ⛔ The same reason, two more keys (2026-10-15): nothing keeps them for a named schema. A
+  // registry has no slot for a field's `help` or for a leaf's `constraints` — it refuses the
+  // first, and a section key cannot sit on a leaf — and no reader of the build reads either.
+  // Until then both were dropped when the schema was registered, without a word.
+  const helped = fieldsWhere(normalized, (spec) => spec.help !== undefined)
+  if (helped.length > 0) {
+    throw new Error(
+      `Data schema '${ref}': a named data schema declares no \`help\` — write it as the field's ` +
+        `\`description\`, which a registry keeps: ${helped.map((p) => `'${p}'`).join(', ')}.`
+    )
+  }
+  const ruled = fieldsWhere(normalized, (spec) => spec.constraints !== undefined && !isSectionShaped(spec))
+  if (ruled.length > 0) {
+    throw new Error(
+      `Data schema '${ref}': ${ruled.map((p) => `'${p}'`).join(', ')} declare${ruled.length === 1 ? 's' : ''} ` +
+        `\`constraints\` on a value — they are a section's rules, naming its fields: declare them in the ` +
+        `\`constraints:\` of the section that holds the field (beside \`fields:\` in a \`fields:\` schema).`
+    )
+  }
   return normalized
 }
 
-/** The dotted paths of every field in a normalized schema that declares a `default`. */
-function fieldsWithDefaults(schema) {
+// A field that lowers into a section — a nested object, an open map, a list of records — and so
+// may carry a section's `constraints`.
+function isSectionShaped(spec) {
+  if (spec.type === 'object') return true
+  return spec.type === 'array' && spec.items?.type === 'object'
+}
+
+/** The dotted paths of every field in a normalized schema that `test` holds for. */
+function fieldsWhere(schema, test) {
   const found = []
   const walkFields = (fields, prefix) => {
     if (!fields || typeof fields !== 'object') return
@@ -121,7 +148,7 @@ function fieldsWithDefaults(schema) {
   }
   const walkSpec = (spec, path) => {
     if (!spec || typeof spec !== 'object') return
-    if (spec.default !== undefined) found.push(path)
+    if (test(spec)) found.push(path)
     walkFields(spec.fields, `${path}.`)
     if (spec.items) walkSpec(spec.items, `${path}[]`)
     if (spec.values) walkSpec(spec.values, `${path}{}`)
@@ -292,6 +319,9 @@ export async function buildDataSchemaMap(refs, { srcDir }) {
       if (!map[target]) queue.push(target)
     }
   }
+  // A picklist names a section of the Model holding its choices — refused here, at the author's
+  // screen, when it names none (`optionsSectionPath`), rather than when the schema is registered.
+  assertOptionsTargets(map)
   return map
 }
 

package/src/uwx/data-schema.js

@@ -21,6 +21,8 @@
  * Pure — IR in, declaration out; no I/O, no uuids.
  */
 
+import { parseOptionsRef, FIELD_RULES } from '@uniweb/schemas/format'
+
 // Text kinds carry per-locale values when localized.
 const TEXT_KINDS = new Set(['string', 'text'])
 
@@ -110,9 +112,10 @@ export function isContentBodyField(field) {
  * @param {string} opts.name - the schema's registry name (`@org/x` or `@/x`).
  * @param {(ref: string) => string} [opts.resolveName] - maps a `ref` target name.
  *   Defaults to resolving `@/x` into the schema's own org, passing others through.
- * @param {(ref: string) => string} [opts.resolveOptions] - maps an `options`
- *   (item_ref) ref to its full `@org/model/<section>` path. Falls back to
- *   `resolveName` (model only) when not supplied.
+ * @param {(options: string, fieldPath: string) => string} [opts.resolveOptions] - maps an
+ *   `options` (item_ref) value to the `@org/model/<section-path>` the registry takes — a
+ *   register supplies it (`registry-package.js`), naming the section a short `'@/x'` means.
+ *   Falls back to `resolveName`, which resolves the scope and keeps the rest as written.
  * @returns {Object} the declaration (`{ name, label?, plural?, icon?, description?,
  *          source_locale?, linkable?, grantable?, sections }`).
  */
@@ -122,11 +125,33 @@ export function toDataSchemaDeclaration(normalized, { name, resolveName, resolve
     throw new Error('toDataSchemaDeclaration: a normalized schema is required')
   }
   const resolve = resolveName || defaultResolver(name)
-  const optResolve = resolveOptions || resolve
+  const resolveChoices = resolveOptions || resolve
+  // A picklist that names no list is refused naming the schema and the field — and so is one
+  // that picks from a section of its own schema (`OWN_SECTION`).
+  const optResolve = (options, fieldPath) => {
+    let resolved
+    try {
+      resolved = resolveChoices(options, fieldPath)
+    } catch (err) {
+      throw new Error(`Data schema '${name}': field '${fieldPath}' ${err.message}`)
+    }
+    if (typeof resolved === 'string' && resolved.startsWith(`${name}/`)) {
+      throw new Error(`Data schema '${name}': field '${fieldPath}' ${OWN_SECTION}`)
+    }
+    return resolved
+  }
 
-  const { sections, brief } = normalized.sections
-    ? lowerSectionsForm(normalized.sections, resolve, optResolve)
-    : lowerFieldsForm(normalized.fields || {}, resolve, optResolve)
+  let lowered
+  try {
+    lowered = normalized.sections
+      ? lowerSectionsForm(normalized.sections, resolve, optResolve)
+      : lowerFieldsForm(normalized.fields || {}, resolve, optResolve, normalized.constraints)
+  } catch (err) {
+    // A field the lowering refuses is named with its schema.
+    if (err.fieldPath !== undefined) throw new Error(`Data schema '${name}': ${err.message}`)
+    throw err
+  }
+  const { sections, brief } = lowered
 
   // The model-level sort axis is inline: `sort_date: true` on the brief's named
   // date field (replaces the old schema-level `sort_date_field` back-reference).
@@ -181,9 +206,10 @@ export function toDataSchemaDeclaration(normalized, { name, resolveName, resolve
 // only the recommended name for its card.
 export const SHORTHAND_SECTION = 'brief'
 
-function lowerFieldsForm(fields, resolve, optResolve) {
+// A `fields:` schema's top-level `constraints:` are its one section's rules (2026-10-15).
+function lowerFieldsForm(fields, resolve, optResolve, constraints) {
   return {
-    sections: { [SHORTHAND_SECTION]: lowerSection({ kind: 'single', brief: true, fields }, resolve, optResolve) },
+    sections: { [SHORTHAND_SECTION]: lowerSection({ kind: 'single', brief: true, fields, constraints }, resolve, optResolve) },
     brief: SHORTHAND_SECTION,
   }
 }
@@ -386,17 +412,17 @@ function lowerField(rawField, resolve, optResolve, path = '') {
       { ...rest, ...items, type: items ? items.type : 'json' },
       resolve,
       optResolve,
-      { multiple: true }
+      { multiple: true, path }
     )
   }
 
-  return lowerLeaf(field, resolve, optResolve)
+  return lowerLeaf(field, resolve, optResolve, { path })
 }
 
 // Lower a LEAF-SHAPED field — a scalar, a reference (`entity_ref`), or a curated
 // picklist (`item_ref`) — with or without `multiple`. The single place field
 // attributes are emitted, so every leaf-shaped kind carries the same set.
-function lowerLeaf(field, resolve, optResolve, { multiple = false } = {}) {
+function lowerLeaf(field, resolve, optResolve, { multiple = false, path = '' } = {}) {
   const leafType = field.type
 
   // `richtext` is NOT a kind — it is the author alias for a ProseMirror document
@@ -416,11 +442,30 @@ function lowerLeaf(field, resolve, optResolve, { multiple = false } = {}) {
   }
   const leafFormat = field.format
 
+  // A section's rules on a value have nowhere to go: the wire's `constraints` is a section key.
+  // A named schema refuses them before this (`resolve-data-schema.js`); refused here too, rather
+  // than dropped, which they were until 2026-10-15.
+  if (field.constraints !== undefined) {
+    throw Object.assign(
+      new Error(
+        `field '${path}' declares \`constraints\` on a value — they are a section's rules: declare them ` +
+          `in the \`constraints:\` of the section that holds it.`
+      ),
+      { fieldPath: path }
+    )
+  }
+
   const out = { type: leafType }
   if (multiple) out.multiple = true
   if (field.label) out.label = field.label
   if (field.description) out.description = field.description
   if (field.required) out.required = true
+  // A field's rules, as written — `max_length`, `min`, `max`, `mime_types`, `max_size`
+  // (`FIELD_RULES`): a registry keeps each as the field's own key and checks it on every
+  // write. ⛔ Until 2026-10-15 the normalizer dropped them before this saw them.
+  for (const key of Object.keys(FIELD_RULES)) {
+    if (field[key] !== undefined) out[key] = field[key]
+  }
 
   // A reference to a whole entity, hydrating to the target's brief. It is a
   // FIELD, so it carries field attributes — the same ones `item_ref` below has
@@ -435,10 +480,11 @@ function lowerLeaf(field, resolve, optResolve, { multiple = false } = {}) {
     return out
   }
 
-  // A curated picklist is an item_ref (machine-ish — never localized).
+  // A curated picklist is an item_ref (machine-ish — never localized), naming the section whose
+  // items are its choices (`optionsSectionPath`).
   if (field.options !== undefined) {
     out.type = 'item_ref'
-    out.options = optResolve(field.options)
+    out.options = optResolve(field.options, path)
     return out
   }
 
@@ -469,6 +515,142 @@ function lowerLeaf(field, resolve, optResolve, { multiple = false } = {}) {
   return out
 }
 
+// --- picklists ----------------------------------------------------------------
+
+// ⛔ A picklist cannot take its choices from a section of its own schema: a registry refuses it on
+// every register, whatever order the package lists its schemas in (measured 2026-10-15). Refused
+// here, at the author's screen, until a registry takes it.
+const OWN_SECTION =
+  'takes its choices from a section of its own schema, which a registry does not take — keep the list in a Model of its own.'
+
+/**
+ * ⭐ THE SECTION A PICKLIST'S CHOICES ARE IN — its path in the options Model, as the registry
+ * names it (2026-10-15). A field that picks from a list names the section holding the list:
+ * `options: '@/lists/countries'`, a nested one by its path (`'@/lists/countries/subdivisions'`).
+ * A Model whose top holds ONE list may be named alone — `'@/country'`, the `fields:` shorthand's
+ * one section, is the common case — and that list is the one meant.
+ *
+ * A register sends `@scope/name/<this path>` (`registry-package.js`): a registry takes an
+ * `item_ref`'s `options` as `@org/model/section-path` and refuses one that names no section
+ * (2026-10-15).
+ *
+ * ⛔ A Model with several lists at its top is refused when named alone: which one the author meant
+ * is not ours to guess. Until 2026-10-15 the first single-or-multi section was taken, and a path
+ * could not be written at all, so a Model's second list could never be a field's choices.
+ *
+ * @param {string} options - the field's `options:` as authored (`@/lists/countries`)
+ * @param {Object} target - the options Model, normalized
+ * @returns {string} the section's path in the Model (`countries`, `brief` for the shorthand)
+ * @throws when the path names no section, or a section that holds only sections, or is left out
+ *   of a Model whose top holds more than one list — naming the lists it has
+ */
+export function optionsSectionPath(options, target) {
+  const { model, path } = parseOptionsRef(options)
+  const sections = sectionPathsOf(target)
+  const lists = sections.filter((s) => s.holdsItems).map((s) => s.path)
+  const named = (paths) => paths.map((p) => `'${model}/${p}'`).join(', ')
+  if (path == null) {
+    const top = lists.filter((p) => !p.includes('/'))
+    if (top.length === 1) return top[0]
+    throw new Error(
+      top.length === 0
+        ? `takes its choices from '${options}', which holds no list at its top — name the section that holds them: ${named(lists) || '(it has none)'}.`
+        : `takes its choices from '${options}', which holds ${top.length} lists at its top — name the one: ${named(top)}.`
+    )
+  }
+  const found = sections.find((s) => s.path === path)
+  if (!found) {
+    throw new Error(`takes its choices from '${options}', but '${model}' has no section '${path}' — its lists: ${named(lists) || '(none)'}.`)
+  }
+  if (!found.holdsItems) {
+    const under = lists.filter((p) => p.startsWith(`${path}/`))
+    throw new Error(
+      `takes its choices from '${options}', a section that holds only sections, so it has no items to choose — ` +
+        `name a list under it: ${named(under) || '(it has none)'}.`
+    )
+  }
+  return path
+}
+
+/**
+ * Check every picklist in a closed map of normalized schemas against the Model it names, throwing
+ * for the first whose `options:` names no list (`optionsSectionPath`). A Model the map does not
+ * hold is skipped: resolving the graph fails on it first.
+ *
+ * @param {Object<string, Object>} dataSchemas - `{ [ref]: normalized }`, closed under references
+ */
+export function assertOptionsTargets(dataSchemas) {
+  for (const [ref, schema] of Object.entries(dataSchemas || {})) {
+    forEachOptionsField(schema, (fieldPath, options) => {
+      const { model } = parseOptionsRef(options)
+      if (model === ref) throw new Error(`Data schema '${ref}': field '${fieldPath}' ${OWN_SECTION}`)
+      const target = dataSchemas[model]
+      if (!target) return
+      try {
+        optionsSectionPath(options, target)
+      } catch (err) {
+        throw new Error(`Data schema '${ref}': field '${fieldPath}' ${err.message}`)
+      }
+    })
+  }
+}
+
+// Every field of a normalized schema that declares `options:`, with its dotted path — in any
+// section, nested object, list of records or open map.
+function forEachOptionsField(schema, fn) {
+  const visitField = (raw, path) => {
+    const field = asField(raw)
+    if (typeof field.options === 'string') fn(path, field.options)
+    if (field.items) visitField(field.items, path)
+    if (field.values) visitField(field.values, path)
+    for (const [key, child] of Object.entries(field.fields || {})) visitField(child, `${path}.${key}`)
+  }
+  const visitSection = (section, prefix) => {
+    for (const [key, field] of Object.entries(section?.fields || {})) visitField(field, `${prefix}${key}`)
+    for (const [name, child] of Object.entries(section?.sections || {})) visitSection(child, `${prefix}${name}.`)
+  }
+  if (schema?.fields) visitSection(schema, '')
+  for (const [name, section] of Object.entries(schema?.sections || {})) visitSection(section, `${name}.`)
+}
+
+// The sections of a normalized Model by the path the registry names each one by, and whether each
+// holds items — the lowering's own shapes (`lowerField`): a child in `sections:`, a nested object
+// (one record), a list of records, an open map (rows). A section holding only sections — a binder —
+// holds none.
+function sectionPathsOf(normalized) {
+  const out = []
+  const visit = (path, node) => {
+    out.push({ path, holdsItems: holdsItems(node) })
+    for (const [name, child] of Object.entries(node.sections || {})) visit(`${path}/${name}`, child)
+    for (const [name, field] of Object.entries(node.fields || {})) {
+      const nested = sectionOfField(field)
+      if (nested) visit(`${path}/${name}`, nested)
+    }
+  }
+  if (normalized?.fields) visit(SHORTHAND_SECTION, { kind: 'single', fields: normalized.fields })
+  for (const [name, section] of Object.entries(normalized?.sections || {})) visit(name, section)
+  return out
+}
+
+// The section a section-shaped FIELD lowers into (`lowerField`), or null for a leaf.
+function sectionOfField(raw) {
+  const field = asField(raw)
+  if (field.type === 'object') {
+    if (field.values !== undefined) return { kind: 'multi', fields: { [OPEN_MAP_KEY]: { type: 'string' }, ...asField(field.values).fields } }
+    return { kind: 'single', fields: field.fields }
+  }
+  if (field.type === 'array' && field.items && asField(field.items).type === 'object') {
+    return { kind: 'multi', fields: asField(field.items).fields }
+  }
+  return null
+}
+
+function holdsItems(section) {
+  if ((section.kind || 'single') === 'multi') return true
+  if (section.kind === 'binder') return false
+  return Object.values(section.fields || {}).some((field) => !sectionOfField(field))
+}
+
 // --- helpers -----------------------------------------------------------------
 
 function asField(def) {

package/src/uwx/registry-package.js

@@ -27,7 +27,8 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
 
 import { normalizeFoundationSchema } from '@uniweb/schemas/foundation'
-import { toDataSchemaDeclaration, SHORTHAND_SECTION } from './data-schema.js'
+import { parseOptionsRef } from '@uniweb/schemas/format'
+import { toDataSchemaDeclaration, optionsSectionPath } from './data-schema.js'
 import { checkFoundationName, splitFoundationName } from '../foundation-name.js'
 
 const FOUNDATION_SCHEMA = '@uniweb/foundation-schema'
@@ -155,7 +156,8 @@ function buildDataSchemaEntities(dataSchemas, scope) {
     .map(([ref, normalized]) => ({
       model: DATA_SCHEMA,
       // `name` resolved to the concrete scope; entity_ref `models` resolve the same
-      // way; item_ref `options` get the full `@org/x/<section>` path (§10.1).
+      // way; item_ref `options` name the section whose items are the choices
+      // (`@org/x/<section-path>`, `makeOptionsResolver`).
       ...toDataSchemaDeclaration(normalized, { name: scoped(ref), resolveName: scoped, resolveOptions }),
     }))
   return { entities: referencedFirst(entities), scoped, org }
@@ -279,27 +281,23 @@ function buildRefs(dataSchemas, scoped) {
   return Object.keys(dataSchemas).sort().map((ref) => ({ name: scoped(ref) }))
 }
 
-// Resolve an item_ref `options: '@/x'` to the full `@/x/<section>` path the
-// backend needs (it splits on the last `/`; a bare model mis-resolves — §10.1).
-// The section is the options model's single item-bearing (single/multi) section.
+// An item_ref's `options` as a registry takes it: `@scope/name/<section-path>`. A registry
+// refuses a path that names no section, and picks none for us (2026-10-15). The section is
+// the one the author named, or — for `'@/x'` alone — the options Model's one list
+// (`optionsSectionPath`, which refuses a Model with several).
+// ⛔ Until 2026-10-15 this took the Model's FIRST single-or-multi section, and this comment said
+// the registry "splits on the last `/`" — it does not, and a two-segment path is refused.
 function makeOptionsResolver(dataSchemas, scoped) {
-  return (ref) => {
-    const model = dataSchemas[ref]
-    if (!model) return scoped(ref)
-    const section = itemBearingSectionName(model, ref)
-    return section ? `${scoped(ref)}/${section}` : scoped(ref)
-  }
-}
-
-function itemBearingSectionName(normalized, ref) {
-  // fields-form → the shorthand's one section, always named `brief`
-  if (normalized.fields) return SHORTHAND_SECTION
-  // sections-form → the first item-bearing (single/multi) section
-  for (const [name, sec] of Object.entries(normalized.sections || {})) {
-    const kind = sec.kind || 'single'
-    if (kind === 'single' || kind === 'multi') return name
+  return (options) => {
+    const { model, path } = parseOptionsRef(options)
+    const target = dataSchemas[model]
+    if (target) return `${scoped(model)}/${optionsSectionPath(options, target)}`
+    if (path) return `${scoped(model)}/${path}`
+    throw new Error(
+      `takes its choices from '${options}', a Model this package does not define — name the section ` +
+        `that holds them: '${options}/<section>'.`
+    )
   }
-  return null
 }
 
 // Per-locale sidecar map from `<foundationDir>/i18n/<locale>.json`. `{}` when none.