@uniweb/core 0.31.0 → 0.32.0

package/package.json

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

package/src/fetch-config.js

@@ -688,9 +688,9 @@ function bindWhere(where, variables) {
 
 /**
  * ⭐ `scope:` IS ITS OWN FIELD, on both lanes. The service takes it natively; on
- * the compiled file the evaluators apply it to each record's placement (`path`,
- * the folder `records/folder.yml` put it in) — `@uniweb/core`'s `applyScope`, the one the
- * build uses too. ⛔ Until 2026-09-11 it was folded here into
+ * the compiled file the evaluators apply it to the branch each record is held with
+ * (`$branch`, the folder `records/folder.yml` put it in) — `@uniweb/core`'s `applyScope`,
+ * the one the build uses too. ⛔ Until 2026-09-11 it was folded here into
  * `where: { path: { under } }`, an authored form that is now retired in its
  * favour [Diego]: a branch is a scope, and `where` stays the author's predicate.
  *

package/src/index.js

@@ -55,9 +55,9 @@ export {
   isDataUrl
 } from './data-paths.js'
 export { evaluate as evaluateWhere, match as matchWhere, whereOutsideLanguage } from './where.js'
-// A query's `scope:` over records that carry their placement — read by the runtime's
-// default fetcher and by `@uniweb/build` when it compiles a query's file.
-export { applyScope, withinScope } from './scope.js'
+// A query's `scope:` over compiled records, which hold their branch under `BRANCH_KEY` —
+// read by the runtime's default fetcher and by `@uniweb/build`, which writes it.
+export { applyScope, withinScope, withoutBranch, BRANCH_KEY } from './scope.js'
 // The one sort evaluator and the one href encoder — both read by `@uniweb/build`
 // (materialization, the `route:` bake) and by `@uniweb/runtime` (the fallback),
 // which is what keeps the static and live lanes answering a query identically.

package/src/query-evaluation.js

@@ -24,7 +24,7 @@
  */
 
 import { match as matchWhere } from './where.js'
-import { applyScope } from './scope.js'
+import { applyScope, withoutBranch } from './scope.js'
 import { sortRecords, parseSort } from './sort.js'
 import { recordKeyValues } from './route-match.js'
 
@@ -42,7 +42,10 @@ import { recordKeyValues } from './route-match.js'
  * @returns {Array<Object>|*} the records the config selects, in its order
  */
 export function evaluateQuery(records, config, { locale = null, sort = sortRecords } = {}) {
-  if (!Array.isArray(records) || !config || typeof config !== 'object') return records
+  if (!Array.isArray(records)) return records
+  // ⛔ What this returns is an ANSWER, and no answer carries a record's branch: `scope` reads
+  // the one a compiled file holds, and it goes no further (`withoutBranch`, ruled 2026-09-27).
+  if (!config || typeof config !== 'object') return withoutBranch(records)
   const order = (items, expr) => sort(items, expr, { locale })
 
   let out = records
@@ -52,12 +55,12 @@ export function evaluateQuery(records, config, { locale = null, sort = sortRecor
   if (isLimit(config.limit)) out = out.slice(0, config.limit)
 
   const narrow = config.narrow
-  if (!narrow || typeof narrow !== 'object') return out
+  if (!narrow || typeof narrow !== 'object') return withoutBranch(out)
   if (narrow.where) out = matchWhere(narrow.where, out)
   if (narrow.match && typeof narrow.match === 'object') out = out.filter(matching(narrow.match))
   if (narrow.sort) out = order(out, narrow.sort)
   if (isLimit(narrow.limit)) out = out.slice(0, narrow.limit)
-  return out
+  return withoutBranch(out)
 }
 
 /**

package/src/route-match.js

@@ -228,8 +228,10 @@ export function splitPathCapture(capture) {
 }
 
 /**
- * The inverse of `splitPathCapture` — a record's own URL path under a
- * `[...path]` template, from its placement and its handle. `dir` may be empty.
+ * The inverse of `splitPathCapture` — a capture from its directory and its last
+ * segment. `dir` may be empty. ⛔ Not a record's URL: a record carries no branch, so its
+ * own URL under `[...path]` is its handle alone (`fillRoutePattern`). Until 2026-09-27 this
+ * composed a record's placement and handle into one.
  *
  * @param {{ dir?: string|null, slug?: string|null }} parts
  * @returns {string|null} null when there is no slug to name the record by
@@ -587,18 +589,17 @@ export function fillRoutePattern(pattern, values, { field = null } = {}) {
   let tailHref = ''
   const tail = pattern.match(CATCH_ALL)
   if (tail) {
-    // A catch-all is filled from the record's placement and handle — the split
-    // rule in reverse (`joinPathCapture`) — with each SEGMENT encoded and the
-    // slashes between them kept as structure. `dir` is the placement; a record
-    // carries it as `path` (the folder `records/folder.yml` put it in), which is why
-    // `path` here is read as the DIRECTORY and never as a composed capture.
+    // ⭐ A catch-all is filled with the record's handle ALONE — one segment, whatever it
+    // contains (a `/` inside it is a value). A record carries no branch [Diego,
+    // 2026-09-27], so its own URL under `[...path]` is the one it has under `[slug]`:
+    // `/logbook/<name>`. A URL that names a directory still reaches the page, and
+    // `scope: :dir` is what makes the directory count. ⛔ Until 2026-09-27 this prefixed the
+    // record's `path`, so one record was linked at `/logbook/field/river-survey` on a static
+    // site and at `/logbook/river-survey` where a records service, which answers no branch,
+    // served it.
     const [handle] = routeParamValues(values, 'slug', field)
-    if (joinPathCapture({ dir: values.dir ?? values.path, slug: handle }) === null) return null
-    const dir = String(values.dir ?? values.path ?? '')
-    const segments = dir.split('/').filter(Boolean).map((seg) => encodeURIComponent(seg))
-    // The handle is ONE segment whatever it contains: a `/` inside it is a value.
-    segments.push(encodeURIComponent(String(handle)))
-    tailHref = '/' + segments.join('/')
+    if (handle === undefined) return null
+    tailHref = '/' + encodeURIComponent(String(handle))
     head = pattern.slice(0, tail.index)
   }
   const href = head.replace(new RegExp(`:(${PARAM_NAME})`, 'g'), (_, name) => {

package/src/scope.js

@@ -1,11 +1,19 @@
 /**
- * A query's `scope:` — the folder branch it reads — evaluated over records that
- * carry their placement.
+ * A query's `scope:` — the folder branch it reads — evaluated over compiled records,
+ * which hold their branch.
  *
- * A record's `path` is the folder `records/folder.yml` placed it in (`build/src/site/
- * query-processor.js`). A scope contains that folder and every folder below it, at
- * SEGMENT boundaries: `field` holds `field` and `field/2025`, never `fieldwork`.
- * The root (`''`) holds everything.
+ * A compiled record holds the folder `records/folder.yml` placed it in under
+ * `$branch` (`BRANCH_KEY`, written by `build/src/site/query-processor.js`). A scope
+ * contains that folder and every folder below it, at SEGMENT boundaries: `field`
+ * holds `field` and `field/2025`, never `fieldwork`. The root (`''`) holds everything.
+ *
+ * ⛔ A RECORD DOES NOT CARRY ITS BRANCH (ruled 2026-09-27 [Diego]: *"branches are to
+ * organize the content pool … queries can filter by branch using `scope`"*). `$branch`
+ * is the compiled file's own key, there because the browser evaluates `scope` over that
+ * file. `evaluateQuery` reads it and answers no record with it (`withoutBranch`), just as
+ * a records service answers none. ⛔ Until then every compiled record carried `path`,
+ * which reached components, overwrote an authored field named `path`, and made a
+ * `[...path]` record's link `<branch>/<name>`.
  *
  * ⭐ Why this is its own field and not a `where` operator: a branch is a scope,
  * and `where` stays the author's predicate over the records' own fields. Ruled
@@ -18,6 +26,31 @@
  * Zero-dependency leaf.
  */
 
+/**
+ * The key a compiled record holds its branch under. The static lane's store only; no
+ * answer carries it.
+ */
+export const BRANCH_KEY = '$branch'
+
+/**
+ * Records as a query answers them: without the branch their compiled file holds. A list
+ * in which no record holds one is returned as it is.
+ *
+ * @param {Array<Object>} records
+ * @returns {Array<Object>}
+ */
+export function withoutBranch(records) {
+  if (!Array.isArray(records)) return records
+  if (!records.some((r) => r && typeof r === 'object' && Object.prototype.hasOwnProperty.call(r, BRANCH_KEY))) {
+    return records
+  }
+  return records.map((r) => {
+    if (!r || typeof r !== 'object' || !Object.prototype.hasOwnProperty.call(r, BRANCH_KEY)) return r
+    const { [BRANCH_KEY]: _branch, ...rest } = r
+    return rest
+  })
+}
+
 function trimSlashes(s) {
   return s.replace(/^\/+/, '').replace(/\/+$/, '')
 }
@@ -29,7 +62,7 @@ function trimSlashes(s) {
  * `2024`, the classic prefix bug, which silently returns records from a sibling
  * folder the author never named.
  *
- * @param {*} placement - a record's `path`
+ * @param {*} placement - a compiled record's branch (`BRANCH_KEY`)
  * @param {string} scope
  * @returns {boolean}
  */
@@ -52,5 +85,5 @@ export function withinScope(placement, scope) {
 export function applyScope(records, scope) {
   if (!Array.isArray(records)) return records
   if (typeof scope !== 'string' || trimSlashes(scope) === '') return records
-  return records.filter((r) => r && typeof r === 'object' && withinScope(r.path, scope))
+  return records.filter((r) => r && typeof r === 'object' && withinScope(r[BRANCH_KEY], scope))
 }