@uniweb/core 0.26.2 → 0.28.0

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/website.js

@@ -12,8 +12,9 @@ import ObservableState from './observable-state.js'
 import { normalizeSeo } from './seo.js'
 import { resolveDefaultLocale, localeLabel } from './locale-config.js'
 import { matchDynamicRoute, decodeRouteValue, matchesRouteParam, routeBinding, routeParamName, parentRouteOf } from './route-match.js'
-import { resolveFetchConfigs, routeQuery, sectionFetches } from './fetch-config.js'
+import { resolveFetchConfigs, routeQuery, pageRouteQuery, routeSelection, sectionFetches, siteReaches } from './fetch-config.js'
 import { buildDetailConfig } from './detail-url.js'
+import { findLayoutEntry } from './layout-name.js'
 import { resolveService } from './services.js'
 
 /**
@@ -589,18 +590,21 @@ export default class Website {
     }
 
     // Try to resolve page metadata from DataStore: the record the page is about,
-    // from its ROUTE QUERY (`routeQuery`) — the page's own query, its parent's, the
-    // site's, or its sections' shared key — read off the same parent the entity
-    // store reads (`templatePage.parent`, linked by the one parent rule). ⛔ Until
-    // 2026-09-11 this probed only a parent found by stripping the route down to
-    // `/` (so a top-level page probed the homepage) and only that parent's fetch,
-    // so a page whose route query was its own or the site's never got its title.
+    // from its ROUTE QUERY — the page's own query, its parent's, the site's, or its
+    // sections' shared key, chosen at the page that captured the URL's variable
+    // (`pageRouteQuery`; a nested page's is its parametric ancestor's) — read off the
+    // same parents the entity store reads (`page.parent`, linked by the one parent
+    // rule). ⛔ Until 2026-09-11 this probed only a parent found by stripping the
+    // route down to `/` (so a top-level page probed the homepage) and only that
+    // parent's fetch, so a page whose route query was its own or the site's never
+    // got its title.
     const parentPage = templatePage.parent
-    const route = routeQuery({
-      page: originalData.fetch,
-      parent: parentPage?.fetch,
+    const route = pageRouteQuery(templatePage, {
+      routeOf: (p) => p?.route,
+      parentOf: (p) => p?.parent ?? null,
+      fetchOf: (p) => (p === templatePage ? originalData.fetch : p?.fetch),
+      sectionsOf: (p) => (p === templatePage ? originalData.sections : p?._bodySections),
       site: this.config?.fetch,
-      sections: sectionFetches(originalData.sections),
     })
 
     if (route && paramValue !== undefined) {
@@ -621,9 +625,10 @@ export default class Website {
 
       if (this.fetcher) {
         // The same sources the store walks for a section that declares nothing,
-        // plus the declaring section's config when the key came from the sections.
+        // plus the route binding itself — which sits above the parent on a nested
+        // page, or on a section when the key came from the sections.
         const fetchConfig = resolveFetchConfigs(
-          [originalData.fetch, parentPage?.fetch, this.config?.fetch, route.level === 'sections' ? route.config : null],
+          [originalData.fetch, parentPage?.fetch, route.config, siteReaches(parentPage) ? this.config?.fetch : null],
           {
             schemas: [route.key],
             locale: this.getActiveLocale(),
@@ -650,7 +655,10 @@ export default class Website {
           const record = Array.isArray(raw) ? raw[0] : raw
           if (record && typeof record === 'object') currentItem = record
 
-          const cached = this.fetcher.peek(fetchConfig, ctx)
+          // ⛔ The route query's whole selection (`routeSelection`), never a list its
+          // `limit` cut: a record past the limit is a record, and until 2026-09-13
+          // this declared its page "Not found" because the cut list was loaded.
+          const cached = this.fetcher.peek(routeSelection(fetchConfig), ctx)
           items = Array.isArray(cached?.data) ? cached.data : []
         }
       }
@@ -674,8 +682,8 @@ export default class Website {
       // Note: the matched record and the sibling list are intentionally NOT
       // stored on dynamicContext — nothing reads them (its shape is
       // { templateRoute, params, paramName, paramValue }; the record reaches
-      // components via content.data, siblings via
-      // `fetch: { refine: true, detail: false }`). The local
+      // components via content.data, the others via
+      // `fetch: { query, current: exclude }`). The local
       // `currentItem`/`items` above drive title/description/notFound.
       pageData._recordsLoaded = items.length > 0 || currentItem !== null
     }
@@ -721,10 +729,7 @@ export default class Website {
   getRemoteLayout(layoutName) {
     const config = globalThis.uniweb?.foundationConfig
     if (!config?.layouts) return null
-    if (layoutName && config.layouts[layoutName]) {
-      return config.layouts[layoutName]
-    }
-    return null
+    return findLayoutEntry(config.layouts, layoutName) ?? null
   }
 
   /**
@@ -753,8 +758,11 @@ export default class Website {
    * @returns {Block[]|null}
    */
   getAreaBlocks(areaName, layoutName) {
-    if (layoutName && this._layoutSets[layoutName]) {
-      return this._layoutSets[layoutName][areaName]?.bodyBlocks || null
+    // A named layout's areas are its own: an area it lacks is absent, never
+    // borrowed from the default layout.
+    const named = findLayoutEntry(this._layoutSets, layoutName)
+    if (named) {
+      return named[areaName]?.bodyBlocks || null
     }
     // Fallback to 'default' layout
     if (this._layoutSets.default) {
@@ -769,8 +777,7 @@ export default class Website {
    * @returns {Object} Map of areaName -> Block[]
    */
   getLayoutAreas(layoutName) {
-    const setName = layoutName || 'default'
-    const layoutSet = this._layoutSets[setName] || this._layoutSets.default
+    const layoutSet = findLayoutEntry(this._layoutSets, layoutName || 'default') || this._layoutSets.default
     if (!layoutSet) return {}
 
     const areas = {}
@@ -788,7 +795,7 @@ export default class Website {
    * @returns {Object|null} Layout meta { areas, transitions, defaults }
    */
   getLayoutMeta(layoutName) {
-    return globalThis.uniweb?.foundationConfig?.layoutMeta?.[layoutName] || null
+    return findLayoutEntry(globalThis.uniweb?.foundationConfig?.layoutMeta, layoutName) || null
   }
 
   /**
@@ -895,7 +902,8 @@ export default class Website {
       const route = routeQuery({
         page: data.fetch,
         parent: page?.parent?.fetch,
-        site: this.config?.fetch,
+        // the site's binding is a route query for a top-level page only (`siteReaches`)
+        site: siteReaches(page?.parent) ? this.config?.fetch : null,
         sections: sectionFetches(data.sections),
       })
       if (!route) continue