@uniweb/build 0.9.5 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.9.5",
+  "version": "0.10.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -54,8 +54,8 @@
     "@uniweb/theming": "0.1.3"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "0.7.5",
     "@uniweb/content-reader": "1.1.4",
+    "@uniweb/runtime": "0.8.0",
     "@uniweb/schemas": "0.2.1"
   },
   "peerDependencies": {
@@ -65,7 +65,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "0.6.2"
+    "@uniweb/core": "0.7.0"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/dev-backend.js

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+/**
+ * Dev backend for testing Uniweb sites with `supports: [where, limit, sort]`.
+ *
+ * Reads a directory of YAML collections (each subfolder is a collection,
+ * each .yml file inside is a record) and exposes them via HTTP. Evaluates
+ * where-objects on the server side using @uniweb/core's matchWhere — the
+ * exact same evaluator the runtime uses as a fallback. This lets you
+ * develop a site against a "real" backend without standing up a database.
+ *
+ * Wire format matches the framework default fetcher's pushdown conventions
+ * (see framework/runtime/src/default-fetcher.js):
+ *
+ *   GET  /api/{collection}                        — full collection
+ *   GET  /api/{collection}?_where=<JSON>          — filtered by where-object
+ *   GET  /api/{collection}?_limit=N               — first N records
+ *   GET  /api/{collection}?_sort=field:dir        — sorted
+ *   POST /api/{collection}  body: { where, ... } — operators in body
+ *   GET  /api/{collection}/{slug}                 — single record
+ *
+ * Usage:
+ *   node scripts/framework/dev-backend.js --collections <path> [--port N]
+ *
+ * Example (academic-metrics):
+ *   node scripts/framework/dev-backend.js \
+ *     --collections framework/templates/academic-metrics/site/collections \
+ *     --port 8080
+ *
+ * Then in the site's site.yml:
+ *   fetcher:
+ *     baseUrl: http://localhost:8080
+ *     supports: [where, limit, sort]
+ *
+ * And rewrite collection refs to URLs, e.g.:
+ *   fetch: { url: /api/members, schema: members }
+ */
+
+import { createServer } from 'node:http'
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { resolve, join, basename, extname } from 'node:path'
+import { parseArgs } from 'node:util'
+import yaml from 'js-yaml'
+import { matchWhere } from '@uniweb/core'
+
+const { values } = parseArgs({
+  options: {
+    collections: { type: 'string', short: 'c' },
+    port: { type: 'string', short: 'p', default: '8080' },
+  },
+})
+
+if (!values.collections) {
+  console.error('Usage: dev-backend.js --collections <path> [--port N]')
+  process.exit(1)
+}
+
+const COLLECTIONS_DIR = resolve(values.collections)
+const PORT = Number(values.port)
+
+if (!existsSync(COLLECTIONS_DIR)) {
+  console.error(`Collections directory not found: ${COLLECTIONS_DIR}`)
+  process.exit(1)
+}
+
+// ─── Load collections from disk ─────────────────────────────────────────────
+
+async function loadCollection(dir) {
+  const files = await readdir(dir)
+  const items = []
+  for (const file of files) {
+    const ext = extname(file).toLowerCase()
+    if (!['.yml', '.yaml', '.json'].includes(ext)) continue
+    const filepath = join(dir, file)
+    const content = await readFile(filepath, 'utf8')
+    let data
+    try {
+      data = ext === '.json' ? JSON.parse(content) : yaml.load(content)
+    } catch (err) {
+      console.warn(`[dev-backend] Failed to parse ${filepath}: ${err.message}`)
+      continue
+    }
+    if (data == null) continue
+    const slug = basename(file, ext)
+    if (Array.isArray(data)) {
+      // Array-form file: each element is a record.
+      for (const record of data) {
+        if (record && typeof record === 'object') items.push(record)
+      }
+    } else if (typeof data === 'object') {
+      items.push({ slug, ...data })
+    }
+  }
+  return items
+}
+
+async function loadAllCollections() {
+  const entries = await readdir(COLLECTIONS_DIR)
+  const collections = {}
+  for (const name of entries) {
+    const fullPath = join(COLLECTIONS_DIR, name)
+    const s = await stat(fullPath)
+    if (!s.isDirectory()) continue
+    collections[name] = await loadCollection(fullPath)
+    console.log(`[dev-backend] Loaded ${collections[name].length} items from "${name}"`)
+  }
+  return collections
+}
+
+// ─── Operator handling (mirrors default-fetcher pushdown wire format) ───────
+
+function applyOperators(items, operators) {
+  let result = items
+  if (operators.where) {
+    result = matchWhere(operators.where, result)
+  }
+  if (operators.sort) {
+    result = applySort(result, operators.sort)
+  }
+  if (typeof operators.limit === 'number' && operators.limit > 0) {
+    result = result.slice(0, operators.limit)
+  }
+  return result
+}
+
+function applySort(items, sortExpr) {
+  const sorts = String(sortExpr).split(',').map((s) => {
+    const [field, dir = 'asc'] = s.trim().split(/\s+/)
+    return { field, desc: dir.toLowerCase() === 'desc' }
+  })
+  return [...items].sort((a, b) => {
+    for (const { field, desc } of sorts) {
+      const av = a?.[field] ?? ''
+      const bv = b?.[field] ?? ''
+      if (av < bv) return desc ? 1 : -1
+      if (av > bv) return desc ? -1 : 1
+    }
+    return 0
+  })
+}
+
+function parseOperatorsFromQuery(searchParams) {
+  const out = {}
+  if (searchParams.has('_where')) {
+    try {
+      out.where = JSON.parse(searchParams.get('_where'))
+    } catch (err) {
+      throw new Error(`Invalid _where JSON: ${err.message}`)
+    }
+  }
+  if (searchParams.has('_limit')) {
+    out.limit = Number(searchParams.get('_limit'))
+  }
+  if (searchParams.has('_sort')) {
+    out.sort = searchParams.get('_sort')
+  }
+  return out
+}
+
+async function readJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    let body = ''
+    req.on('data', (chunk) => { body += chunk })
+    req.on('end', () => {
+      if (!body) return resolve({})
+      try { resolve(JSON.parse(body)) }
+      catch (err) { reject(new Error(`Invalid JSON body: ${err.message}`)) }
+    })
+    req.on('error', reject)
+  })
+}
+
+// ─── HTTP server ────────────────────────────────────────────────────────────
+
+function send(res, status, body) {
+  res.writeHead(status, {
+    'Content-Type': 'application/json',
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type',
+  })
+  res.end(typeof body === 'string' ? body : JSON.stringify(body))
+}
+
+async function handleRequest(req, res, collections) {
+  if (req.method === 'OPTIONS') return send(res, 204, '')
+
+  const url = new URL(req.url, `http://${req.headers.host}`)
+  const match = url.pathname.match(/^\/api\/([^/]+)(?:\/([^/]+))?$/)
+  if (!match) return send(res, 404, { error: 'Not found' })
+
+  const [, collectionName, slug] = match
+  const items = collections[collectionName]
+  if (!items) return send(res, 404, { error: `Unknown collection: ${collectionName}` })
+
+  // Single record by slug.
+  if (slug) {
+    const item = items.find((r) => r?.slug === slug)
+    if (!item) return send(res, 404, { error: `No record with slug "${slug}"` })
+    return send(res, 200, item)
+  }
+
+  // Collection — apply operators from query string (GET) or body (POST).
+  let operators
+  try {
+    operators = req.method === 'POST'
+      ? await readJsonBody(req)
+      : parseOperatorsFromQuery(url.searchParams)
+  } catch (err) {
+    return send(res, 400, { error: err.message })
+  }
+
+  let result
+  try {
+    result = applyOperators(items, operators)
+  } catch (err) {
+    return send(res, 400, { error: `Operator evaluation failed: ${err.message}` })
+  }
+  return send(res, 200, result)
+}
+
+// ─── Boot ───────────────────────────────────────────────────────────────────
+
+const collections = await loadAllCollections()
+const knownCollections = Object.keys(collections)
+if (knownCollections.length === 0) {
+  console.warn('[dev-backend] No collections found.')
+}
+
+const server = createServer((req, res) => {
+  handleRequest(req, res, collections).catch((err) => {
+    console.error('[dev-backend] Request handler threw:', err)
+    send(res, 500, { error: 'Internal server error' })
+  })
+})
+
+server.listen(PORT, () => {
+  console.log(`[dev-backend] Listening on http://localhost:${PORT}`)
+  console.log(`[dev-backend] Collections: ${knownCollections.join(', ') || '(none)'}`)
+  console.log('[dev-backend] Endpoints:')
+  for (const name of knownCollections) {
+    console.log(`  GET  /api/${name}                  — full collection`)
+    console.log(`  GET  /api/${name}?_where=<JSON>    — filtered`)
+    console.log(`  GET  /api/${name}/{slug}            — single record`)
+    console.log(`  POST /api/${name}  body: { where } — operators in body`)
+  }
+})

package/src/site/collection-processor.js

@@ -79,7 +79,8 @@ function parseCollectionConfig(name, config) {
       sort: null,
       filter: null,
       limit: 0,
-      excerpt: { maxLength: 160 }
+      excerpt: { maxLength: 160 },
+      deferred: null,
     }
   }
 
@@ -93,7 +94,24 @@ function parseCollectionConfig(name, config) {
     excerpt: {
       maxLength: config.excerpt?.maxLength || 160,
       field: config.excerpt?.field || null
-    }
+    },
+    // `deferred:` lists fields that are heavy (article body, full nested
+    // arrays). Those fields are stripped from the cascade payload that
+    // ships with `data: <name>` declarations, and per-record full files
+    // are emitted at public/data/<name>/<slug>.json. Components that
+    // need the full record fetch the per-record file on demand, either
+    // automatically on dynamic-route pages (entity-store routes the
+    // singular detail there) or via the kit's useEntityDetail hook.
+    deferred: Array.isArray(config.deferred) ? config.deferred.slice() : null,
+    // `queryable:` declares the queryable surface — which fields a
+    // foundation can offer for filtering UI, with their type and
+    // type-specific metadata (enum options, range bounds). Foundations
+    // read this metadata via the kit's useCollectionQueryable hook to
+    // render filter controls and compose where-objects from user
+    // interactions. The framework doesn't validate the shape here —
+    // foundations get whatever the author wrote; documentation defines
+    // the conventional types (enum/boolean/range/text).
+    queryable: (config.queryable && typeof config.queryable === 'object') ? config.queryable : null,
   }
 }
 
@@ -578,7 +596,7 @@ export async function processCollections(siteDir, collectionsConfig, collections
  * })
  * // Creates public/data/articles.json
  */
-export async function writeCollectionFiles(siteDir, collections) {
+export async function writeCollectionFiles(siteDir, collections, collectionsConfig = null) {
   if (!collections || Object.keys(collections).length === 0) {
     return
   }
@@ -587,9 +605,44 @@ export async function writeCollectionFiles(siteDir, collections) {
   await mkdir(dataDir, { recursive: true })
 
   for (const [name, items] of Object.entries(collections)) {
-    const filepath = join(dataDir, `${name}.json`)
-    await writeFile(filepath, JSON.stringify(items, null, 2))
-    console.log(`[collection-processor] Generated ${filepath} (${items.length} items)`)
+    const rawConfig = collectionsConfig?.[name]
+    const parsed = rawConfig ? parseCollectionConfig(name, rawConfig) : null
+    const deferred = parsed?.deferred
+
+    if (deferred && deferred.length > 0) {
+      // `deferred:` is set — emit two payloads:
+      //   1. The cascade JSON at /data/<name>.json with deferred fields stripped.
+      //      This is what `data: <name>` declarations deliver everywhere.
+      //   2. Per-record full files at /data/<name>/<slug>.json with every field.
+      //      Dynamic-route singular fetches and useEntityDetail hooks read these.
+      const recordsDir = join(dataDir, name)
+      await mkdir(recordsDir, { recursive: true })
+
+      let perRecordCount = 0
+      for (const item of items) {
+        if (!item || typeof item !== 'object' || !item.slug) continue
+        const recordPath = join(recordsDir, `${item.slug}.json`)
+        await writeFile(recordPath, JSON.stringify(item, null, 2))
+        perRecordCount++
+      }
+
+      const stripped = items.map((item) => {
+        if (!item || typeof item !== 'object') return item
+        const out = { ...item }
+        for (const field of deferred) delete out[field]
+        return out
+      })
+      const cascadePath = join(dataDir, `${name}.json`)
+      await writeFile(cascadePath, JSON.stringify(stripped, null, 2))
+      console.log(
+        `[collection-processor] Generated ${cascadePath} (${items.length} items, ` +
+        `deferred: [${deferred.join(', ')}]) + ${perRecordCount} per-record files`
+      )
+    } else {
+      const filepath = join(dataDir, `${name}.json`)
+      await writeFile(filepath, JSON.stringify(items, null, 2))
+      console.log(`[collection-processor] Generated ${filepath} (${items.length} items)`)
+    }
   }
 }
 

package/src/site/data-fetcher.js

@@ -20,6 +20,7 @@ import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { existsSync } from 'node:fs'
 import yaml from 'js-yaml'
+import { matchWhere } from '@uniweb/core'
 
 /**
  * Infer schema name from path or URL
@@ -157,19 +158,52 @@ export function applySort(items, sortExpr) {
 }
 
 /**
- * Apply post-processing to fetched data (filter, sort, limit)
+ * Apply a where-object predicate to an array of items.
+ *
+ * The where-object is the new query language (see @uniweb/core's
+ * matchWhere and the architecture doc at
+ * kb/framework/architecture/data-fetching.md). Structured JSON
+ * predicate; the runtime evaluator walks the object against each
+ * record. Same shape ships to backends that declare `supports: [where]`.
+ *
+ * @param {Array} items - Items to filter
+ * @param {object} where - Where-object predicate
+ * @returns {Array} Filtered items in source order
+ */
+export function applyWhere(items, where) {
+  if (!where || !Array.isArray(items)) return items
+  return matchWhere(where, items)
+}
+
+/**
+ * Apply post-processing to fetched data (where, filter, sort, limit)
+ *
+ * Order of operations:
+ *   1. where (where-object predicate, new) — narrows the record set
+ *   2. filter (legacy DSL string) — narrows further if both are set; deprecated
+ *   3. sort
+ *   4. limit
+ *
+ * `where:` and `filter:` may both appear during the deprecation window
+ * but in practice authors should pick one. Using `filter:` emits a dev
+ * warning at parse time (see parseFetchConfig).
  *
  * @param {any} data - Fetched data
- * @param {object} config - Fetch config with optional filter, sort, limit
+ * @param {object} config - Fetch config with optional where, filter, sort, limit
  * @returns {any} Processed data
  */
 export function applyPostProcessing(data, config) {
   if (!data || !Array.isArray(data)) return data
-  if (!config.filter && !config.sort && !config.limit) return data
+  if (!config.where && !config.filter && !config.sort && !config.limit) return data
 
   let result = data
 
-  // Apply filter first
+  // Apply where-object predicate first (new path)
+  if (config.where) {
+    result = applyWhere(result, config.where)
+  }
+
+  // Apply legacy filter expression (deprecated)
   if (config.filter) {
     result = applyFilter(result, config.filter)
   }
@@ -242,17 +276,20 @@ export function parseFetchConfig(fetch) {
         'Accepted for one release; will be removed in the next minor.'
       )
     }
+    if (fetch.filter !== undefined) warnFilterDeprecated()
     return {
       refine: true,
       ...(fetch.detail !== undefined ? { detail: fetch.detail } : {}),
       ...(fetch.limit !== undefined ? { limit: fetch.limit } : {}),
       ...(fetch.sort !== undefined ? { sort: fetch.sort } : {}),
+      ...(fetch.where !== undefined ? { where: fetch.where } : {}),
       ...(fetch.filter !== undefined ? { filter: fetch.filter } : {}),
     }
   }
 
   // Collection reference: { collection: 'articles', limit: 3 }
   if (fetch.collection) {
+    if (fetch.filter !== undefined) warnFilterDeprecated()
     return {
       path: `/data/${fetch.collection}.json`,
       url: undefined,
@@ -260,9 +297,11 @@ export function parseFetchConfig(fetch) {
       prerender: fetch.prerender ?? true,
       merge: fetch.merge ?? false,
       transform: fetch.transform,
-      // Post-processing options
+      // Query operators
+      where: fetch.where,
       limit: fetch.limit,
       sort: fetch.sort,
+      // Legacy post-processing (deprecated, see warning above)
       filter: fetch.filter,
     }
   }
@@ -275,15 +314,19 @@ export function parseFetchConfig(fetch) {
     merge = false,
     transform,
     detail,
-    // Post-processing options (also supported for path/url fetches)
+    // Query operators
+    where,
     limit,
     sort,
+    // Legacy post-processing (deprecated)
     filter,
   } = fetch
 
   // Must have either path or url
   if (!path && !url) return null
 
+  if (filter !== undefined) warnFilterDeprecated()
+
   return {
     path,
     url,
@@ -292,13 +335,27 @@ export function parseFetchConfig(fetch) {
     merge,
     transform,
     detail,
-    // Post-processing options
+    // Query operators
+    where,
     limit,
     sort,
+    // Legacy post-processing (deprecated)
     filter,
   }
 }
 
+let filterDeprecationWarned = false
+function warnFilterDeprecated() {
+  if (filterDeprecationWarned) return
+  filterDeprecationWarned = true
+  console.warn(
+    "[uniweb] 'fetch: { filter: ... }' (DSL string) is deprecated; use 'where: { ... }' " +
+    'with a where-object. Example: where: { tags: \"featured\" } instead of ' +
+    "filter: 'tags contains featured'. " +
+    'Accepted for one release; will be removed in the next minor.'
+  )
+}
+
 /**
  * Execute a fetch operation
  *

package/src/site/plugin.js

@@ -556,7 +556,7 @@ export function siteContentPlugin(options = {}) {
           if (collectionsConfig) {
             console.log('[site-content] Processing content collections...')
             const collections = await processCollections(resolvedSitePath, collectionsConfig, resolvedCollectionsBase, basePath)
-            await writeCollectionFiles(resolvedSitePath, collections)
+            await writeCollectionFiles(resolvedSitePath, collections, collectionsConfig)
           }
         } catch (err) {
           console.warn('[site-content] Early collection processing failed:', err.message)
@@ -593,7 +593,7 @@ export function siteContentPlugin(options = {}) {
         if (isProduction && siteContent.config?.collections) {
           console.log('[site-content] Processing content collections...')
           const collections = await processCollections(resolvedSitePath, siteContent.config.collections, resolvedCollectionsBase, basePath)
-          await writeCollectionFiles(resolvedSitePath, collections)
+          await writeCollectionFiles(resolvedSitePath, collections, siteContent.config.collections)
         }
 
         // Execute data fetches in dev mode
@@ -656,7 +656,7 @@ export function siteContentPlugin(options = {}) {
               const collections = collectionsConfig || siteContent?.config?.collections
               if (collections) {
                 const processed = await processCollections(resolvedSitePath, collections, resolvedCollectionsBase, basePath)
-                await writeCollectionFiles(resolvedSitePath, processed)
+                await writeCollectionFiles(resolvedSitePath, processed, collections)
               }
               // Send full reload to client
               server.ws.send({ type: 'full-reload' })