@uniweb/core 0.7.31 → 0.7.33

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@uniweb/core",
-  "version": "0.7.31",
+  "version": "0.7.33",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {
     ".": "./src/index.js",
-    "./locale-config": "./src/locale-config.js"
+    "./fetch-config": "./src/fetch-config.js",
+    "./locale-config": "./src/locale-config.js",
+    "./section-id": "./src/section-id.js"
   },
   "files": [
     "src"

package/src/entity-store.js

@@ -15,16 +15,18 @@
  */
 
 import { substitutePlaceholders } from './substitute-placeholders.js'
+import { isFetchRefinement, resolveFetchConfigs } from './fetch-config.js'
 
 /**
  * Is `block.fetch` a per-instance refinement of the ancestor's fetch config
  * rather than a new source? The canonical spelling is `refine: true`; the
  * legacy spelling `inherit: true` is still honored for one release with a
  * dev-mode warning.
+ *
+ * The predicate itself lives in `./fetch-config.js` with the rest of the
+ * cascade rule; this alias keeps the local call sites reading as they did.
  */
-function isRefinement(bf) {
-  return bf?.refine === true || bf?.inherit === true
-}
+const isRefinement = isFetchRefinement
 
 let inheritDeprecationWarned = false
 function warnInheritDeprecation(block) {
@@ -95,54 +97,39 @@ export default class EntityStore {
     return []
   }
 
-  /**
-   * Return a localized copy of a fetch config for collection data.
-   * Non-default locales get /{locale} prefixed onto /data/ paths so the
-   * client fetches the translated JSON (/fr/data/articles.json).
-   */
-  _localizeConfig(cfg, website) {
-    if (!cfg.path || !website) return cfg
-    const locale = website.getActiveLocale?.()
-    const defaultLocale = website.getDefaultLocale?.()
-    if (!locale || locale === defaultLocale) return cfg
-    if (!cfg.path.startsWith('/data/')) return cfg
-    return { ...cfg, path: `/${locale}${cfg.path}` }
-  }
-
   /**
    * Walk the four-level hierarchy and collect fetch configs for the
    * requested schemas. First match per schema wins.
+   *
+   * This method's job is to read the four source slots off the object graph;
+   * the rule applied to them (precedence, first-match-per-schema, locale
+   * normalization, deferred-detail injection) lives in `./fetch-config.js`,
+   * shared with every other host that has to answer the same question. Do not
+   * re-inline it here — divergence between copies is what the extraction
+   * exists to prevent.
    */
   _findFetchConfigs(block, requested) {
-    const configs = new Map()
-    const collectAll = requested.length === 0
-    const sources = []
-
     if (block.fetch?.inherit === true && block.fetch?.refine !== true) {
       warnInheritDeprecation(block)
     }
-    if (block.fetch && !isRefinement(block.fetch)) sources.push(block.fetch)
-    const page = block.page
-    if (page?.fetch) sources.push(page.fetch)
-    if (page?.parent?.fetch) sources.push(page.parent.fetch)
-    const siteFetch = block.website?.config?.fetch
-    if (siteFetch) sources.push(siteFetch)
 
+    const page = block.page
     const website = block.website
 
-    for (const source of sources) {
-      const configList = Array.isArray(source) ? source : [source]
-      for (const cfg of configList) {
-        if (!cfg.schema) continue
-        if (configs.has(cfg.schema)) continue
-        if (collectAll || requested.includes(cfg.schema)) {
-          const localized = this._localizeConfig(cfg, website)
-          const withDetail = this._applyDeferredDetail(localized, website)
-          configs.set(cfg.schema, withDetail)
-        }
-      }
-    }
-    return configs
+    return resolveFetchConfigs(
+      [
+        block.fetch && !isRefinement(block.fetch) ? block.fetch : null,
+        page?.fetch,
+        page?.parent?.fetch,
+        website?.config?.fetch,
+      ],
+      {
+        schemas: requested,
+        locale: website?.getActiveLocale?.() ?? null,
+        defaultLocale: website?.getDefaultLocale?.() ?? null,
+        collections: website?.config?.collections ?? null,
+      },
+    )
   }
 
   /**
@@ -167,52 +154,6 @@ export default class EntityStore {
     }
   }
 
-  /**
-   * Auto-inject `detail:` on collection refs whose collection has
-   * `deferred:` declared. The detail pattern points at the per-record
-   * source so the existing dynamic-route singular flow fetches a record
-   * with all fields (including the deferred ones) instead of the
-   * matched-item-from-the-cascade-collection (without).
-   *
-   * Two patterns:
-   *
-   *   - Markdown-backed collections (the build emits per-record files
-   *     at `/data/<name>/<slug>.json`): the auto-injected pattern is
-   *     that path. `isLocalPath` resolution downstream gives the
-   *     fetch a `path:` shape.
-   *
-   *   - API-backed collections (the source is a remote URL; the build
-   *     emits no per-record files): the author declares a `detailUrl:`
-   *     on the collection — e.g., `/api/articles/{slug}` — and the
-   *     auto-injected pattern uses it. `isLocalPath` resolution
-   *     downstream gives the fetch a `url:` shape (because the
-   *     collection itself has `url:`, not `path:`).
-   *
-   * Conventions:
-   *   - Per-record sources are keyed by `item.slug`. The injected
-   *     pattern uses the `{slug}` placeholder; substitution works when
-   *     the dynamic route's paramName is 'slug' (the documented
-   *     convention). Routes with other param names need an explicit
-   *     author-written `detail:` value.
-   *   - Author-supplied `cfg.detail` always wins. This helper only fills
-   *     in the default for collections that have declared deferred fields.
-   *   - Per-record files are not currently localized; sites needing
-   *     localized deferred collections write their own `detail:` URL.
-   */
-  _applyDeferredDetail(cfg, website) {
-    if (cfg.detail !== undefined) return cfg
-    const schema = cfg.schema
-    if (!schema) return cfg
-    const collConfig = website?.config?.collections?.[schema]
-    if (!collConfig || typeof collConfig !== 'object') return cfg
-    const deferred = Array.isArray(collConfig.deferred) ? collConfig.deferred : null
-    if (!deferred || deferred.length === 0) return cfg
-    const pattern = typeof collConfig.detailUrl === 'string'
-      ? collConfig.detailUrl
-      : `/data/${schema}/{slug}.json`
-    return { ...cfg, detail: pattern }
-  }
-
   /**
    * Build a detail-URL fetch config from a collection config + dynamic context.
    *

package/src/fetch-config.js

@@ -0,0 +1,153 @@
+/**
+ * Fetch-config resolution — the shared rule, in one place.
+ *
+ * "Which fetch configs apply here?" is a framework concept. Authors declare
+ * `fetch:` at the section, page, folder and site levels; the framework decides
+ * which declaration wins per schema, how a local data path is localized, and
+ * when a collection with deferred fields gets a detail pattern injected.
+ *
+ * Every host that renders a page needs that answer — the browser runtime, the
+ * build-time prerenderer, and any server-side renderer. The rule had grown
+ * more than one implementation, and they had diverged in both directions (each
+ * carrying a level or a semantic the other lacked). This module is the single
+ * definition they call.
+ *
+ * INTENTIONALLY A LEAF: no imports, so it is safe to load anywhere — including
+ * environments with no DOM, no filesystem, and a hard bundle-size ceiling.
+ * Importing anything here (or from the package root) would defeat that. Keep
+ * it dependency-free.
+ *
+ * WHAT THIS DOES NOT OWN: where the sources come from. A caller holding a live
+ * object graph reads them off the graph; a caller holding a content document
+ * reads them off the JSON. Both hand the same ordered array to
+ * `resolveFetchConfigs`. That difference is real and stays with the caller.
+ */
+
+/**
+ * Is this fetch declaration a per-instance *refinement* of an ancestor's
+ * config rather than a new source of its own?
+ *
+ * The canonical spelling is `refine: true`. The legacy spelling `inherit: true`
+ * is still honored; callers that want to warn about it should test for the key
+ * themselves — this predicate stays silent so it is safe in any environment.
+ *
+ * @param {Object} cfg - a fetch declaration
+ * @returns {boolean}
+ */
+export function isFetchRefinement(cfg) {
+  return cfg?.refine === true || cfg?.inherit === true
+}
+
+/**
+ * Localize a fetch config that reads a local data path.
+ *
+ * Non-default locales get `/{locale}` prefixed onto `/data/` paths so the
+ * caller reads the translated JSON (`/fr/data/articles.json`). Configs with no
+ * `path` (remote `url:` sources), or paths outside `/data/`, pass through
+ * untouched — a remote endpoint's localization is the author's business.
+ *
+ * @param {Object} cfg
+ * @param {string|null} locale - the locale being rendered
+ * @param {string|null} defaultLocale - the site's default locale
+ * @returns {Object} the original config, or a localized copy
+ */
+function localizeConfig(cfg, locale, defaultLocale) {
+  if (!cfg.path) return cfg
+  if (!locale || locale === defaultLocale) return cfg
+  if (!cfg.path.startsWith('/data/')) return cfg
+  return { ...cfg, path: `/${locale}${cfg.path}` }
+}
+
+/**
+ * Auto-inject `detail:` on a collection ref whose collection declares
+ * `deferred:` fields.
+ *
+ * A deferred collection ships a lean list payload, so the full record has to
+ * come from somewhere else. Two patterns, picked by what the collection
+ * declares:
+ *
+ *   - the collection has `detailUrl:` → use it verbatim (a remote source);
+ *   - otherwise → `/data/<schema>/{slug}.json`, the per-record file emitted
+ *     alongside the lean list.
+ *
+ * Conventions carried from the original implementation:
+ *   - Per-record sources are keyed by `item.slug`, and the injected pattern
+ *     uses the `{slug}` placeholder. Substitution works when the dynamic
+ *     route's paramName is `slug` (the documented convention); a route using
+ *     another param name needs an explicit author-written `detail:`.
+ *   - Per-record files are not currently localized. A site needing localized
+ *     deferred collections writes its own `detail:` URL.
+ *
+ * An author-supplied `cfg.detail` always wins; this only fills the default.
+ * With no `collections` map available the config passes through untouched —
+ * deferred-detail injection is an enhancement, never a correctness
+ * requirement, so a caller that does not have collection metadata still gets
+ * a usable config. That matters for hosts whose content projection may not
+ * carry collection metadata at all.
+ *
+ * @param {Object} cfg
+ * @param {Object|null} collections - the site's `config.collections` map
+ * @returns {Object} the original config, or a copy carrying `detail`
+ */
+function applyDeferredDetail(cfg, collections) {
+  if (cfg.detail !== undefined) return cfg
+  const schema = cfg.schema
+  if (!schema || !collections) return cfg
+  const collConfig = collections[schema]
+  if (!collConfig || typeof collConfig !== 'object') return cfg
+  const deferred = Array.isArray(collConfig.deferred) ? collConfig.deferred : null
+  if (!deferred || deferred.length === 0) return cfg
+  const pattern = typeof collConfig.detailUrl === 'string'
+    ? collConfig.detailUrl
+    : `/data/${schema}/{slug}.json`
+  return { ...cfg, detail: pattern }
+}
+
+/**
+ * Resolve the applicable fetch configs from an ordered list of sources.
+ *
+ * The rule: walk the sources in precedence order and take the FIRST match per
+ * schema. Sources are the framework's cascade, most specific first — typically
+ * section → page → parent page → site. A source may be a single config or an
+ * array of them; arrays are walked in order.
+ *
+ * First-match-per-schema (rather than first-match-wins-outright) is what lets
+ * a page needing two schemas inherit one from the site and declare the other
+ * itself. Collapsing that to a single winner is a real behavior change, not a
+ * simplification.
+ *
+ * @param {Array<Object|Array<Object>>} sources - ordered, most specific first.
+ *   Falsy entries are skipped, so callers can pass optional levels directly.
+ * @param {Object} [options]
+ * @param {string[]} [options.schemas] - restrict to these schema names.
+ *   Empty (the default) collects every schema found.
+ * @param {string|null} [options.locale] - the locale being rendered
+ * @param {string|null} [options.defaultLocale] - the site's default locale
+ * @param {Object|null} [options.collections] - the site's `config.collections`
+ * @returns {Map<string, Object>} schema name → resolved config
+ */
+export function resolveFetchConfigs(sources, options = {}) {
+  const {
+    schemas = [],
+    locale = null,
+    defaultLocale = null,
+    collections = null,
+  } = options
+
+  const configs = new Map()
+  const collectAll = schemas.length === 0
+
+  for (const source of sources) {
+    if (!source) continue
+    const configList = Array.isArray(source) ? source : [source]
+    for (const cfg of configList) {
+      if (!cfg?.schema) continue
+      if (configs.has(cfg.schema)) continue
+      if (!collectAll && !schemas.includes(cfg.schema)) continue
+      const localized = localizeConfig(cfg, locale, defaultLocale)
+      configs.set(cfg.schema, applyDeferredDetail(localized, collections))
+    }
+  }
+
+  return configs
+}

package/src/section-id.js

@@ -0,0 +1,67 @@
+/**
+ * The DOM id of a rendered section — one rule, shared by everything that
+ * needs to name a section.
+ *
+ * A section's id is written by the renderer and read by anything that links
+ * to a section: the search index's anchors, a table of contents, a deep link
+ * someone pastes. Those only agree if they derive the id the same way, and
+ * they cannot check each other — a mismatch produces no error anywhere. The
+ * link simply lands on the page and does not scroll, and if the target is the
+ * page you are already on, nothing visibly happens at all.
+ *
+ * That is not hypothetical. The renderers moved from the positional `id` to
+ * `stableId` (so an id survives reordering) and the search extractor was not
+ * updated, so it kept emitting `Section1` while the DOM said
+ * `section-what-is-uniweb`. Every section-level search result on every site
+ * pointed at a fragment that did not exist, and no test failed.
+ *
+ * So this is deliberately the ONLY place the rule is written down, and it
+ * captures both halves — which identity to use AND how to spell it. A helper
+ * that only formatted a value the caller picked would have prevented the
+ * spelling half of that bug and none of the identity half.
+ *
+ * **Zero imports, and it must stay that way.** `@uniweb/projections` consumes
+ * this through the leaf subpath `@uniweb/core/section-id` because its
+ * environment contract forbids the bare `@uniweb/core` entry (that pulls in
+ * semantic-parser and theming). Adding an import here would break that
+ * package's `tests/environment.test.js`.
+ */
+
+/** Prefix for every section wrapper id. */
+const PREFIX = 'section-'
+
+/**
+ * The DOM id for a section, from either a Block or the raw section data.
+ *
+ * Accepts both shapes on purpose: the runtime holds `Block` instances while
+ * build-time consumers hold plain objects off the wire. Both carry the same
+ * two fields, so one function serves both rather than each growing its own.
+ *
+ * `stableId` is preferred because it is derived from the section's filename
+ * (or an authored `id:`) and therefore survives reordering; the positional
+ * `id` is the fallback for content that has no stable identity.
+ *
+ * @param {{stableId?: string, id?: string|number}} section - A Block, or a
+ *   section object from site content.
+ * @returns {string} e.g. `section-hero`. Returns `section-unknown` rather
+ *   than an id ending in `undefined` when a section carries no identity at
+ *   all — a wrong-but-obvious anchor beats a malformed one.
+ */
+export function sectionDomId(section) {
+  if (!section) return `${PREFIX}unknown`
+  const id = section.stableId || section.id
+  return `${PREFIX}${id === undefined || id === null || id === '' ? 'unknown' : id}`
+}
+
+/**
+ * The same id as a URL fragment, for building a link to a section.
+ *
+ * Exists so a caller composing an href never has to remember whether the
+ * `#` is already included — the concatenation is the part people get wrong.
+ *
+ * @param {{stableId?: string, id?: string|number}} section
+ * @returns {string} e.g. `#section-hero`
+ */
+export function sectionHash(section) {
+  return `#${sectionDomId(section)}`
+}