@uniweb/core 0.28.0 → 0.29.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/core",
-  "version": "0.28.0",
+  "version": "0.29.1",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {
@@ -8,6 +8,7 @@
     "./base-path": "./src/base-path.js",
     "./records-service": "./src/records-service.js",
     "./data-paths": "./src/data-paths.js",
+    "./data-keys": "./src/data-keys.js",
     "./datastore": "./src/datastore.js",
     "./detail-url": "./src/detail-url.js",
     "./fetch-config": "./src/fetch-config.js",
@@ -45,8 +46,8 @@
     "vitest": "^4.1.7"
   },
   "dependencies": {
-    "@uniweb/theming": "^0.1.15",
-    "@uniweb/semantic-parser": "^1.4.0"
+    "@uniweb/semantic-parser": "^1.4.0",
+    "@uniweb/theming": "^0.1.15"
   },
   "scripts": {
     "test": "vitest run"

package/src/block.js

@@ -111,6 +111,13 @@ export default class Block {
       }
     }
 
+    // ⭐ WHAT THE SECTION HOLDS before any fetch answers it: its tagged data blocks, and
+    // its own fetches' answers a static build prerendered into it, by key. A declared key
+    // it holds is filled from here first (`runtime/src/prepare-props.js`), and a fetch
+    // whose answer is here is not asked again (`EntityStore`). Kept apart from
+    // `parsedContent.data`, which each render rebuilds from the declared keys.
+    this.heldData = this.parsedContent.data || {}
+
     // Flat content structure - no more nested main/items
     // parsedContent now has: title, pretitle, paragraphs, links, images, items, etc.
     this.items = this.parsedContent.items || []

package/src/data-keys.js

@@ -0,0 +1,155 @@
+/**
+ * ⭐ WHAT A SECTION RECEIVES — the keys its component declares, and which fetch fills each.
+ * Ruled 2026-09-14 [Diego]:
+ *
+ *   - **`content.data` holds every key the component declares — in its `meta.js` `data:`,
+ *     and in its foundation's `main.js` `data:` — and nothing else.** A component with no
+ *     `data:` receives none of its own; a foundation's keys reach every section, since its
+ *     handlers run for every section.
+ *   - **Which fetch fills a declared key** — automatic `as`: the fetches reaching a section
+ *     are taken one level at a time, most specific first; within a level, a fetch fills
+ *     its own key when the component declares it, and the fetches whose keys it does not
+ *     declare fill its still-empty keys of their query's schema, in order.
+ *
+ * ⛔ Until then `content.data` held every key that reached a section — every fetch of the
+ * section, its page, its parent and the site, and every tagged block — and a key reached
+ * a component only under the name the fetch was given (`as`), so a component naming its
+ * key differently received nothing.
+ *
+ * Plain data in and out, like `routeQuery`, so the entity store, the editor and anything
+ * else that shows what a section receives call these and keep no copy.
+ *
+ * @module
+ */
+
+import { fetchEntries } from './fetch-config.js'
+
+/**
+ * A declared key's schema ref, as `data:` spells it: a ref string (`'@std/article'`), an
+ * entry naming one (`{ schema: '@/member' }`), or null for an inline shape — a field map
+ * or a form — which names no schema.
+ *
+ * @param {*} value - one `data:` entry's value, authored or leaned
+ * @returns {string|null}
+ */
+function refOf(value) {
+  if (typeof value === 'string') return value || null
+  if (value && typeof value === 'object' && typeof value.schema === 'string') return value.schema || null
+  return null
+}
+
+/**
+ * The keys a section's component receives, in order, each with its schema ref — its
+ * component's `data:` first, then its foundation's. A key both declare is the
+ * component's.
+ *
+ * `data: false`, a missing `data:` or anything that is not a map declares nothing. Each
+ * value may be as authored or as the build leans it (`{ key: ref|null }`).
+ *
+ * @param {Object|false|null|undefined} componentData - the component's `data:`
+ * @param {Object|false|null|undefined} [foundationData] - its foundation's `main.js` `data:`
+ * @returns {Array<[string, string|null]>}
+ */
+export function declaredKeys(componentData, foundationData = null) {
+  const out = []
+  const seen = new Set()
+  for (const data of [componentData, foundationData]) {
+    if (!data || typeof data !== 'object' || Array.isArray(data)) continue
+    for (const [key, value] of Object.entries(data)) {
+      if (!key || seen.has(key)) continue
+      seen.add(key)
+      out.push([key, refOf(value)])
+    }
+  }
+  return out
+}
+
+/**
+ * Do two schema refs name the same schema?
+ *
+ * ⭐ `@/<name>` is "this project's own `<name>`", and what that project is differs by who
+ * wrote it: in a foundation's `meta.js` it is the foundation's schema, in a site's
+ * `queries.yml` the site's — and a site synced to a host has its queries' `@/` refs
+ * qualified with its org (`@acme/member`). So a local ref matches a ref of ANY scope with
+ * the same name; two scoped refs match only when their scopes agree. Decided 2026-09-14
+ * (the plan's §7 left it to framework): `@/member` and `@acme/member` match,
+ * `@std/person` and `@acme/person` do not.
+ *
+ * @param {string|null|undefined} a
+ * @param {string|null|undefined} b
+ * @returns {boolean}
+ */
+export function sameSchema(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string' || !a || !b) return false
+  if (a === b) return true
+  const pa = parseRef(a)
+  const pb = parseRef(b)
+  if (!pa || !pb || pa.name !== pb.name) return false
+  return pa.scope === pb.scope || pa.scope === '' || pb.scope === ''
+}
+
+/** `@scope/name` → `{ scope, name }`, `''` for a local `@/name`; null for anything else. */
+function parseRef(ref) {
+  const m = /^@([^/]*)\/([^/]+)$/.exec(ref)
+  return m ? { scope: m[1], name: m[2] } : null
+}
+
+/**
+ * ⭐ WHICH FETCH FILLS EACH DECLARED KEY — automatic `as`, ruled 2026-09-14 [Diego].
+ *
+ * The levels are the fetches reaching a section, most specific first — its own, its
+ * page's, its parent page's, a nested page's route binding, the site's (the sources
+ * `resolveFetchConfigs` takes). Within a level each fetch's key is its `as`, which is its
+ * query's name unless the author wrote another, and:
+ *
+ *   1. **a fetch fills its key**, if the component declares it;
+ *   2. **the fetches whose keys the component does not declare fill its still-empty keys
+ *      of their query's schema, in order** — the first such fetch, in the order written,
+ *      fills the first such key, in the order `data:` lists them, and the next fetch the
+ *      next key (`sameSchema`).
+ *
+ * A key filled at one level is not refilled by a less specific one, and a key the section
+ * already holds — a tagged data block in it (`held`) — is filled before any fetch. Where
+ * two fetches could fill one key, the first does. A fetch that fills nothing is not in
+ * the answer, and so is not asked for.
+ *
+ * The mapping says where an answer lands; it renames no fetch. A fetch keeps its `as`
+ * for its question, its cache key and its prefetch.
+ *
+ * @param {Array<[string, string|null]>} declared - `declaredKeys`
+ * @param {Array<*>} levels - each level's `fetch`, most specific first; falsy levels skipped
+ * @param {Object} [options]
+ * @param {Object|null} [options.queries] - the site's `config.queries`, for each fetch's
+ *   query's schema
+ * @param {Iterable<string>} [options.held] - declared keys the section already fills
+ * @returns {Map<string, { fetch: Object, level: number, index: number }>} declared key →
+ *   the fetch that fills it, as the level spells it (with its `as`), the level it came
+ *   from and its place in that level; in the order `declared` lists the keys
+ */
+export function fillDeclaredKeys(declared, levels, { queries = null, held = [] } = {}) {
+  const refs = new Map(declared)
+  const filled = new Map()
+  const done = new Set(held)
+  for (let level = 0; level < levels.length; level++) {
+    const entries = fetchEntries(levels[level])
+    // 1. a fetch fills its own key, if declared
+    entries.forEach((fetch, index) => {
+      const key = fetch.as
+      if (refs.has(key) && !done.has(key)) {
+        done.add(key)
+        filled.set(key, { fetch, level, index })
+      }
+    })
+    // 2. a fetch under an undeclared key fills the next still-empty key of its schema
+    entries.forEach((fetch, index) => {
+      if (refs.has(fetch.as)) return
+      const schema = typeof fetch.query === 'string' ? queries?.[fetch.query]?.schema : null
+      if (!schema) return
+      const key = declared.find(([k, ref]) => !done.has(k) && sameSchema(ref, schema))?.[0]
+      if (key === undefined) return
+      done.add(key)
+      filled.set(key, { fetch, level, index })
+    })
+  }
+  return new Map(declared.filter(([key]) => filled.has(key)).map(([key]) => [key, filled.get(key)]))
+}

package/src/data-paths.js

@@ -13,7 +13,8 @@
  * (`data-fetcher.js`), core injected the per-record default
  * (`fetch-config.js applyDeferredDetail`), core gated locale-prefixing on it
  * (`fetch-config.js localizeConfig`), the dev server matched it with a regex
- * (`build/src/site/plugin.js`), and kit's `useEntityDetail` requested it.
+ * (`build/src/site/plugin.js`), and kit's `useEntityDetail` — `useWholeRecord`
+ * since 2026-09-14 — requested it.
  *
  * They drifted. `useEntityDetail` was edited to `/_data/` on its own and
  * nothing else followed, so a public documented hook requested a URL that
@@ -73,12 +74,11 @@ export function queryDataUrl(name) {
  * URL of one record's full payload — every field, including deferred ones.
  * Emitted per record only when the query declares `deferred:`.
  *
- * Takes either a concrete slug (kit's `useEntityDetail`, which holds a
- * record) or the literal placeholder `{slug}` (core's `applyDeferredDetail`,
- * which builds a pattern that `substitutePlaceholders` resolves later
- * against the dynamic-route param). Both are plain interpolation; this
- * function does not encode, matching the behavior of the call sites it
- * replaced.
+ * Takes either a concrete slug — a caller holding the record — or the literal
+ * placeholder `{slug}` (core's `applyDeferredDetail`, which builds a pattern
+ * that `substitutePlaceholders` resolves later against the dynamic-route
+ * param). Both are plain interpolation; this function does not encode,
+ * matching the behavior of the call sites it replaced.
  *
  * @param {string} query - The query name.
  * @param {string} slug - A record slug, or a `{param}` placeholder.

package/src/datastore.js

@@ -23,10 +23,10 @@
  *
  * An ADDRESSED request — `path` or `url` — is identified by where it goes (the
  * address, the binding key, the unwrap, and for a POST its method and body) AND by
- * the view it takes of what came back: `scope`, `where`, `sort`, `limit`, which
- * the default fetcher evaluates locally over the file. `query` is not hashed: the
- * address already carries it (a query's list and its per-record file are
- * different addresses).
+ * the view it takes of what came back: the set — `scope`, `where`, `sort`, `limit` —
+ * and the `narrow` taken of it, which the default fetcher evaluates locally over the
+ * file (`evaluateQuery`). `query` is not hashed: the address already carries it (a
+ * query's list and its per-record file are different addresses).
  *
  * ⛔ **The view was left out until 2026-09-11, on the belief that operators "are
  * applied after the fetch over one shared copy".** They were applied BEFORE the
@@ -39,12 +39,18 @@
  * for the same request."*
  *
  * An ADDRESS-LESS request — a QUESTION sent to the records service — is
- * identified by the question: `query`, `schema`, `scope`, `where`, `match`,
- * `sort`, `limit`, `whole`. ⛔ The reason: with no per-query address, two pages
- * binding one `as` to two queries would otherwise share an entry, and a list
- * (brief) and a record (whole) of one query would collide — the one defect on
- * this path that delivers WRONG data rather than none. `match` is the record a
- * parametric page asks for; without it every record's question is one entry.
+ * identified by the question: `query`, `schema`, `scope`, `where`, `sort`, `limit`,
+ * `narrow`, `whole`. ⛔ The reason: with no per-query address, two pages binding one
+ * `as` to two queries would otherwise share an entry, and a list (brief) and a
+ * record (whole) of one query would collide — the one defect on this path that
+ * delivers WRONG data rather than none. `narrow.match` is the record a parametric
+ * page asks for; without it every record's question is one entry.
+ *
+ * ⭐ `narrow` is hashed field by field, in one order — `where`, `match`, `sort`,
+ * `cursor`, `limit` — so two producers that build the same narrowing in a different
+ * key order share an entry, and a `narrow` with nothing in it is no `narrow`. ⛔ Until
+ * 2026-09-14 a fetch's narrowing was merged into the top-level fields and `match` sat
+ * beside them (`@uniweb/core/fetch-config`, `setAndNarrow`).
  *
  * `locale` is hashed on both when present: two locales' answers must not share
  * an entry, and an asked config always carries the locale it was asked in.
@@ -62,15 +68,24 @@ export function deriveCacheKey(request) {
     ? request.method.toUpperCase()
     : undefined
   const body = method === 'POST' ? request?.body : undefined
-  const { query, schema, scope, where, match, sort, limit, whole } = request || {}
+  const { query, schema, scope, where, sort, limit, whole } = request || {}
+  const narrow = canonicalNarrow(request?.narrow)
   if (path || url) {
     // ⚠️ The field NAME is part of the hash, so renaming it moves every key ONCE.
     // In-memory stores repopulate; a consumer with a persistent cache takes one
     // cold pass. Chosen over hashing under the old name, which would have hidden
     // the rename inside the one function whose job is to be canonical.
-    return JSON.stringify({ path, url, as, transform, method, body, locale, scope, where, sort, limit })
+    return JSON.stringify({ path, url, as, transform, method, body, locale, scope, where, sort, limit, narrow })
   }
-  return JSON.stringify({ query, schema, scope, where, match, sort, limit, whole, as, transform, locale })
+  return JSON.stringify({ query, schema, scope, where, sort, limit, narrow, whole, as, transform, locale })
+}
+
+/** A `narrow` in one field order, or `undefined` when it holds nothing. */
+function canonicalNarrow(narrow) {
+  if (!narrow || typeof narrow !== 'object') return undefined
+  const { where, match, sort, cursor, limit } = narrow
+  if ([where, match, sort, cursor, limit].every((v) => v === undefined)) return undefined
+  return { where, match, sort, cursor, limit }
 }
 
 /**

package/src/detail-url.js

@@ -45,7 +45,7 @@ function paramContext(paramName, paramValue, record) {
   // detail URL was `/data/articles/{slug}.json`, a guaranteed 404, on every
   // template page with `deferred:` fields (measured 2026-09-04). When the caller
   // holds the record — the entity store does (it matched it), and so does
-  // `useEntityDetail` — its slug fills the name the FILE was written under. A
+  // kit's `useWholeRecord` — its slug fills the name the FILE was written under. A
   // caller with no record in hand leaves `{slug}` literal rather than guessing
   // the capture is one: a visibly unresolved address beats a plausible wrong one.
   const handle = recordHandle(record)
@@ -69,7 +69,7 @@ export const ROUTE_HANDLE_KEY = routeRecordKey('slug')
  * config (post-`resolveFetchConfigs`, which set `detail` — see `./fetch-config.js`).
  * Three sources, and no others:
  *
- *   - **the records service** — the route query's own question, plus `match`;
+ *   - **the records service** — the route query's set, plus `narrow.match`;
  *   - **an external query's `record:`** — its `url` (the query's when it names none),
  *     `method` (likewise), `body` and `transform` — ⛔ never the list's `body` or
  *     `transform`, since a record response is rarely wrapped the way the list is;
@@ -97,22 +97,30 @@ export function buildDetailConfig(queryConfig, dynamicContext) {
   const { paramName, paramValue, record = null } = dynamicContext
   if (!paramName || paramValue === undefined) return null
 
-  // ⭐ THE RECORDS SERVICE: the record is the route query's own question, unchanged,
-  // plus `match` — the one key the page's folder names and the URL's value for it
-  // (`routeRecordKey`: `[slug]` → `$name`, `[uuid]` → `$uuid`, `[id]` → `id`) —
-  // asked in full. `sort` and `limit` are the list's and drop; `scope` and the
-  // authored `where` stay AS WRITTEN, so a query's conditions cannot be escaped
-  // through the URL (the records contract, §1a).
+  // ⭐ THE RECORDS SERVICE: the record is the route query's SET — the query as saved,
+  // its `scope`, `where`, `sort` and `limit` all kept — narrowed by `match`, the one
+  // key the page's folder names and the URL's value for it (`routeRecordKey`: `[slug]`
+  // → `$name`, `[uuid]` → `$uuid`, `[id]` → `id`), asked in full. So the one question
+  // answers the record if it is in the set and `[]` (not found) if it is not: a
+  // record outside the query's `limit` has no page, and a query's conditions cannot
+  // be escaped through the URL (ruled 2026-09-14 [Diego]).
   //
-  // ⛔ `where` is never touched. Until 2026-09-11 the handle was merged into it,
-  // which replaced any condition the author had on the same key; `where` is the
-  // author's and `match` is the visitor's [Diego]. The value is a string — it is a
-  // URL segment — and the service compares it as one, as the local match does.
+  // ⭐ The fetch's own narrowing drops: which pages exist is the query's to decide,
+  // never a list's (`routeSelection`). So every section of the page that asks its
+  // record asks this one question.
+  //
+  // ⛔ Until 2026-09-14 the record question dropped the query's `sort` and `limit` and
+  // sent `match` at the top level, so "this field note, if it is among the 100" was
+  // asked as "this field note". ⛔ And `where` is never touched: until 2026-09-11 the
+  // handle was merged into it, which replaced any condition the author had on the same
+  // key; `where` is the author's and `match` is the visitor's [Diego]. The value is a
+  // string — it is a URL segment — and the service compares it as one, as the local
+  // match does.
   if (queryConfig.ask) {
-    const { sort, limit, detail: _detail, match: _match, ...rest } = queryConfig
+    const { narrow: _narrow, detail: _detail, match: _match, ...set } = queryConfig
     return {
-      ...rest,
-      match: { [routeRecordKey(paramName)]: String(paramValue) },
+      ...set,
+      narrow: { match: { [routeRecordKey(paramName)]: String(paramValue) } },
       whole: true,
       dynamicContext: { paramName, paramValue },
     }