@uniweb/build 1.11.1 → 1.11.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@uniweb/build",
3
- "version": "1.11.1",
3
+ "version": "1.11.2",
4
4
  "description": "Build tooling for the Uniweb Component Web Platform",
5
5
  "type": "module",
6
6
  "exports": {
@@ -56,12 +56,12 @@
56
56
  "js-yaml": "^4.3.2",
57
57
  "sharp": "^0.35.5",
58
58
  "yaml": "^2.5.0",
59
- "@uniweb/content-writer": "~1.3.1",
60
- "@uniweb/schemas": "~1.6.5",
61
59
  "@uniweb/theming": "~1.2.1",
60
+ "@uniweb/schemas": "~1.6.6",
61
+ "@uniweb/semantic-parser": "~1.13.0",
62
62
  "@uniweb/content-reader": "~1.5.7",
63
- "@uniweb/projections": "~1.2.7",
64
- "@uniweb/semantic-parser": "~1.13.0"
63
+ "@uniweb/content-writer": "~1.3.1",
64
+ "@uniweb/projections": "~1.2.7"
65
65
  },
66
66
  "optionalDependencies": {
67
67
  "@uniweb/runtime": "~1.2.13"
@@ -40,7 +40,7 @@ import { existsSync, readdirSync, statSync } from 'node:fs'
40
40
  import { join, resolve, isAbsolute, extname, basename } from 'node:path'
41
41
  import { dataRefOf } from '@uniweb/core/data-keys'
42
42
  import { SYSTEM_RECORD_SCHEMAS } from '@uniweb/schemas/system'
43
- import { assertOptionsTargets } from './uwx/data-schema.js'
43
+ import { assertOptionsTargets, assertI18nPaths } from './uwx/data-schema.js'
44
44
  import { pathToFileURL } from 'node:url'
45
45
  import { createRequire } from 'node:module'
46
46
  import yaml from 'js-yaml'
@@ -321,7 +321,9 @@ export async function buildDataSchemaMap(refs, { srcDir }) {
321
321
  }
322
322
  // A picklist names a section of the Model holding its choices — refused here, at the author's
323
323
  // screen, when it names none (`optionsSectionPath`), rather than when the schema is registered.
324
+ // So does a translation whose path names no label of its schema (`assertI18nPaths`).
324
325
  assertOptionsTargets(map)
326
+ assertI18nPaths(map)
325
327
  return map
326
328
  }
327
329
 
@@ -119,7 +119,8 @@ export function isContentBodyField(field) {
119
119
  * register supplies it (`registry-package.js`), naming the section a short `'@/x'` means.
120
120
  * Falls back to `resolveName`, which resolves the scope and keeps the rest as written.
121
121
  * @returns {Object} the declaration (`{ name, label?, plural?, icon?, description?,
122
- * source_locale?, linkable?, grantable?, sections }`).
122
+ * source_locale?, linkable?, grantable?, sections, i18n }`) — `i18n` always, `{}`
123
+ * when the schema has no labels in other languages.
123
124
  */
124
125
  export function toDataSchemaDeclaration(normalized, { name, resolveName, resolveOptions } = {}) {
125
126
  if (!name) throw new Error('toDataSchemaDeclaration: a registry name is required')
@@ -191,9 +192,83 @@ export function toDataSchemaDeclaration(normalized, { name, resolveName, resolve
191
192
  if (normalized.grantable === false) decl.grantable = false
192
193
 
193
194
  decl.sections = sections
195
+
196
+ // `i18n` — the schema's labels in other languages — rides on every declaration, the whole
197
+ // set: `{}` when the schema has none. A registry leaves its stored translations alone when the
198
+ // key is absent, so a language taken out of the schema would never go. Each path must name a
199
+ // label of the sections above. Since 2026-10-28.
200
+ decl.i18n = lowerI18n(normalized.i18n, sections, name)
194
201
  return decl
195
202
  }
196
203
 
204
+ // --- i18n ----------------------------------------------------------------------
205
+
206
+ // A section of the lowered declaration by its full `/`-path from the root, or null.
207
+ function sectionAt(sections, path) {
208
+ const [first, ...rest] = path.split('/')
209
+ let section = sections[first]
210
+ for (const segment of rest) {
211
+ const child = section?.fields?.[segment]
212
+ section = child?.type === 'section' ? child : null
213
+ }
214
+ return section || null
215
+ }
216
+
217
+ // Every section's full `/`-path, depth first.
218
+ function sectionPaths(sections) {
219
+ const out = []
220
+ const visit = (path, section) => {
221
+ out.push(path)
222
+ for (const [key, field] of Object.entries(section?.fields || {})) {
223
+ if (field?.type === 'section') visit(`${path}/${key}`, field)
224
+ }
225
+ }
226
+ for (const [name, section] of Object.entries(sections || {})) visit(name, section)
227
+ return out
228
+ }
229
+
230
+ // Why a label path names no label of these sections, or null when it does.
231
+ function labelPathProblem(path, sections) {
232
+ if (/^model\.(?:label|plural|description)$/.test(path)) return null
233
+ const field = /^section\.(.+)\.field\.([^./]+)\.(?:label|description)$/.exec(path)
234
+ const section = field || /^section\.(.+)\.(?:label|description)$/.exec(path)
235
+ if (!section) return 'is not a label path'
236
+ const at = sectionAt(sections, section[1])
237
+ if (!at) {
238
+ const paths = sectionPaths(sections)
239
+ const full = paths.filter((p) => p.endsWith(`/${section[1]}`))
240
+ return full.length === 1
241
+ ? `names a nested section by its bare name — write its full path, '${full[0]}'`
242
+ : `names no section '${section[1]}' — this schema's are ${paths.map((p) => `'${p}'`).join(', ')}`
243
+ }
244
+ if (field && !at.fields?.[field[2]]) return `names no field '${field[2]}' in section '${section[1]}'`
245
+ return null
246
+ }
247
+
248
+ function lowerI18n(i18n, sections, name) {
249
+ const out = {}
250
+ for (const [language, labels] of Object.entries(i18n || {})) {
251
+ for (const path of Object.keys(labels || {})) {
252
+ const problem = labelPathProblem(path, sections)
253
+ if (problem) throw new Error(`Data schema '${name}': i18n '${language}': '${path}' ${problem}.`)
254
+ }
255
+ out[language] = { ...labels }
256
+ }
257
+ return out
258
+ }
259
+
260
+ /**
261
+ * Refuse an `i18n` path that names no label of its schema where schemas resolve — the foundation
262
+ * build and `uniweb validate` (`buildDataSchemaMap`) — rather than when the schema is registered.
263
+ *
264
+ * @param {Object<string, object>} dataSchemas - normalized schemas by ref
265
+ */
266
+ export function assertI18nPaths(dataSchemas) {
267
+ for (const [ref, schema] of Object.entries(dataSchemas || {})) {
268
+ if (schema?.i18n) toDataSchemaDeclaration(schema, { name: ref })
269
+ }
270
+ }
271
+
197
272
  // --- shapes ------------------------------------------------------------------
198
273
 
199
274
  // The `fields:` shorthand: a flat field set is ONE single section, named `brief` and
@@ -263,17 +338,25 @@ function lowerSection(def, resolve, optResolve, path = '') {
263
338
  if (def.nestable) out.self_nesting = true
264
339
  if (def.append_only) out.append_only = true
265
340
 
341
+ // Leaves and explicit child sections (sections-form, e.g. under a binder) share one ordered
342
+ // `fields:` namespace, a child as a `type: section` field. The two maps are lowered in the
343
+ // order the author wrote them, which the IR keeps (`@uniweb/schemas/format`), since a
344
+ // registry lists a definition's sections in the declared order. ⛔ Until 2026-10-28 every
345
+ // child section went after the leaves, wherever it was written.
266
346
  const fields = {}
267
- for (const [key, rawField] of Object.entries(def.fields || {})) {
268
- fields[key] = lowerField(rawField, resolve, optResolve, path ? `${path}/${key}` : key)
269
- }
270
- // Explicit child sections (sections-form, e.g. under a binder) → `type: section`
271
- // fields, in the same ordered namespace as the leaves.
272
- for (const [childName, childDef] of Object.entries(def.sections || {})) {
273
- const childPath = path ? `${path}/${childName}` : childName
274
- fields[childName] = {
275
- type: 'section',
276
- ...lowerSection(childDef, resolve, optResolve, childPath)
347
+ for (const part of Object.keys(def)) {
348
+ if (part === 'fields') {
349
+ for (const [key, rawField] of Object.entries(def.fields || {})) {
350
+ fields[key] = lowerField(rawField, resolve, optResolve, path ? `${path}/${key}` : key)
351
+ }
352
+ } else if (part === 'sections') {
353
+ for (const [childName, childDef] of Object.entries(def.sections || {})) {
354
+ const childPath = path ? `${path}/${childName}` : childName
355
+ fields[childName] = {
356
+ type: 'section',
357
+ ...lowerSection(childDef, resolve, optResolve, childPath)
358
+ }
359
+ }
277
360
  }
278
361
  }
279
362
  // A section with neither leaves nor sub-sections carries nothing, and is not a
@@ -4,10 +4,16 @@
4
4
  // ⛔ AN ITEM OF A LIST WITHOUT A `$uuid` IS A NEW ROW. A record's `many` sections are `multi`
5
5
  // sections on the backend, so a record re-sent with its list items uuid-less would insert them all
6
6
  // and delete every stored one. The backend refuses that, whole (`identity_required`, naming the
7
- // section) — measured 2026-09-25 on an edit of a talk whose `sessions` it held. A single section
8
- // needs nothing: its one item is matched by section. So every LIST of a record carries its items'
9
- // `$uuid`s once the backend holds them: a `many` section, a list nested in a section or in an
10
- // item, and a self-nesting list's `$children`, at every depth.
7
+ // section) — measured 2026-09-25 on an edit of a talk whose `sessions` it held. So every LIST of a
8
+ // record carries its items' `$uuid`s once the backend holds them: a `many` section, a list nested
9
+ // in a section or in an item, and a self-nesting list's `$children`, at every depth.
10
+ //
11
+ // ⭐ AND SO DOES A SINGLE SECTION UNDER A LIST. A single section with no list above it holds one
12
+ // item, matched by section, and needs nothing. Under a list it holds one item PER ITEM of the list
13
+ // (a degree's `thesis`), so a backend matches it by its `$uuid`, as a list element: sent without
14
+ // one, every push after the first is refused whole. It is banked at its place under its item
15
+ // (`degrees[0].thesis`), with no fingerprint, since its item's own match places it. ⛔ Until
16
+ // 2026-10-28 it was never banked, because a backend matched every single section by section.
11
17
  //
12
18
  // ⭐ BANKED PER RECORD, FROM WHAT WAS SENT AND WHAT CAME BACK. An item has no file and no name, so
13
19
  // nothing on disk can carry its identity — the fourth kind in the producer's ledger, beside
@@ -74,6 +80,18 @@ function eachList(def, value, prefix, visit) {
74
80
  }
75
81
  }
76
82
 
83
+ // Each single section of a container that the container holds a value for, by its path, and
84
+ // the single sections inside it: never into a list, whose items are visited as items. Called on
85
+ // an item of a list, so every section it visits has a list above it.
86
+ function eachSingle(def, value, prefix, visit) {
87
+ if (!isPlainObject(value)) return
88
+ for (const [key, field] of Object.entries(def?.fields || {})) {
89
+ if (field?.type !== 'section' || field.multiple === true || !isPlainObject(value[key])) continue
90
+ visit(`${prefix}${key}`, field, value[key])
91
+ eachSingle(field, value[key], `${prefix}${key}.`, visit)
92
+ }
93
+ }
94
+
77
95
  // Each list of a record document: its `many` sections, and the lists inside its single ones.
78
96
  function eachRecordList(declaration, document, visit) {
79
97
  for (const [name, def] of Object.entries(declaration?.sections || {})) {
@@ -95,18 +113,23 @@ function itemsOf(def, items) {
95
113
  nested[path] = itemsOf(d, list)
96
114
  })
97
115
  if (Object.keys(nested).length) node.c = nested
116
+ const singles = []
117
+ eachSingle(def, item, '', (path) => singles.push(path))
118
+ if (singles.length) node.s = singles
98
119
  return node
99
120
  })
100
121
  }
101
122
 
102
123
  /**
103
124
  * The lists of one record document, as sent: each list's items by path, each item its
104
- * fingerprint (`h`) and its own lists (`c`). What `harvestRecordItems` pairs with the
105
- * document the backend returns. Not stored — a bank is (`harvestRecordItems`).
125
+ * fingerprint (`h`), its own lists (`c`) and the paths of the single sections under it (`s`).
126
+ * What `harvestRecordItems` pairs with the document the backend returns. Not stored — a bank
127
+ * is (`harvestRecordItems`).
106
128
  *
107
129
  * @param {object} document - the record's `$`-document
108
130
  * @param {object} declaration - its data schema's declaration (`{ name, sections }`)
109
- * @returns {Object<string, Array<{ h: string, c?: object }>>} empty when the record has no list
131
+ * @returns {Object<string, Array<{ h: string, c?: object, s?: string[] }>>} empty when the
132
+ * record has no list
110
133
  */
111
134
  export function recordItemLists(document, declaration) {
112
135
  const lists = {}
@@ -136,6 +159,11 @@ function pairItems(ours, theirs, at, bank) {
136
159
  if (!uuid) return
137
160
  const place = `${at}[${k}]`
138
161
  bank[place] = exact ? `${uuid} ${ours[k].h}` : uuid
162
+ // A single section under the item, at its place under it: the uuid alone.
163
+ for (const path of ours[k]?.s || []) {
164
+ const single = uuidOf(valueAt(item, path))
165
+ if (single) bank[`${place}.${path}`] = single
166
+ }
139
167
  for (const [path, sub] of Object.entries(ours[k]?.c || {})) {
140
168
  const list = valueAt(item, path)
141
169
  if (Array.isArray(list)) pairItems(sub, list, `${place}.${path}`, bank)
@@ -164,18 +192,19 @@ export function harvestRecordItems(lists, returned) {
164
192
  // A list in the backend's document: an array of items that each carry a `$uuid`.
165
193
  const isStoredList = (v) => Array.isArray(v) && v.length > 0 && v.every((item) => uuidOf(item))
166
194
 
167
- function storedLists(container, prefix, bank) {
195
+ function storedLists(container, prefix, bank, underList = false) {
168
196
  for (const [key, value] of Object.entries(container || {})) {
169
197
  if (key.startsWith('$') && key !== '$children') continue
170
198
  if (isStoredList(value)) {
171
199
  value.forEach((item, k) => {
172
200
  const place = `${prefix}${key}[${k}]`
173
201
  bank[place] = item.$uuid
174
- storedLists(item, `${place}.`, bank)
202
+ storedLists(item, `${place}.`, bank, true)
175
203
  })
176
204
  } else if (uuidOf(value)) {
177
- // A section: its lists sit under its name.
178
- storedLists(value, `${prefix}${key}.`, bank)
205
+ // A section: its lists sit under its name. A single one under a list is banked too.
206
+ if (underList) bank[`${prefix}${key}`] = value.$uuid
207
+ storedLists(value, `${prefix}${key}.`, bank, underList)
179
208
  }
180
209
  }
181
210
  }
@@ -187,7 +216,8 @@ function storedLists(container, prefix, bank) {
187
216
  *
188
217
  * Read by shape: a list is an array whose every item carries a `$uuid`, and a section is an
189
218
  * object carrying one — a reference is a string or an `{ schema, entity }`, and a localized
190
- * value a `{ lang: … }` map, neither of which does.
219
+ * value a `{ lang: … }` map, neither of which does. A section under a list is banked at its
220
+ * place, as `harvestRecordItems` banks it.
191
221
  *
192
222
  * @param {object} returned - the backend's document for one record
193
223
  * @returns {Object<string, string>} place → `"<uuid>"`
@@ -240,8 +270,19 @@ function matchItems(prints, banked) {
240
270
  return assigned
241
271
  }
242
272
 
243
- function stampList(def, items, at, lists, counts, claimed) {
244
- const banked = (at !== null && lists.get(at)) || []
273
+ // The bank's single sections — a place that does not end in an index — place → uuid.
274
+ function bankedSingles(bank) {
275
+ const singles = new Map()
276
+ for (const [place, value] of Object.entries(bank || {})) {
277
+ if (/\]$/.test(place) || typeof value !== 'string') continue
278
+ const [u] = value.split(' ')
279
+ if (u) singles.set(place, u)
280
+ }
281
+ return singles
282
+ }
283
+
284
+ function stampList(def, items, at, banks, counts, claimed) {
285
+ const banked = (at !== null && banks.lists.get(at)) || []
245
286
  const assigned = matchItems(items.map((item) => fingerprint(def, item)), banked)
246
287
  items.forEach((item, i) => {
247
288
  const b = assigned[i]
@@ -252,11 +293,24 @@ function stampList(def, items, at, lists, counts, claimed) {
252
293
  } else {
253
294
  counts.unknown++
254
295
  }
255
- // An item's own lists are banked under the place of the item it matched — a new item's
256
- // nested items are new too.
296
+ // An item's own lists, and its single sections, are banked under the place of the item it
297
+ // matched — a new item's nested items are new too.
257
298
  const under = b && item.$uuid === b.u ? b.place : null
299
+ if (under !== null) {
300
+ eachSingle(def, item, '', (path, d, single) => {
301
+ const u = banks.singles.get(`${under}.${path}`)
302
+ if (u && !claimed.has(u)) {
303
+ single.$uuid = u
304
+ claimed.add(u)
305
+ counts.stamped++
306
+ } else {
307
+ // Under an item the backend holds, with no identity here: one the backend may hold.
308
+ counts.unbankedSingles++
309
+ }
310
+ })
311
+ }
258
312
  eachList(def, item, '', (path, d, list) =>
259
- stampList(d, list, under === null ? null : `${under}.${path}`, lists, counts, claimed)
313
+ stampList(d, list, under === null ? null : `${under}.${path}`, banks, counts, claimed)
260
314
  )
261
315
  })
262
316
  }
@@ -268,14 +322,17 @@ function stampList(def, items, at, lists, counts, claimed) {
268
322
  * @param {object} declaration - its data schema's declaration
269
323
  * @param {Object<string,string>} bank - this record's entry (`harvestRecordItems` /
270
324
  * `storedRecordItems`)
271
- * @returns {{ stamped: number, unknown: number }} items given a uuid, and items sent as new
325
+ * @returns {{ stamped: number, unknown: number, unbankedSingles: number }} items given a
326
+ * uuid; list items sent as new; and single sections under an item that kept its uuid but
327
+ * with none banked for them, which a backend may hold (a bank from before 2026-10-28 has
328
+ * none), so the caller can recover them
272
329
  */
273
330
  export function stampRecordItems(document, declaration, bank) {
274
- const counts = { stamped: 0, unknown: 0 }
331
+ const counts = { stamped: 0, unknown: 0, unbankedSingles: 0 }
275
332
  const claimed = new Set()
276
- const lists = bankedLists(bank)
333
+ const banks = { lists: bankedLists(bank), singles: bankedSingles(bank) }
277
334
  eachRecordList(declaration, document, (path, def, items) => {
278
- stampList(def, items, path, lists, counts, claimed)
335
+ stampList(def, items, path, banks, counts, claimed)
279
336
  })
280
337
  return counts
281
338
  }
@@ -554,6 +554,10 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
554
554
  const n = stampRecordItems(e.document, declaration, banked)
555
555
  recordItemIdentity.stamped += n.stamped
556
556
  recordItemIdentity.unknown += n.unknown
557
+ // A single section under an item the backend holds, banked nowhere — a bank from before such
558
+ // sections were banked (2026-10-28) — is recovered as an unbanked record's items are: sent
559
+ // without its `$uuid`, a push after the first is refused whole.
560
+ if (n.unbankedSingles > 0) unbankedIds.add(e.id)
557
561
  }
558
562
 
559
563
  const siteEntity = siteDoc