@uniweb/core 0.7.33 → 0.8.0

package/package.json

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

package/src/data-paths.js

@@ -0,0 +1,121 @@
+/**
+ * Compiled-collection paths — the ONE home for the URL and directory
+ * convention that the build emits and every fetcher requests.
+ *
+ * Why this module exists. The path `/data/<name>.json` was a bare string
+ * literal in six places across three packages: the build wrote it
+ * (`collection-processor.js`), the build resolved `collection:` to it
+ * (`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.
+ *
+ * They drifted. `useEntityDetail` was edited to `/_data/` on its own and
+ * nothing else followed, so a public documented hook requested a URL that
+ * nothing anywhere emitted or served — broken on every lane, silently,
+ * because it has no call site in this workspace to fail. Emit and request
+ * had passing tests the whole time; each pinned its own literal.
+ *
+ * So the invariant is structural, not documented: producers and consumers
+ * read the same constant, and a test asserts they agree. Changing the
+ * convention is then one edit here rather than a six-site sweep with a
+ * silent-failure trap in it (see `localizeConfig` — a missed site there
+ * degrades to default-locale content with a 200, not a 404).
+ *
+ * WHY THIS PATH IS NOT `_data`. The site's other reserved paths are
+ * underscore-prefixed — `_search`, `_pages/`, `_importmap/` — and the
+ * inconsistency invites a rename. It has been proposed and declined. Those
+ * are machinery: an endpoint and bundler artifacts, which no visitor should
+ * land on and which an underscore correctly marks as internal. Compiled
+ * collection JSON is the opposite — it is the site's own content, the same
+ * records an agent that found the site through `llms.txt` may reasonably
+ * fetch directly. `/data/articles.json` is a legitimate public address, and
+ * `data` is a legitimate page route; neither collides with the other, since
+ * pages emit `.html` and collections emit `.json`. Prefixing it would say
+ * "internal" about something that is not.
+ *
+ * Zero-dependency leaf, like `./locale-config.js`, so a consumer that must
+ * not pull core's graph (semantic-parser, theming) can import the subpath
+ * `@uniweb/core/data-paths` directly.
+ */
+
+/**
+ * The directory segment, for filesystem joins and regex construction.
+ * The build writes `<site>/public/<DATA_DIR>/` and copies it to
+ * `<dist>/<DATA_DIR>/`.
+ */
+export const DATA_DIR = 'data'
+
+/**
+ * The URL prefix every compiled-collection request carries. Note the
+ * trailing slash: `isDataUrl` is a prefix test, and without it `/database`
+ * would match.
+ */
+export const DATA_URL_PREFIX = `/${DATA_DIR}/`
+
+/**
+ * URL of a collection's cascade payload — the whole collection, with
+ * `deferred:` fields stripped when the collection declares them.
+ *
+ * @param {string} name - The collection name.
+ * @returns {string} e.g. `/data/articles.json`
+ */
+export function collectionDataUrl(name) {
+  return `${DATA_URL_PREFIX}${name}.json`
+}
+
+/**
+ * URL of one record's full payload — every field, including deferred ones.
+ * Emitted per item only when the collection 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.
+ *
+ * @param {string} collection - The collection name.
+ * @param {string} slug - A record slug, or a `{param}` placeholder.
+ * @returns {string} e.g. `/data/articles/design-tips.json`
+ */
+export function recordDataUrl(collection, slug) {
+  return `${DATA_URL_PREFIX}${collection}/${slug}.json`
+}
+
+/**
+ * The inverse of `collectionDataUrl` — recover a collection name from a fetch
+ * path so a caller can look it up among the declared collections.
+ *
+ * Best-effort by design, and the caller decides what a miss means: a path
+ * outside the compiled-collection tree is returned with only its `.json`
+ * suffix removed, which simply will not match any declared collection and
+ * lets the caller fall through to reading the file. Nested names round-trip
+ * (`/data/archive/2024/posts.json` → `archive/2024/posts`).
+ *
+ * Lives here because it is the *same* convention read backwards. Left at a
+ * call site it becomes a regex with the prefix baked in — which is exactly
+ * how `validate-data.js` came to hold a sixth copy of it.
+ *
+ * @param {string} path - A fetch config's `path`.
+ * @returns {string} The derived collection name.
+ */
+export function collectionNameFromUrl(path) {
+  if (typeof path !== 'string') return ''
+  // DATA_DIR is a plain identifier segment, so it needs no regex escaping.
+  return path.replace(new RegExp(`^/?${DATA_DIR}/`), '').replace(/\.json$/i, '')
+}
+
+/**
+ * Whether a fetch config's `path` addresses compiled collection data.
+ *
+ * Used to scope behavior that only makes sense for build-emitted files —
+ * locale prefixing in particular, which must not touch a remote `url:`
+ * source or an author-declared `detailUrl:`.
+ *
+ * @param {*} path - A fetch config's `path` field.
+ * @returns {boolean}
+ */
+export function isDataUrl(path) {
+  return typeof path === 'string' && path.startsWith(DATA_URL_PREFIX)
+}

package/src/fetch-config.js

@@ -12,10 +12,14 @@
  * 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.
+ * INTENTIONALLY A LEAF: safe to load anywhere — including environments with no
+ * DOM, no filesystem, and a hard bundle-size ceiling. The rule that protects
+ * that is **no transitive graph**: import nothing from the package root (which
+ * pulls semantic-parser and theming) and nothing that itself imports. A
+ * zero-dependency sibling leaf is admissible and `./data-paths.js` is the only
+ * one taken — the path convention it holds has to be identical here and in the
+ * build that emits the files, and a second copy of that string is precisely
+ * the drift this module exists to prevent.
  *
  * 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
@@ -23,6 +27,8 @@
  * `resolveFetchConfigs`. That difference is real and stays with the caller.
  */
 
+import { isDataUrl, recordDataUrl } from './data-paths.js'
+
 /**
  * Is this fetch declaration a per-instance *refinement* of an ancestor's
  * config rather than a new source of its own?
@@ -54,7 +60,7 @@ export function isFetchRefinement(cfg) {
 function localizeConfig(cfg, locale, defaultLocale) {
   if (!cfg.path) return cfg
   if (!locale || locale === defaultLocale) return cfg
-  if (!cfg.path.startsWith('/data/')) return cfg
+  if (!isDataUrl(cfg.path)) return cfg
   return { ...cfg, path: `/${locale}${cfg.path}` }
 }
 
@@ -99,7 +105,7 @@ function applyDeferredDetail(cfg, collections) {
   if (!deferred || deferred.length === 0) return cfg
   const pattern = typeof collConfig.detailUrl === 'string'
     ? collConfig.detailUrl
-    : `/data/${schema}/{slug}.json`
+    : recordDataUrl(schema, '{slug}')
   return { ...cfg, detail: pattern }
 }
 

package/src/index.js

@@ -27,9 +27,20 @@ export {
   resolvePublishableLocales,
   validateLanguageConfig
 } from './locale-config.js'
+export {
+  DATA_DIR,
+  DATA_URL_PREFIX,
+  collectionDataUrl,
+  recordDataUrl,
+  collectionNameFromUrl,
+  isDataUrl
+} from './data-paths.js'
 export { evaluate as evaluateWhere, match as matchWhere } from './where.js'
-export { isRichSchema } from './schemas.js'
-export { resolveStyle as resolveRequestStyle, listStyleNames as listRequestStyleNames } from './request-styles/index.js'
+export { isRichSchema, normalizeSchema } from './schemas.js'
+export {
+  resolveStyle as resolveRequestStyle,
+  listStyleNames as listRequestStyleNames
+} from './request-styles/index.js'
 
 /**
  * The singleton Uniweb instance.
@@ -53,8 +64,20 @@ export function getUniweb() {
  *   this transport. Used only by the editor's preview iframe.
  * @returns {Uniweb} The created instance (also assigned to globalThis.uniweb).
  */
-export function createUniweb(content, foundation = null, extensions = [], { defaultFetcher = null, transport = null, dev = false } = {}) {
-  const instance = new Uniweb({ content, foundation, extensions, defaultFetcher, transport, dev })
+export function createUniweb(
+  content,
+  foundation = null,
+  extensions = [],
+  { defaultFetcher = null, transport = null, dev = false } = {}
+) {
+  const instance = new Uniweb({
+    content,
+    foundation,
+    extensions,
+    defaultFetcher,
+    transport,
+    dev
+  })
   globalThis.uniweb = instance
   return instance
 }

package/src/schemas.js

@@ -35,3 +35,76 @@ export function isRichSchema(schema) {
   if (schema.childSchema && typeof schema.childSchema === 'object') return true
   return false
 }
+
+/**
+ * Normalize any authored `data:` schema shape to the rich form the editor
+ * renders, or null when it is not a single form at all.
+ *
+ * WHY THIS EXISTS. `isRichSchema` answers "is this already the rich shape?",
+ * which is the right question for dispatch and the wrong one for "can this be
+ * edited". There are THREE authored shapes and it accepts exactly one:
+ *
+ *   { fields: [ {id, …} ] }        meta.js inline rich-form      → true
+ *   { fields: { name: spec } }     a RESOLVED NAMED REF          → FALSE
+ *   { name: spec }                 meta.js inline field map      → false
+ *
+ * The middle row is the important one and the reason this helper is in `core`
+ * rather than in the editor. A named ref (`'@/article'`, `'@std/person'`) is the
+ * FIRST authoring form the docs show, and `validateAndNormalizeSchema` in the
+ * build resolves it to `{ fields: <MAP> }` — a map, not an array. So filtering
+ * with `isRichSchema` discards not merely "simple" schemas but the primary
+ * documented one, and any consumer that wants to render it has to re-derive the
+ * conversion. Three consumers re-deriving it is exactly the divergence the
+ * shared predicate was introduced to prevent.
+ *
+ * A field map is an unordered `fields[]`, so the conversion is mechanical.
+ * Ordering comes from `Object.entries`, which is insertion order for string keys
+ * — i.e. the order the author wrote, which is the order a form should show.
+ *
+ * `sections` returns null on purpose: a sectioned data-schema describes a Model
+ * with several sections, which is not one form. Flattening it would invent a
+ * layout the author never expressed.
+ *
+ * @param {*} schema - any authored or resolved `data:` schema value
+ * @returns {{ fields: Array<object> } | null} the rich shape, or null
+ */
+export function normalizeSchema(schema) {
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema))
+    return null
+
+  // Already rich — hand back untouched. Composite/childSchema variants are rich
+  // by `isRichSchema`'s definition and are not ours to reshape.
+  if (Array.isArray(schema.fields)) return schema
+  if (schema.isComposite === true || schema.childSchema) return schema
+
+  // A sectioned Model is not a single form.
+  if (schema.sections !== undefined) return null
+
+  const mapToFields = (map) =>
+    Object.entries(map).map(([id, spec]) =>
+      typeof spec === 'string' ? { id, type: spec } : { id, ...spec }
+    )
+
+  // A resolved named ref: `fields` present, as a map.
+  if (schema.fields && typeof schema.fields === 'object') {
+    const { fields, ...rest } = schema
+    return { ...rest, fields: mapToFields(fields) }
+  }
+
+  // An inline field map: no `fields` key, so every value must be an OBJECT
+  // carrying `type`.
+  //
+  // The bare-type string shorthand (`{ cpu: 'string' }`) is deliberately NOT
+  // accepted here, even though schema FILES support it. Without a `fields` key
+  // there is nothing to distinguish it from ordinary data: `{ name: 'Acme' }` and
+  // `{ cpu: 'string' }` are the same shape, and an earlier cut of this function
+  // turned `{ name, description }` into a two-field form. Erring toward null
+  // costs an author the object spelling; erring the other way invents a form out
+  // of a config block.
+  const entries = Object.entries(schema)
+  if (!entries.length) return null
+  const isFieldSpec = ([, v]) =>
+    v && typeof v === 'object' && !Array.isArray(v) && v.type !== undefined
+  if (!entries.every(isFieldSpec)) return null
+  return { fields: mapToFields(schema) }
+}

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}
  */