@uniweb/core 0.27.0 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/core",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {
@@ -45,8 +45,8 @@
     "vitest": "^4.1.7"
   },
   "dependencies": {
-    "@uniweb/semantic-parser": "^1.4.0",
-    "@uniweb/theming": "^0.1.15"
+    "@uniweb/theming": "^0.1.15",
+    "@uniweb/semantic-parser": "^1.4.0"
   },
   "scripts": {
     "test": "vitest run"

package/src/field-path.js

@@ -0,0 +1,31 @@
+/**
+ * Field paths — the ONE rule for which dotted keys the query language admits.
+ *
+ * A `where` key and a `sort` field name a field of the record, or a path into it:
+ * `tenure.start`, `education.degree`. Every `.` is a step. ⭐ Two shapes are outside
+ * the language on both lanes (the records service's rule, stated by backend on
+ * 2026-09-14): a path with an **empty step** (`a..b`, `.a`, `a.`), and a path whose first
+ * step starts with **`$`** (`$meta.x`). A single `$` field — `$name`, `$uuid` — is not a
+ * path and stays a field. A `where` key outside the language selects no records; a
+ * `sort` field outside it is refused where it is authored.
+ *
+ * Zero-dependency leaf: the where evaluator and the sort evaluator both read it.
+ */
+
+/**
+ * Why a field key is outside the language, or null when it is inside.
+ *
+ * @param {string} key
+ * @returns {string|null} the problem, as a sentence
+ */
+export function fieldPathProblem(key) {
+  if (typeof key !== 'string' || key.indexOf('.') === -1) return null
+  const steps = key.split('.')
+  if (steps.some((step) => step === '')) {
+    return `\`${key}\` has an empty step — a path is field names joined by single dots`
+  }
+  if (steps[0].startsWith('$')) {
+    return `\`${key}\` starts with \`$\` — a path starts at one of the record's own fields`
+  }
+  return null
+}

package/src/sort.js

@@ -18,12 +18,14 @@
  * Dotted paths descend into nested objects (`tenure.start`) — kept, like the
  * predicate evaluator's.
  *
- * Zero-dependency leaf: `@uniweb/build` reads it to materialize `/data/<name>.json`
+ * Zero-dependency beyond the `field-path.js` leaf: `@uniweb/build` reads it to materialize `/data/<name>.json`
  * and `@uniweb/runtime` reads it as the fallback over a fetched array, so the two
  * lanes cannot drift on the one thing a conformance test would otherwise have to
  * catch by luck.
  */
 
+import { fieldPathProblem } from './field-path.js'
+
 /**
  * Parse an authored `sort:` into `{ field, desc }`.
  *
@@ -39,6 +41,7 @@ export function parseSort(sort) {
   if (sort === undefined || sort === null || sort === '') return null
   if (typeof sort === 'object') {
     if (typeof sort.field !== 'string' || sort.field.length === 0) return null
+    refuseFieldPath(sort.field, sort.field)
     return { field: sort.field, desc: sort.desc === true }
   }
   const text = String(sort).trim()
@@ -52,6 +55,7 @@ export function parseSort(sort) {
   if (text.startsWith('-')) {
     const field = text.slice(1).trim()
     if (!field || /\s/.test(field)) throw new Error(`[uniweb] sort: "${text}" is not a field name.`)
+    refuseFieldPath(field, text)
     return { field, desc: true }
   }
   const parts = text.split(/\s+/)
@@ -63,9 +67,16 @@ export function parseSort(sort) {
   if (lower !== 'asc' && lower !== 'desc') {
     throw new Error(`[uniweb] sort: "${text}" — direction must be \`asc\` or \`desc\`, not "${dir}".`)
   }
+  refuseFieldPath(field, text)
   return { field, desc: lower === 'desc' }
 }
 
+/** A sort field outside the language is refused where it is written (`field-path.js`). */
+function refuseFieldPath(field, text) {
+  const problem = fieldPathProblem(field)
+  if (problem) throw new Error(`[uniweb] sort: "${text}" — ${problem}.`)
+}
+
 /**
  * The service's spelling of a sort: `date` ascending, `-date` descending.
  *
@@ -81,29 +92,102 @@ export function sortToWire(sort) {
 /**
  * Sort records by one key. Returns a new array; the input is not mutated.
  *
- * Strings compare with `localeCompare` so `apple` sorts before `Banana`; anything
- * else compares with `<`/`>`, which is right for numbers and ISO date strings. A
- * record with no value for the key sorts as the empty string — first ascending,
- * last descending — which is what every previous evaluator did.
+ * ⭐ TEXT SORTS BY THE COLLATION OF THE PAGE'S LOCALE — ruled 2026-09-14 [Diego]: *"collation
+ * in the page's locale is the correct answer."* So `apple` sorts before `Banana`, and
+ * `Álvarez` before `Zamora` on a Spanish page, the way a reader of that language expects;
+ * the records service collates in the question's locale. The collation is the locale's
+ * default, with no options: no numeric ordering (`item 10` before `item 2`), and case and
+ * accents only break ties between the same letters. ⛔ Until then a text compared with
+ * `localeCompare` and no locale — the JavaScript runtime's own — so a browser and a host's
+ * prerender could order one list differently. With no locale, or one the runtime cannot
+ * collate, `en` stands in: the CLDR root order, which English does not tailor.
+ * Numbers, ISO dates and booleans compare as values.
+ *
+ * ⭐ A RECORD WITH NO VALUE FOR THE KEY SORTS LAST, IN EITHER DIRECTION, and records
+ * that compare equal keep their order — the language both lanes answer
+ * (`kb/frontend/contracts/site-queries.md` §1.4, as the records service built it on
+ * 2026-09-13). "No value" is what `exists: false` means: missing, `null`, `""` — and a
+ * list, since nothing says which member orders the record (a dotted path that meets
+ * a list reads no value). ⛔ Until 2026-09-14 a missing value sorted as the empty
+ * string — first ascending, last descending — so a static site and a hosted one put
+ * the same records in different places.
  *
  * @param {Array<Object>} items
  * @param {string|{field:string, desc?:boolean}|null|undefined} sort
+ * @param {Object} [options]
+ * @param {string|null} [options.locale] - the page's locale, which texts are collated in
  * @returns {Array<Object>}
  */
-export function sortRecords(items, sort) {
+export function sortRecords(items, sort, { locale = null } = {}) {
   const spec = parseSort(sort)
   if (!spec || !Array.isArray(items) || items.length === 0) return items
   const { field, desc } = spec
+  const collate = collatorFor(locale)
+  const compareValues = (a, b) => compareValuesIn(a, b, collate)
   return [...items].sort((a, b) => {
-    const av = readPath(a, field) ?? ''
-    const bv = readPath(b, field) ?? ''
-    const cmp = typeof av === 'string' && typeof bv === 'string'
-      ? av.localeCompare(bv)
-      : (av > bv ? 1 : av < bv ? -1 : 0)
-    return desc ? -cmp : cmp
+    const av = readPath(a, field)
+    const bv = readPath(b, field)
+    const aNone = !hasSortValue(av)
+    const bNone = !hasSortValue(bv)
+    // Last in either direction — so this is decided before `desc` flips anything.
+    if (aNone || bNone) return aNone === bNone ? 0 : (aNone ? 1 : -1)
+    return desc ? -compareValues(av, bv) : compareValues(av, bv)
   })
 }
 
+/** A value a record can be ordered by: not missing, `null`, `""` or a list. */
+function hasSortValue(v) {
+  if (v === undefined || v === null || v === '') return false
+  return !Array.isArray(v)
+}
+
+/**
+ * ⭐ TWO KINDS IN ONE FIELD ARE ORDERED BY KIND, THEN WITHIN THE KIND — booleans,
+ * numbers, texts, then anything else — the records service's comparator, stated by
+ * backend on 2026-09-14. A total order, so a sort never fails; `where` still holds no
+ * comparison across kinds. ⛔ Until then `<` / `>` coerced a number against a text.
+ *
+ * Two texts compare with `collate` — the page's locale (`sortRecords`).
+ */
+function compareValuesIn(a, b, collate) {
+  const ka = kindRank(a)
+  const kb = kindRank(b)
+  if (ka !== kb) return ka < kb ? -1 : 1
+  if (typeof a === 'string') return collate(a, b)
+  if (ka === KIND_OTHER) return 0
+  return a > b ? 1 : a < b ? -1 : 0
+}
+
+/** One `Intl.Collator` per locale, made on first use. */
+const collators = new Map()
+const FALLBACK_LOCALE = 'en'
+
+function collatorFor(locale) {
+  const wanted = typeof locale === 'string' && locale ? locale : FALLBACK_LOCALE
+  let compare = collators.get(wanted)
+  if (!compare) {
+    let collator
+    try {
+      collator = new Intl.Collator(wanted)
+    } catch {
+      // A tag the runtime cannot collate in (malformed, or unknown to its ICU data).
+      collator = new Intl.Collator(FALLBACK_LOCALE)
+    }
+    compare = collator.compare
+    collators.set(wanted, compare)
+  }
+  return compare
+}
+
+const KIND_OTHER = 3
+
+function kindRank(v) {
+  if (typeof v === 'boolean') return 0
+  if (typeof v === 'number') return 1
+  if (typeof v === 'string') return 2
+  return KIND_OTHER
+}
+
 function readPath(record, path) {
   if (!record || typeof record !== 'object') return undefined
   if (path.indexOf('.') === -1) return record[path]

package/src/where.js

@@ -66,13 +66,16 @@
  * empty argument. It never falls back to a wider answer. `whereOutsideLanguage`
  * says why, so a producer can refuse the declaration where the author wrote it.
  *
- * Dotted paths descend into nested objects: `tenure.start: { gte: 2015 }`. ⭐ A
+ * Dotted paths descend into nested objects: `tenure.start: { gte: 2015 }` — never one with
+ * an empty step, nor one starting at a `$` field (`field-path.js`). ⭐ A
  * path that meets a list descends into each item, and the values it reaches are
  * read as a list field — so `education.degree: PhD` matches a record any of whose
  * `education` entries has that degree. (Kept on this lane by ruling 2026-09-13
  * [Diego]; a host's records service may not answer them.)
  */
 
+import { fieldPathProblem } from './field-path.js'
+
 const OPERATORS = new Set([
   'eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'not_in', 'exists', 'contains', 'starts_with', 'ends_with',
 ])
@@ -145,7 +148,10 @@ function clauseProblem(key, value) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) return '`not` takes one object of conditions'
     return whereOutsideLanguage(value)
   }
-  // A field clause: a bare value, null, or an operator object.
+  // A field clause: a bare value, null, or an operator object — under a key that is a
+  // field or a path the language admits (`field-path.js`).
+  const pathProblem = fieldPathProblem(key)
+  if (pathProblem) return pathProblem
   if (value === null || typeof value !== 'object' || Array.isArray(value)) return null
   const ops = Object.keys(value)
   if (ops.length === 0) return `the condition on \`${key}\` is empty`