@uniweb/core 0.25.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/core",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {

package/src/entity-store.js

@@ -15,7 +15,7 @@
  */
 
 import { isFetchRefinement, resolveFetchConfigs, routeQuery, sectionFetches } from './fetch-config.js'
-import { fillRoutePattern, routeParamValue } from './route-match.js'
+import { fillRoutePattern, matchesRouteParam } from './route-match.js'
 import { sortRecords } from './sort.js'
 
 /**
@@ -288,7 +288,7 @@ export default class EntityStore {
           const { paramName, paramValue } = dynamicContext
           const items = cached.data
           let filtered = Array.isArray(items)
-            ? items.filter((item) => String(routeParamValue(item, paramName)) !== String(paramValue))
+            ? items.filter((item) => !matchesRouteParam(item, paramName, paramValue))
             : items
           if (order) filtered = this._sortItems(filtered, order)
           data[schema] = limit && Array.isArray(filtered) ? filtered.slice(0, limit) : filtered
@@ -314,7 +314,7 @@ export default class EntityStore {
           const { paramName, paramValue } = dynamicContext
           const items = cached.data
           const match = Array.isArray(items)
-            ? items.find((item) => String(routeParamValue(item, paramName)) === String(paramValue))
+            ? items.find((item) => matchesRouteParam(item, paramName, paramValue))
             : null
           if (!match) {
             data[schema] = []
@@ -422,7 +422,7 @@ export default class EntityStore {
         }
         const { paramName, paramValue } = dynamicContext
         let filtered = Array.isArray(records)
-          ? records.filter((item) => String(routeParamValue(item, paramName)) !== String(paramValue))
+          ? records.filter((item) => !matchesRouteParam(item, paramName, paramValue))
           : (records ?? [])
         if (order) filtered = this._sortItems(filtered, order)
         data[schema] = limit && Array.isArray(filtered) ? filtered.slice(0, limit) : filtered
@@ -460,7 +460,7 @@ export default class EntityStore {
         }
 
         const match = records?.find(
-          (item) => String(routeParamValue(item, paramName)) === String(paramValue)
+          (item) => matchesRouteParam(item, paramName, paramValue)
         ) ?? null
 
         if (!match) {

package/src/index.js

@@ -64,10 +64,13 @@ export {
   joinPathCapture,
   recordHandle,
   routeParamValue,
+  routeParamValues,
+  matchesRouteParam,
   routeRecordKey,
   routeBinding,
   routeParamName,
   parentRouteOf,
+  recordRouteBase,
 } from './route-match.js'
 export { isRichSchema } from './schemas.js'
 // ⛔ `Tracker` is NOT on the package entry. It is a FEATURE, not part of the

package/src/page.js

@@ -104,7 +104,7 @@ export default class Page {
     // Scroll position memory (for navigation restoration)
     this.scrollY = 0
 
-    // Fetch configuration (from page.yml data: field)
+    // Fetch configuration (page.yml's `fetch:`, or its `query:` shorthand, desugared at build)
     // Preserved at runtime so EntityStore can walk the page hierarchy
     this.fetch = pageData.fetch || null
 

package/src/route-match.js

@@ -95,6 +95,8 @@ export function isDynamicRoute(route) {
 
 /** The catch-all token, only as a pattern's final segment: `/:path*`. */
 const CATCH_ALL = new RegExp(`/:(${PARAM_NAME})\\*$`)
+/** A route whose LAST segment is a parameter — the page that addresses one record. */
+const RECORD_ROUTE = new RegExp(`/:(${PARAM_NAME})\\*?$`)
 
 /**
  * Compile a route pattern to an anchored regex plus its param names.
@@ -305,6 +307,58 @@ export function routeParamValue(record, paramName) {
   return record[paramName]
 }
 
+/**
+ * Every value a record offers for a route's param, as strings — one for a scalar,
+ * one per member for a `multi` field.
+ *
+ * ⭐ A `multi` FIELD MATCHES MEMBER-WISE (ruled 2026-09-12 [Diego]: *"if the code is
+ * natural for backend, I think it can be useful to match member-wise"*), and the
+ * case it is for is not tag pages: it is a Model field TYPED `multi` that holds one
+ * value — `department: ['biology']` — which an author routes as `[department]` and
+ * thinks of as a scalar. Matched whole, that page silently renders not-found.
+ *
+ * ⛔ A ROUTE FIELD THAT IS NOT UNIQUE MAKES TIES NORMAL. Two records holding `'a'`
+ * both claim `/tags/a`; the first wins, and *which* is first is this lane's order —
+ * the build's record order here, the service's storage order on a hosted site. They
+ * can differ, with no error on either. The static build warns when two records claim
+ * one route; `docs/reference/dynamic-routes.md` says it plainly.
+ *
+ * Empty and duplicate members drop, so a record can never claim `/tags/` or the same
+ * route twice. ⚠️ `undefined` drops too — it used to stringify to `'undefined'` and
+ * match a URL segment spelled that way.
+ *
+ * @param {Object} record
+ * @param {string} paramName
+ * @returns {string[]} the values, in the record's own order
+ */
+export function routeParamValues(record, paramName) {
+  const raw = routeParamValue(record, paramName)
+  const out = []
+  for (const value of Array.isArray(raw) ? raw : [raw]) {
+    if (value === undefined || value === null || value === '') continue
+    const text = String(value)
+    if (text === '' || out.includes(text)) continue
+    out.push(text)
+  }
+  return out
+}
+
+/**
+ * Does this record answer to this value for the route's param? The one comparison
+ * every lane makes — the SPA, the prefetch, the static build — so a URL that finds a
+ * record in one cannot miss it in another. Compared as STRINGS: a URL segment is
+ * text, so `'42'` matches a field holding `42`.
+ *
+ * @param {Object} record
+ * @param {string} paramName
+ * @param {string|number} value - the URL segment
+ * @returns {boolean}
+ */
+export function matchesRouteParam(record, paramName, value) {
+  const target = String(value)
+  return routeParamValues(record, paramName).some((held) => held === target)
+}
+
 /**
  * A parametric page's route binding — the param the record is matched on, its
  * value, and the route VARIABLES a query may reference. ONE implementation, for
@@ -391,6 +445,35 @@ export function parentRouteOf(route, { declared = null, has } = {}) {
   return has(up) ? up : null
 }
 
+/**
+ * The base route a record's URL composes onto, for a page that ADDRESSES ONE RECORD —
+ * or null when the page is not one.
+ *
+ * `/blog/:slug` → `/blog` · `/docs/:path*` → `/docs` · `/:slug` → `/`.
+ *
+ * ⭐ **The selection is the point, not the slicing.** A page addresses a record only
+ * when its route ENDS in a parameter. ⛔ A page nested inside a parametric one —
+ * `/members/:slug/cv` — does not, and returns null: composing a record onto it would
+ * produce `/members/:slug/alice`, a URL that ranks in an index and 404s on click
+ * (the failure hosting measured in their own fixture, 2026-09-12). A static page
+ * returns null too, so a page that merely fetches to render itself contributes
+ * nothing to a record index.
+ *
+ * Written for `@uniweb/projections`' `recordRoutes`, which pairs it with
+ * `routeQuery` to answer *which of a site's queries become detail pages, and at what
+ * base URL* — one mapping a consumer can call instead of re-deriving from page data.
+ *
+ * @param {string} route - a page's route, parametric or not
+ * @returns {string|null} the base route, or null when the page addresses no record
+ */
+export function recordRouteBase(route) {
+  if (typeof route !== 'string') return null
+  const r = normalizeRoute(route)
+  if (!RECORD_ROUTE.test(r)) return null
+  const cut = r.lastIndexOf('/')
+  return cut <= 0 ? '/' : r.slice(0, cut)
+}
+
 /**
  * Fill a route pattern's params from a record — the ONE encoder for a record's href.
  *
@@ -437,12 +520,15 @@ export function fillRoutePattern(pattern, values) {
     head = pattern.slice(0, tail.index)
   }
   const href = head.replace(new RegExp(`:(${PARAM_NAME})`, 'g'), (_, name) => {
-    const value = routeParamValue(values, name)
-    if (value === undefined || value === null || value === '') {
+    // ⭐ THE FIRST MEMBER of a `multi` field — a record has ONE canonical href, and
+    // every member routes to it (`routeParamValues`). Baked whole, a `['a','b']`
+    // field produced `/tags/a%2Cb`, a URL no lane matches.
+    const [value] = routeParamValues(values, name)
+    if (value === undefined) {
       missing = true
       return ''
     }
-    return encodeURIComponent(String(value))
+    return encodeURIComponent(value)
   })
   return missing ? null : href + tailHref
 }

package/src/website.js

@@ -11,7 +11,7 @@ import FetcherDispatcher from './fetcher-dispatcher.js'
 import ObservableState from './observable-state.js'
 import { normalizeSeo } from './seo.js'
 import { resolveDefaultLocale, localeLabel } from './locale-config.js'
-import { matchDynamicRoute, decodeRouteValue, routeParamValue, routeBinding, routeParamName, parentRouteOf } from './route-match.js'
+import { matchDynamicRoute, decodeRouteValue, matchesRouteParam, routeBinding, routeParamName, parentRouteOf } from './route-match.js'
 import { resolveFetchConfigs, routeQuery, sectionFetches } from './fetch-config.js'
 import { buildDetailConfig } from './detail-url.js'
 import { resolveService } from './services.js'
@@ -656,7 +656,7 @@ export default class Website {
       }
 
       if (!currentItem) {
-        currentItem = items.find(item => String(routeParamValue(item, paramName)) === String(paramValue)) ?? null
+        currentItem = items.find(item => matchesRouteParam(item, paramName, paramValue)) ?? null
       }
 
       if (currentItem) {