@uniweb/core 0.7.32 → 0.7.34

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@uniweb/core",
-  "version": "0.7.32",
+  "version": "0.7.34",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {
     ".": "./src/index.js",
+    "./fetch-config": "./src/fetch-config.js",
     "./locale-config": "./src/locale-config.js",
     "./section-id": "./src/section-id.js"
   },
@@ -32,8 +33,8 @@
     "vitest": "^4.1.7"
   },
   "dependencies": {
-    "@uniweb/theming": "0.1.14",
-    "@uniweb/semantic-parser": "1.1.20"
+    "@uniweb/theming": "0.1.15",
+    "@uniweb/semantic-parser": "1.1.21"
   },
   "scripts": {
     "test": "vitest run"

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/theme.js

@@ -13,28 +13,6 @@ const SHADE_LEVELS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950]
 // Valid color contexts
 const VALID_CONTEXTS = ['light', 'medium', 'dark']
 
-// Default semantic tokens by context
-const DEFAULT_CONTEXT_TOKENS = {
-  light: {
-    bg: 'var(--neutral-50)',
-    text: 'var(--neutral-950)',
-    heading: 'var(--neutral-900)',
-    link: 'var(--primary-600)',
-  },
-  medium: {
-    bg: 'var(--neutral-100)',
-    text: 'var(--neutral-950)',
-    heading: 'var(--neutral-900)',
-    link: 'var(--primary-600)',
-  },
-  dark: {
-    bg: 'var(--neutral-900)',
-    text: 'var(--neutral-50)',
-    heading: 'white',
-    link: 'var(--primary-400)',
-  },
-}
-
 /**
  * Theme class for runtime theme access
  */
@@ -154,40 +132,42 @@ export default class Theme {
   // Context Access
   // ============================================================
 
-  /**
-   * Get a semantic token value for a context
+  /*
+   * REMOVED 2026-07-28: getContextToken(context, token) and
+   * getContextTokens(context), plus the DEFAULT_CONTEXT_TOKENS table backing
+   * them. Read this before reintroducing either.
    *
-   * @param {string} context - Context name ('light', 'medium', 'dark')
-   * @param {string} token - Token name (e.g., 'bg', 'text', 'link')
-   * @returns {string|null} Token value or null
+   * They were unreachable-by-design rather than merely stale. A lookup keyed on
+   * (context, token) answers "what does the .context-<name> class set by
+   * default?", but the question callers ask is "what colour is --heading HERE",
+   * and those diverge for two reasons no such lookup can see:
    *
-   * @example
-   * theme.getContextToken('light', 'bg') // → "var(--neutral-50)"
-   * theme.getContextToken('dark', 'text') // → "var(--neutral-50)"
-   */
-  getContextToken(context, token) {
-    // Check custom context tokens first
-    const customContext = this._contexts[context]
-    if (customContext && customContext[token]) {
-      return customContext[token]
-    }
-
-    // Fall back to defaults
-    const defaults = DEFAULT_CONTEXT_TOKENS[context]
-    return defaults?.[token] || null
-  }
-
-  /**
-   * Get all tokens for a context
+   *   - a section's own `theme:` overrides, emitted as `#section-{id} { … }` by
+   *     @uniweb/theming's buildSectionOverrides;
+   *   - the active site scheme, where `.scheme-dark` redefines the root tokens.
    *
-   * @param {string} context - Context name
-   * @returns {Object} Token name → value mapping
+   * So a correct-looking answer would still be wrong whenever a section
+   * overrides tokens or the visitor is in dark mode — the failure being a
+   * confident wrong value, not an error. (The table had also drifted: it held
+   * `bg`/`text`, retired in favour of `section`/`body`, and four tokens where
+   * the live set is ~25. Repopulating it would have made a misleading API look
+   * trustworthy, which is worse than leaving it visibly incomplete.)
+   *
+   * What to use instead:
+   *   - an actually-resolved value (canvas, SVG, a chart matching the theme):
+   *     getComputedStyle(el).getPropertyValue('--heading') — this accounts for
+   *     both section overrides and the active scheme, which no static table can;
+   *   - the defaults table itself (tooling, a theme editor):
+   *     getDefaultContextTokens() from @uniweb/theming, which owns it;
+   *   - ordinary component styling: the CSS variables directly. Reading tokens
+   *     into JS to branch on them is the `isDark ? … : …` pattern semantic
+   *     tokens exist to remove.
+   *
+   * SHADE_LEVELS below is duplicated from @uniweb/theming too, and was left
+   * deliberately: both copies are identical and the 11-step scale is fixed by
+   * the design, so there is no drift to prevent — noted so the next reader
+   * knows it was considered rather than missed.
    */
-  getContextTokens(context) {
-    const defaults = DEFAULT_CONTEXT_TOKENS[context] || {}
-    const custom = this._contexts[context] || {}
-    return { ...defaults, ...custom }
-  }
 
   /**
    * Get the CSS class name for a context
@@ -423,6 +403,15 @@ export default class Theme {
  * point here; everything that consumes the model (runtime boot, kit's
  * useAppearance) imports THIS one.
  *
+ * A warning is not a mechanism, and this one has been tested: while it stood,
+ * a SECOND shared table in this same file — DEFAULT_CONTEXT_TOKENS, duplicating
+ * @uniweb/theming's — drifted to retired token names and lost twenty entries
+ * without anyone noticing, because nothing called the two methods that read it.
+ * It was removed 2026-07-28 (see the note where it sat). Treat the lockstep
+ * above as a live obligation with a track record, not a formality: if you find
+ * yourself copying a value out of @uniweb/theming into this file, that is the
+ * moment this comment is for.
+ *
  * @param {Object} appearance - the resolved theme.yml `appearance:` block
  * @returns {boolean}
  */