@uniweb/core 0.7.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/core",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {
@@ -30,8 +30,8 @@
     "jest": "^29.7.0"
   },
   "dependencies": {
-    "@uniweb/theming": "0.1.3",
-    "@uniweb/semantic-parser": "1.1.9"
+    "@uniweb/semantic-parser": "1.1.9",
+    "@uniweb/theming": "0.1.3"
   },
   "scripts": {
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"

package/src/entity-store.js

@@ -148,18 +148,31 @@ export default class EntityStore {
 
   /**
    * Auto-inject `detail:` on collection refs whose collection has
-   * `deferred:` declared. The build emits per-record files at
-   * `/data/<name>/<slug>.json` for those collections; this populates
-   * the detail-fetch URL so the existing dynamic-route singular flow
-   * uses the per-record file (with deferred fields) instead of the
-   * matched-item-from-cascade-collection (without).
+   * `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 files 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 using other param names need an explicit author-written
-   *     `detail:` value.
+   *   - 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
@@ -173,7 +186,10 @@ export default class EntityStore {
     if (!collConfig || typeof collConfig !== 'object') return cfg
     const deferred = Array.isArray(collConfig.deferred) ? collConfig.deferred : null
     if (!deferred || deferred.length === 0) return cfg
-    return { ...cfg, detail: `/data/${schema}/{slug}.json` }
+    const pattern = typeof collConfig.detailUrl === 'string'
+      ? collConfig.detailUrl
+      : `/data/${schema}/{slug}.json`
+    return { ...cfg, detail: pattern }
   }
 
   /**

package/src/index.js

@@ -22,6 +22,7 @@ export { default as ObservableState } from './observable-state.js'
 export { default as singularize } from './singularize.js'
 export { substitutePlaceholders } from './substitute-placeholders.js'
 export { evaluate as evaluateWhere, match as matchWhere } from './where.js'
+export { resolveStyle as resolveRequestStyle, listStyleNames as listRequestStyleNames } from './request-styles/index.js'
 
 /**
  * The singleton Uniweb instance.

package/src/request-styles/flat-query.js

@@ -0,0 +1,146 @@
+/**
+ * flat-query — plain URL query-string style.
+ *
+ * GET-only. Operators become bare query params:
+ *
+ *   ?limit=10
+ *   ?sort=-date                  (single-key, "-" prefix for desc)
+ *   ?sort=-date,title            (multi-key, comma-separated)
+ *   ?dept=biology&tenured=true   (where, flat AND of equalities only)
+ *
+ * The `where:` operator is pushed **only** when the predicate is a flat
+ * AND of equalities on top-level fields. Nested operator objects
+ * (`{ age: { gte: 18 } }`), composition (`and` / `or` / `not`), and
+ * dotted field paths disqualify pushdown — the wire format can't
+ * express them. In those cases flat-query silently skips `where`, and
+ * the default fetcher applies it as a runtime fallback after the
+ * response arrives. This is the documented trade-off for the style's
+ * simplicity: flat-query fits simple REST APIs; richer queries either
+ * evaluate client-side or pick a different style.
+ *
+ * POST requests encode nothing — flat-query is a URL-params shape and
+ * has no meaningful POST representation.
+ *
+ * Use case: public REST APIs like `?dept=biology&limit=10&sort=-date`.
+ * For GraphQL or body-shaped backends, use json-body. For Strapi v4,
+ * use the strapi style.
+ */
+
+export const flatQuery = {
+  name: 'flat-query',
+  canPush: new Set(['where', 'limit', 'sort']),
+  defaultEnvelope: null,
+
+  encode(request, { method, pushCandidates, rename }) {
+    const pushed = new Set()
+    const queryParams = []
+
+    if (method !== 'GET') {
+      // POST has no flat-query representation; silent no-op.
+      return { queryParams, bodyMerge: null, pushed }
+    }
+
+    // where — only flat AND of equalities.
+    if (pushCandidates.has('where') && request.where !== undefined) {
+      const pairs = encodeFlatEqualities(request.where)
+      if (pairs !== null) {
+        for (const [k, v] of pairs) queryParams.push([applyRename(k, rename), v])
+        pushed.add('where')
+      }
+    }
+
+    if (pushCandidates.has('limit') && request.limit !== undefined) {
+      queryParams.push([wireName('limit', 'limit', rename), String(request.limit)])
+      pushed.add('limit')
+    }
+
+    if (pushCandidates.has('sort') && request.sort !== undefined) {
+      const encoded = encodeSort(request.sort)
+      if (encoded !== null) {
+        queryParams.push([wireName('sort', 'sort', rename), encoded])
+        pushed.add('sort')
+      }
+    }
+
+    return { queryParams, bodyMerge: null, pushed }
+  },
+}
+
+/**
+ * Encode a where-object as flat [field, value] pairs. Returns null when
+ * the predicate doesn't fit the flat-AND-equalities shape — caller
+ * falls back to runtime evaluation.
+ */
+function encodeFlatEqualities(where) {
+  if (!where || typeof where !== 'object' || Array.isArray(where)) return null
+  const out = []
+  for (const [key, raw] of Object.entries(where)) {
+    // Composition and operator shorthand disqualify the whole predicate.
+    if (key === 'and' || key === 'or' || key === 'not') return null
+    if (key.includes('.')) return null // dotted path — flat-query can't express nesting
+
+    // Bare primitive → implicit equality.
+    if (isPrimitive(raw)) {
+      out.push([key, stringifyPrimitive(raw)])
+      continue
+    }
+
+    // { eq: primitive } → equality. Anything else disqualifies.
+    if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+      const opKeys = Object.keys(raw)
+      if (opKeys.length === 1 && opKeys[0] === 'eq' && isPrimitive(raw.eq)) {
+        out.push([key, stringifyPrimitive(raw.eq)])
+        continue
+      }
+    }
+
+    return null
+  }
+  return out
+}
+
+/**
+ * Encode `sort: 'date desc'` → `-date`; `sort: 'date desc, title asc'` →
+ * `-date,title`. Returns null on malformed input (caller falls back).
+ */
+function encodeSort(sortExpr) {
+  if (typeof sortExpr !== 'string' || sortExpr.length === 0) return null
+  const parts = sortExpr.split(',').map((s) => s.trim()).filter(Boolean)
+  if (parts.length === 0) return null
+  const encoded = []
+  for (const part of parts) {
+    const [field, dirRaw] = part.split(/\s+/)
+    if (!field) return null
+    const desc = (dirRaw || 'asc').toLowerCase() === 'desc'
+    encoded.push(desc ? `-${field}` : field)
+  }
+  return encoded.join(',')
+}
+
+function isPrimitive(value) {
+  if (value === null) return true
+  const t = typeof value
+  return t === 'string' || t === 'number' || t === 'boolean'
+}
+
+function stringifyPrimitive(value) {
+  if (value === null) return ''
+  return String(value)
+}
+
+function wireName(operator, defaultWire, rename) {
+  if (rename && typeof rename[operator] === 'string' && rename[operator].length > 0) {
+    return rename[operator]
+  }
+  return defaultWire
+}
+
+// `rename` on flat-query's where pushdown doesn't apply to individual
+// field names — authors who need `dept → department` should write
+// their where-objects with the backend's field name directly. rename
+// remains available for `limit` and `sort` wire names.
+function applyRename(fieldName, _rename) {
+  return fieldName
+}
+
+export default flatQuery

package/src/request-styles/index.js

@@ -0,0 +1,61 @@
+/**
+ * Request-style registry.
+ *
+ * A "style" describes how the default fetcher reshapes a normalized
+ * request into wire format — which operators become URL params, which
+ * go into a body, what envelope the response carries. Sites pick a
+ * style on `site.yml fetcher.request.style`; when unset, the ambient
+ * default is `json-body`.
+ *
+ * Styles are shipped by the framework. There is no `registerStyle()`
+ * API for foundations or sites — custom wire shapes are expressed via
+ * foundation-level named transports. Styles are specifically for
+ * reshapings of the framework's own fetcher behavior.
+ *
+ * Internal to @uniweb/core. Consumed by @uniweb/runtime's default-fetcher.
+ */
+
+import { jsonBody } from './json-body.js'
+import { flatQuery } from './flat-query.js'
+import { strapi } from './strapi.js'
+
+const STYLES = new Map([
+  [jsonBody.name, jsonBody],
+  [flatQuery.name, flatQuery],
+  [strapi.name, strapi],
+])
+
+/**
+ * Resolve a style by name. Returns the requested style if registered,
+ * otherwise the ambient default (`json-body`). Unknown names trigger a
+ * one-time dev warning; production silently falls back.
+ *
+ * @param {string|undefined|null} name
+ * @param {{ dev?: boolean }} [options]
+ * @returns {Object} A style module.
+ */
+export function resolveStyle(name, { dev = false } = {}) {
+  if (!name) return jsonBody
+  const style = STYLES.get(name)
+  if (style) return style
+  if (dev && !warnedUnknownStyles.has(name)) {
+    warnedUnknownStyles.add(name)
+    console.warn(
+      `[default-fetcher] unknown request style "${name}"; falling back to "json-body". ` +
+        `Known styles: ${[...STYLES.keys()].join(', ')}.`,
+    )
+  }
+  return jsonBody
+}
+
+const warnedUnknownStyles = new Set()
+
+/**
+ * Sentinel list of names registered at the registry level. Used by tests
+ * and by dev-mode diagnostics; not part of the site-facing contract.
+ */
+export function listStyleNames() {
+  return [...STYLES.keys()]
+}
+
+export { jsonBody, flatQuery, strapi }

package/src/request-styles/json-body.js

@@ -0,0 +1,117 @@
+/**
+ * json-body — the framework's general-purpose request style.
+ *
+ * Ambient default when the site doesn't pick a style. Speaks the
+ * framework's own conventions:
+ *
+ *   GET   — operators travel as URL params prefixed with underscore:
+ *             ?_where=<JSON.stringify(predicate)>
+ *             ?_limit=N
+ *             ?_sort=field:dir       (comma-separated for multi-key)
+ *           The leading underscore avoids collision with backend-
+ *           specific query params the author may have included in `url:`.
+ *
+ *   POST  — operators merge as top-level keys into an object body,
+ *           alongside any author-supplied body. Content-Type defaults
+ *           to `application/json` unless the site set a different one.
+ *           String POST bodies (rare; typically GraphQL-only) don't
+ *           receive operator merge — the string is sent as-is.
+ *
+ * Operator name renames are applied from the `rename:` map passed in
+ * context. Shallow substitutions only — `rename: { limit: pageSize }`
+ * swaps the wire name `_limit` → `pageSize` on GET, or the body key
+ * `limit` → `pageSize` on POST. The operator identity (what `limit`
+ * means in the query) does not change.
+ *
+ * Internal module. Accessed by `default-fetcher.js` via the registry;
+ * never imported directly from outside `@uniweb/runtime`.
+ */
+
+export const jsonBody = {
+  name: 'json-body',
+
+  // Which operators this style knows how to push. The effective push set
+  // is the intersection of this and the site's `supports:` list.
+  canPush: new Set(['where', 'limit', 'sort']),
+
+  // Default response envelope. null = no wrapper (a plain JSON payload).
+  defaultEnvelope: null,
+
+  /**
+   * Encode a request against the json-body conventions.
+   *
+   * @param {Object} request - The normalized fetch request.
+   * @param {Object} ctx
+   * @param {'GET'|'POST'} ctx.method - The method the fetcher chose.
+   * @param {Set<string>} ctx.pushCandidates - Operators present on the
+   *   request AND listed in the site's `supports:`. Style may choose to
+   *   push all, some, or none of these based on what it knows how to
+   *   express on the wire.
+   * @param {Object|null} ctx.rename - Optional { operator → wireName } map.
+   * @returns {{
+   *   queryParams: Array<[string, string]>,
+   *   bodyMerge: Object|null,
+   *   pushed: Set<string>,
+   * }}
+   *   queryParams — pairs appended to the URL's query string.
+   *   bodyMerge   — object merged into the POST body, or null.
+   *   pushed      — the operators that actually rode on the wire.
+   *                 Feeds the fetcher's cache-key derivation and
+   *                 runtime-fallback skip.
+   */
+  encode(request, { method, pushCandidates, rename }) {
+    const pushed = new Set()
+    const queryParams = []
+    let bodyMerge = null
+
+    if (method === 'GET') {
+      if (pushCandidates.has('where') && request.where !== undefined) {
+        queryParams.push([
+          wireName('where', '_where', rename),
+          JSON.stringify(request.where),
+        ])
+        pushed.add('where')
+      }
+      if (pushCandidates.has('limit') && request.limit !== undefined) {
+        queryParams.push([
+          wireName('limit', '_limit', rename),
+          String(request.limit),
+        ])
+        pushed.add('limit')
+      }
+      if (pushCandidates.has('sort') && request.sort !== undefined) {
+        queryParams.push([
+          wireName('sort', '_sort', rename),
+          String(request.sort),
+        ])
+        pushed.add('sort')
+      }
+    } else if (method === 'POST') {
+      const merged = {}
+      if (pushCandidates.has('where') && request.where !== undefined) {
+        merged[wireName('where', 'where', rename)] = request.where
+        pushed.add('where')
+      }
+      if (pushCandidates.has('limit') && request.limit !== undefined) {
+        merged[wireName('limit', 'limit', rename)] = request.limit
+        pushed.add('limit')
+      }
+      if (pushCandidates.has('sort') && request.sort !== undefined) {
+        merged[wireName('sort', 'sort', rename)] = request.sort
+        pushed.add('sort')
+      }
+      if (Object.keys(merged).length > 0) bodyMerge = merged
+    }
+
+    return { queryParams, bodyMerge, pushed }
+  },
+}
+
+function wireName(operator, defaultWire, rename) {
+  if (rename && typeof rename[operator] === 'string' && rename[operator].length > 0) {
+    return rename[operator]
+  }
+  return defaultWire
+}
+
+export default jsonBody

package/src/request-styles/strapi.js

@@ -0,0 +1,232 @@
+/**
+ * strapi — Strapi v4 REST API query style.
+ *
+ * GET-only. Encodes a full where-object into Strapi's bracket-notation
+ * filters:
+ *
+ *   where: { dept: 'biology' }
+ *     → filters[dept][$eq]=biology
+ *
+ *   where: { age: { gte: 18 } }
+ *     → filters[age][$gte]=18
+ *
+ *   where: { 'tenure.start': { gte: 2015 } }
+ *     → filters[tenure][start][$gte]=2015
+ *
+ *   where: { or: [{ a: 1 }, { b: 2 }] }
+ *     → filters[$or][0][a][$eq]=1 & filters[$or][1][b][$eq]=2
+ *
+ *   where: { not: { dept: 'emeritus' } }
+ *     → filters[$not][dept][$eq]=emeritus
+ *
+ *   limit: 10
+ *     → pagination[limit]=10
+ *
+ *   sort: 'date desc'
+ *     → sort=date:desc
+ *
+ *   sort: 'date desc, title asc'
+ *     → sort[0]=date:desc & sort[1]=title:asc
+ *
+ * Response envelope defaults to `{ collection: 'data', item: 'data' }` —
+ * Strapi v4 wraps every response in `{ data, meta }`. Sites can override
+ * via `envelope:` at the site or per-fetch level.
+ *
+ * Operators mapped (where-object → Strapi `$op`):
+ *   eq, ne, gt, gte, lt, lte, in, nin → notIn, like → containsi,
+ *   exists → notNull, and → $and, or → $or, not → $not.
+ *
+ * For operators the where-object supports but Strapi doesn't have a
+ * clean equivalent for, the style leaves them untouched (the default
+ * fetcher applies them as a runtime fallback).
+ */
+
+export const strapi = {
+  name: 'strapi',
+  canPush: new Set(['where', 'limit', 'sort']),
+  defaultEnvelope: { collection: 'data', item: 'data' },
+
+  encode(request, { method, pushCandidates, rename }) {
+    const pushed = new Set()
+    const queryParams = []
+
+    if (method !== 'GET') {
+      // Strapi v4 REST is GET-only for reads.
+      return { queryParams, bodyMerge: null, pushed }
+    }
+
+    if (pushCandidates.has('where') && request.where !== undefined) {
+      const filterKey = wireName('where', 'filters', rename)
+      const pairs = encodeStrapiFilters(request.where, filterKey)
+      if (pairs !== null) {
+        for (const pair of pairs) queryParams.push(pair)
+        pushed.add('where')
+      }
+    }
+
+    if (pushCandidates.has('limit') && request.limit !== undefined) {
+      const limitKey = wireName('limit', 'pagination[limit]', rename)
+      queryParams.push([limitKey, String(request.limit)])
+      pushed.add('limit')
+    }
+
+    if (pushCandidates.has('sort') && request.sort !== undefined) {
+      const sortPairs = encodeStrapiSort(request.sort, wireName('sort', 'sort', rename))
+      if (sortPairs !== null) {
+        for (const pair of sortPairs) queryParams.push(pair)
+        pushed.add('sort')
+      }
+    }
+
+    return { queryParams, bodyMerge: null, pushed }
+  },
+}
+
+// ─── where encoding ────────────────────────────────────────────────────────
+
+// Values are the Strapi operator *with* bracket delimiters, so they
+// concatenate cleanly into a bracketed path like `filters[field][$eq]`.
+const OPERATOR_MAP = {
+  eq: '[$eq]',
+  ne: '[$ne]',
+  gt: '[$gt]',
+  gte: '[$gte]',
+  lt: '[$lt]',
+  lte: '[$lte]',
+  in: '[$in]',
+  nin: '[$notIn]',
+  like: '[$containsi]',    // case-insensitive substring — closest Strapi analog
+  exists: '[$notNull]',    // overridden below for exists:false → [$null]
+}
+
+/**
+ * Walk a where-object and emit [paramName, paramValue] pairs encoding
+ * Strapi's bracket syntax. Returns null if any branch is unencodable
+ * (caller falls back to runtime evaluation for the whole predicate).
+ */
+function encodeStrapiFilters(where, rootKey) {
+  const out = []
+  try {
+    walkPredicate(where, [rootKey], out)
+  } catch (err) {
+    if (err && err.unencodable) return null
+    throw err
+  }
+  return out.length > 0 ? out : null
+}
+
+function walkPredicate(node, path, out) {
+  if (!node || typeof node !== 'object' || Array.isArray(node)) {
+    throwUnencodable()
+  }
+
+  // Top-level each key is either composition ($and/$or/$not) or a field.
+  for (const [key, value] of Object.entries(node)) {
+    if (key === 'and' || key === 'or') {
+      if (!Array.isArray(value)) throwUnencodable()
+      value.forEach((sub, i) => {
+        walkPredicate(sub, [...path, `[$${key}]`, `[${i}]`], out)
+      })
+    } else if (key === 'not') {
+      walkPredicate(value, [...path, '[$not]'], out)
+    } else {
+      emitFieldPredicate(key, value, path, out)
+    }
+  }
+}
+
+function emitFieldPredicate(field, value, path, out) {
+  // Dotted paths become nested bracket segments: `tenure.start` →
+  // `[tenure][start]`.
+  const fieldSegments = field.split('.').map((seg) => `[${seg}]`)
+  const fieldPath = [...path, ...fieldSegments]
+
+  // Bare primitive → implicit eq.
+  if (isPrimitive(value)) {
+    out.push([joinPath(fieldPath) + '[$eq]', stringifyPrimitive(value)])
+    return
+  }
+
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    for (const [opName, opValue] of Object.entries(value)) {
+      const strapiOp = OPERATOR_MAP[opName]
+      if (!strapiOp) throwUnencodable()
+
+      if (opName === 'in' || opName === 'nin') {
+        if (!Array.isArray(opValue)) throwUnencodable()
+        opValue.forEach((item, i) => {
+          if (!isPrimitive(item)) throwUnencodable()
+          out.push([joinPath(fieldPath) + strapiOp + `[${i}]`, stringifyPrimitive(item)])
+        })
+        continue
+      }
+
+      if (opName === 'exists') {
+        // { exists: true }  → field IS NOT NULL  → [field][$notNull]=true
+        // { exists: false } → field IS NULL      → [field][$null]=true
+        const wantsPresent = !!opValue
+        out.push([joinPath(fieldPath) + (wantsPresent ? '[$notNull]' : '[$null]'), 'true'])
+        continue
+      }
+
+      if (!isPrimitive(opValue)) throwUnencodable()
+      out.push([joinPath(fieldPath) + strapiOp, stringifyPrimitive(opValue)])
+    }
+    return
+  }
+
+  throwUnencodable()
+}
+
+function joinPath(segments) {
+  return segments.join('')
+}
+
+function throwUnencodable() {
+  const err = new Error('unencodable predicate')
+  err.unencodable = true
+  throw err
+}
+
+// ─── sort encoding ─────────────────────────────────────────────────────────
+
+function encodeStrapiSort(sortExpr, baseKey) {
+  if (typeof sortExpr !== 'string' || sortExpr.length === 0) return null
+  const parts = sortExpr.split(',').map((s) => s.trim()).filter(Boolean)
+  if (parts.length === 0) return null
+
+  const encoded = []
+  for (const part of parts) {
+    const [field, dirRaw] = part.split(/\s+/)
+    if (!field) return null
+    const dir = (dirRaw || 'asc').toLowerCase() === 'desc' ? 'desc' : 'asc'
+    encoded.push(`${field}:${dir}`)
+  }
+
+  if (encoded.length === 1) {
+    return [[baseKey, encoded[0]]]
+  }
+  return encoded.map((v, i) => [`${baseKey}[${i}]`, v])
+}
+
+// ─── helpers ───────────────────────────────────────────────────────────────
+
+function isPrimitive(value) {
+  if (value === null) return true
+  const t = typeof value
+  return t === 'string' || t === 'number' || t === 'boolean'
+}
+
+function stringifyPrimitive(value) {
+  if (value === null) return ''
+  return String(value)
+}
+
+function wireName(operator, defaultWire, rename) {
+  if (rename && typeof rename[operator] === 'string' && rename[operator].length > 0) {
+    return rename[operator]
+  }
+  return defaultWire
+}
+
+export default strapi