@uniweb/core 0.27.0 → 0.29.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,101 @@ 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 (as a host's
+ * records service answers it since 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,7 +12,8 @@ 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, pageRouteQuery, routeSelection, sectionFetches, siteReaches } from './fetch-config.js'
+import { resolveFetchConfigs, pageRouteQuery, recordPages, routeSelection, siteReaches } from './fetch-config.js'
+import { declaredKeys } from './data-keys.js'
 import { buildDetailConfig } from './detail-url.js'
 import { findLayoutEntry } from './layout-name.js'
 import { resolveService } from './services.js'
@@ -87,6 +88,8 @@ export default class Website {
     this.notFoundPage = null
     this._dynamicPageData = new Map()
     this._dynamicPageCache = new Map()
+    // query name → the page its records link to (`recordPageFor`), worked out on first ask
+    this._recordPages = null
     this.pages = []
     this.activePage = null
     this.pageRoutes = []
@@ -161,6 +164,7 @@ export default class Website {
       }
     }
     this._dynamicPageCache = new Map()
+    this._recordPages = null
 
     this.pages = regularPages.map((page, index) => new Page(page, index, this))
     this.buildPageHierarchy()
@@ -573,7 +577,7 @@ export default class Website {
     const { paramName, paramValue, variables } = routeBinding(templatePage.route, params, originalData.paramName)
 
     // Store dynamic context for components to access. ⛔ No `schema`: the key the
-    // URL narrows is worked out where it is read (`EntityStore._routeKey`), from
+    // URL narrows is worked out where it is read (`EntityStore._route`), from
     // the page, never stored beside it (deleted 2026-09-11).
     pageData.dynamicContext = {
       templateRoute: templatePage.route,
@@ -622,6 +626,10 @@ export default class Website {
       // visitor's page — the "write key ≠ read key" failure.
       let items = []
       let currentItem = null
+      // ⭐ On the records service the record's own question checks the route query's
+      // set (`buildDetailConfig`), so once it has answered, its answer is definitive —
+      // the record, or `[]` for not found — with no list to consult.
+      let recordAnswered = false
 
       if (this.fetcher) {
         // The same sources the store walks for a section that declares nothing,
@@ -654,10 +662,13 @@ export default class Website {
           const raw = detailCached?.data
           const record = Array.isArray(raw) ? raw[0] : raw
           if (record && typeof record === 'object') currentItem = record
+          if (fetchConfig.ask && detailCached && Array.isArray(raw)) recordAnswered = true
 
-          // ⛔ 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.
+          // ⭐ The route query's set (`routeSelection`) — the query as saved, its `limit`
+          // included, never a list a fetch narrowed: a record past a fetch's `limit` is a
+          // record, and one past the query's is not (ruled 2026-09-14 [Diego]). ⛔ Until
+          // 2026-09-13 this read the cut list and declared a record past a list's
+          // `limit` "Not found".
           const cached = this.fetcher.peek(routeSelection(fetchConfig), ctx)
           items = Array.isArray(cached?.data) ? cached.data : []
         }
@@ -672,8 +683,9 @@ export default class Website {
         if (currentItem.description || currentItem.excerpt) {
           pageData.description = currentItem.description || currentItem.excerpt
         }
-      } else if (items.length > 0) {
-        // The records are loaded but this ID isn't among them — definitive not found
+      } else if (items.length > 0 || recordAnswered) {
+        // The set is loaded and this ID isn't in it, or the record question answered
+        // `[]` — definitive not found
         pageData.title = 'Not found'
         pageData.notFound = true
       }
@@ -685,7 +697,7 @@ export default class Website {
       // 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
+      pageData._recordsLoaded = items.length > 0 || currentItem !== null || recordAnswered
     }
 
     // Create the page instance
@@ -875,43 +887,60 @@ export default class Website {
   }
 
   /**
-   * The parametric page that renders ONE record of a query — `{ route, paramName }`
-   * for the page whose route query (`routeQuery`) lands under `name`, or null when
-   * the site routes no such page.
-   *
-   * ⭐ This is how a caller outside a parametric page learns which record field
-   * the site's URL is built on: `kit`'s `useEntityDetail` asks it so a hover
-   * card and the page it links to address the record by the SAME field. It
-   * hardcoded `slug` until 2026-09-04, which was quietly wrong on any site
-   * routing `[id]`.
-   *
-   * `name` may be the binding key (`content.data.<key>`) or the query's name:
-   * `useEntityDetail` holds the query name, and the two differ under an `as:`
-   * override — which this matched by binding key only until 2026-09-11. The first
-   * page found wins, and only a page whose own folder is the parameter (a page
-   * nested inside one is not the record's page).
-   *
-   * @param {string} name - a binding key or a query name
+   * ⭐ THE `content.data` KEYS A COMPONENT RECEIVES — its `data:` (`meta.data`, as the build
+   * leans it), then its foundation's `main.js` `data:`, each with its schema ref
+   * (`declaredKeys`, `./data-keys.js`; ruled 2026-09-14 [Diego]). A component with no
+   * `data:` receives only its foundation's keys, which reach every section because its
+   * handlers run for every section.
+   *
+   * @param {Object|null} meta - the component's runtime meta (`uniweb.getComponentMeta`)
+   * @returns {Array<[string, string|null]>}
+   */
+  declaredKeys(meta) {
+    return declaredKeys(meta?.data, this._foundation?.default?.capabilities?.data)
+  }
+
+  /**
+   * ⭐ THE PAGE A QUERY'S RECORDS LINK TO — `{ route, paramName }`: the parametric page
+   * whose route query IS the query, by name, the first in page order (`recordPages`,
+   * `./fetch-config.js`), with its route translated for the active locale. Null when the
+   * site has no such page, and then a record of the query has no link.
+   *
+   * This is what fills a delivered record's `$route` (`EntityStore`) when its fetch picks
+   * no `detailPage`, and how a caller outside a parametric page learns which record field
+   * the page's URL is built on: `kit`'s `useEntityDetail` asks it so a hover card and the
+   * page it links to address the record by the SAME field.
+   *
+   * ⛔ Replaces `detailTemplateFor(name)` (2026-09-14), which matched a binding key OR a
+   * query name — so a page whose route query merely landed under the same key answered
+   * for another query's records.
+   *
+   * @param {string} query - a query's name
    * @returns {{ route: string, paramName: string } | null}
    */
-  detailTemplateFor(name) {
-    if (!name) return null
-    for (const data of this._dynamicPageData.values()) {
-      if (!data?.route || !/\/:[A-Za-z0-9_-]+\*?$/.test(data.route)) continue
-      const page = this.pages.find((p) => p.route === data.route)
-      const route = routeQuery({
-        page: data.fetch,
-        parent: page?.parent?.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),
+  recordPageFor(query) {
+    if (typeof query !== 'string' || !query) return null
+    if (!this._recordPages) {
+      // ⭐ Every page, by the route PATTERN it answers to — the entity store's reading
+      // (`_route`). A static build replaces a parametric page with one concrete page per
+      // record (`expandDynamicPages`), each carrying its template's route as
+      // `dynamicContext.templateRoute`; the payload it prerenders and hydrates holds those,
+      // and no template. ⛔ Read from the templates alone, this found no page there, and
+      // no record of a prerendered site had a link (measured on the `dynamic` template).
+      this._recordPages = recordPages(this.pages, {
+        routeOf: (page) => page?.dynamicContext?.templateRoute ?? page?.route,
+        parentOf: (page) => page?.parent ?? null,
+        fetchOf: (page) => page?.fetch,
+        sectionsOf: (page) => page?._bodySections,
+        site: this.config?.fetch,
       })
-      if (!route) continue
-      if (route.key === name || route.config?.query === name) {
-        return { route: data.route, paramName: routeParamName(data.route, data.paramName) }
-      }
     }
-    return null
+    const found = this._recordPages.get(query)
+    if (!found) return null
+    return {
+      route: this.translateRoute(found.route),
+      paramName: routeParamName(found.route, found.page?.dynamicContext?.paramName ?? found.page?.paramName),
+    }
   }
 
   /**

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`