@uniweb/core 0.25.1 → 0.26.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/core",
-  "version": "0.25.1",
+  "version": "0.26.1",
   "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,14 @@ export {
   joinPathCapture,
   recordHandle,
   routeParamValue,
+  routeParamValues,
+  matchesRouteParam,
   routeRecordKey,
   routeBinding,
   routeParamName,
   parentRouteOf,
+  recordRouteBase,
+  findPageForRoute,
 } 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/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
 }
@@ -470,3 +556,49 @@ export function stripLocalePrefix(route, activeLocale, defaultLocale) {
   if (route.startsWith(`${prefix}/`)) return route.slice(prefix.length)
   return route
 }
+
+/**
+ * ⭐ **THE PAGE A ROUTE NAMES — one rule, for every lane that asks the question.**
+ *
+ * Exact match first, then the parametric pages in page order, which is the order
+ * `Website#getPage` uses in the SPA. Captured params are decoded by
+ * `matchDynamicRoute` (a catch-all per segment), so the values are what a site's
+ * query binds against.
+ *
+ * ⛔ **Why this is a leaf rather than a thing each lane composes.** More than one
+ * lane asks *which page does this path name* — the SPA, the runtime's server-side
+ * prefetch, and a host's router. Our leaves (`normalizeRoute`, `isDynamicRoute`,
+ * `routePatternToRegex`) were importable and the RULE was not, so a consumer
+ * imported the parts and wrote the composition itself. **A renamed export breaks
+ * loudly; a re-implemented rule drifts silently.** A hand-written matcher spelled
+ * `:(\w+)` accepts a different param alphabet than our `[A-Za-z0-9_-]+`, so a
+ * hyphenated slug resolves in one copy and 404s in the other, with nothing failing
+ * anywhere. Import this; do not rebuild it.
+ *
+ * ⚠️ **A trailing slash is the same route, on BOTH branches** (`normalizeRoute`),
+ * which is what `Website#getPage` has always done. The runtime's own prefetch copy
+ * compared raw strings until 2026-09-12 and so disagreed with the SPA about
+ * `/about/` — the exact class of split this function exists to end.
+ *
+ * ⚖️ Matching is not resolving: a hit means the ROUTE exists. Whether the record
+ * behind a parametric page exists is a data question answered later.
+ *
+ * @param {Array<Object>|{pages?: Array<Object>}} source - the pages, or a payload holding them
+ * @param {string} route - the concrete path
+ * @returns {{ page: Object|null, params: Record<string,string> }} `page` is null when nothing matches
+ */
+export function findPageForRoute(source, route) {
+  const pages = Array.isArray(source) ? source : source?.pages
+  const list = Array.isArray(pages) ? pages : []
+  const wanted = normalizeRoute(route)
+
+  for (const page of list) {
+    if (typeof page?.route === 'string' && normalizeRoute(page.route) === wanted) return { page, params: {} }
+  }
+  for (const page of list) {
+    if (typeof page?.route !== 'string' || !isDynamicRoute(page.route)) continue
+    const hit = matchDynamicRoute(page.route, wanted)
+    if (hit) return { page, params: hit.params }
+  }
+  return { page: null, params: {} }
+}

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) {