@uniweb/core 0.5.14 → 0.5.15

package/package.json

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

package/src/block.js

@@ -148,6 +148,45 @@ export default class Block {
     Object.seal(this)
   }
 
+  /**
+   * The resolved URL path of the current page (e.g. /blog or /blog/1).
+   * Use this to build child links: `${block.path}/${item.id}`
+   *
+   * Uses page.getNavRoute() which returns the path with its leading slash intact
+   * and normalizes /index suffixes to the folder route. getNormalizedRoute() is
+   * intentionally NOT used here — it strips the leading slash (designed for route
+   * comparison), which would produce relative paths and cause double-segment URLs.
+   *
+   * Works in all scenarios:
+   * - Static pages: page.route (/blog)
+   * - Dynamic pages: concrete route (/blog/1), set by _createDynamicPage
+   * - Editor: set by the editor to the page being previewed
+   * - SSR/prerender: set from page data at build time
+   */
+  get path() {
+    return this.page.getNavRoute()
+  }
+
+  /**
+   * The parent page's URL path, one level up from the current page.
+   * Use this for "Back" links in detail pages: /blog/1 → /blog
+   *
+   * For dynamic pages uses templateRoute (/blog/:id → /blog) rather than
+   * the concrete route, so it correctly points to the index page regardless
+   * of the param value.
+   */
+  get parentPath() {
+    // Dynamic page: derive parent from the route template, not the concrete URL
+    // e.g. templateRoute = '/blog/:id' → parent = '/blog'
+    if (this.dynamicContext?.templateRoute) {
+      const tmpl = this.dynamicContext.templateRoute
+      return tmpl.split('/').slice(0, -1).join('/') || '/'
+    }
+    // Static page: go one level up from the normalized route
+    const p = this.path
+    return p.split('/').slice(0, -1).join('/') || '/'
+  }
+
   /**
    * Parse content into structured format using semantic-parser
    * Supports multiple content formats:

package/src/datastore.js

@@ -25,10 +25,23 @@ export default class DataStore {
     this._cache = new Map()
     this._inflight = new Map()
     this._fetcher = null
+    this._transforms = new Map()
+    this._listeners = new Set()
 
     Object.seal(this)
   }
 
+  /**
+   * Subscribe to data updates. Returns an unsubscribe function.
+   * Called by PageRenderer to re-render when dynamic page data arrives.
+   * @param {Function} fn - Called whenever new data is stored
+   * @returns {Function} unsubscribe
+   */
+  onUpdate(fn) {
+    this._listeners.add(fn)
+    return () => this._listeners.delete(fn)
+  }
+
   /**
    * Register the fetcher function (called by runtime at startup).
    * @param {Function} fn - (config) => Promise<{ data, error? }>
@@ -37,6 +50,16 @@ export default class DataStore {
     this._fetcher = fn
   }
 
+  /**
+   * Register a named transform function.
+   * Named transforms are applied after the fetcher returns, before caching.
+   * @param {string} name - Transform name (e.g. 'profiles')
+   * @param {Function} fn - (data, config) => transformedData
+   */
+  registerTransform(name, fn) {
+    this._transforms.set(name, fn)
+  }
+
   /**
    * Check whether data for this config is cached.
    * @param {Object} config - Fetch config
@@ -63,6 +86,7 @@ export default class DataStore {
    */
   set(config, data) {
     this._cache.set(cacheKey(config), data)
+    this._listeners.forEach((fn) => fn())
   }
 
   /**
@@ -95,10 +119,22 @@ export default class DataStore {
     // Miss — execute fetch
     const promise = this._fetcher(config).then((result) => {
       this._inflight.delete(key)
-      if (result.data !== undefined && result.data !== null) {
-        this._cache.set(key, result.data)
+      let data = result.data
+      // Apply named transform if registered (dot-path transforms
+      // are handled by the fetcher itself via getNestedValue)
+      if (
+        data !== undefined &&
+        data !== null &&
+        config.transform &&
+        this._transforms.has(config.transform)
+      ) {
+        data = this._transforms.get(config.transform)(data, config)
+      }
+      if (data !== undefined && data !== null) {
+        this._cache.set(key, data)
+        this._listeners.forEach((fn) => fn())
       }
-      return result
+      return { ...result, data }
     })
 
     this._inflight.set(key, promise)
@@ -111,5 +147,6 @@ export default class DataStore {
   clear() {
     this._cache.clear()
     this._inflight.clear()
+    this._transforms.clear()
   }
 }

package/src/entity-store.js

@@ -22,6 +22,49 @@ export default class EntityStore {
     Object.seal(this)
   }
 
+  /**
+   * Whether a component wants detail-URL resolution on dynamic pages.
+   * Default true. Set to false via `data: { inherit: true, detail: false }`
+   * to receive the full collection (minus the active item) instead.
+   *
+   * @param {Object} meta
+   * @returns {boolean}
+   */
+  _shouldInheritDetail(meta, block) {
+    // Block-level fetch inherit override takes priority over meta
+    const bf = block?.fetch
+    if (bf?.inherit === true && bf?.detail !== undefined) return bf.detail !== false
+    if (!meta) return true
+    return meta.inheritDetail !== false
+  }
+
+  _inheritLimit(meta, block) {
+    // Block-level fetch inherit override takes priority over meta
+    const bf = block?.fetch
+    if (bf?.inherit === true && bf?.limit > 0) return bf.limit
+    return (meta?.inheritLimit > 0) ? meta.inheritLimit : null
+  }
+
+  _inheritOrder(block) {
+    const bf = block?.fetch
+    if (bf?.inherit === true && bf?.order?.orderBy) return bf.order
+    return null
+  }
+
+  _sortItems(items, order) {
+    if (!order?.orderBy || !Array.isArray(items) || items.length === 0) return items
+    const { orderBy, sortOrder = 'ASC' } = order
+    const desc = sortOrder === 'DESC'
+    return [...items].sort((a, b) => {
+      const av = a[orderBy] ?? ''
+      const bv = b[orderBy] ?? ''
+      const cmp = typeof av === 'string' && typeof bv === 'string'
+        ? av.localeCompare(bv)
+        : (av > bv ? 1 : av < bv ? -1 : 0)
+      return desc ? -cmp : cmp
+    })
+  }
+
   /**
    * Determine which schemas a component requests.
    *
@@ -78,8 +121,8 @@ export default class EntityStore {
 
     const sources = []
 
-    // 1. Block-level fetch
-    if (block.fetch) {
+    // 1. Block-level fetch (skip inherit-merge configs — they have no URL, only override props)
+    if (block.fetch && !block.fetch.inherit) {
       sources.push(block.fetch)
     }
 
@@ -140,7 +183,13 @@ export default class EntityStore {
 
     if (detail === 'rest') {
       // REST convention: {baseUrl}/{paramValue}
-      detailUrl = `${baseUrl.replace(/\/$/, '')}/${encodeURIComponent(paramValue)}`
+      // Preserve query string (auth params like token, profileLang) — only insert
+      // the param value before the '?', not after.
+      const [basePath, queryString] = baseUrl.split('?')
+      const cleanBase = basePath.replace(/\/$/, '')
+      detailUrl = queryString
+        ? `${cleanBase}/${encodeURIComponent(paramValue)}?${queryString}`
+        : `${cleanBase}/${encodeURIComponent(paramValue)}`
     } else if (detail === 'query') {
       // Query param convention: {baseUrl}?{paramName}={paramValue}
       const sep = baseUrl.includes('?') ? '&' : '?'
@@ -199,34 +248,87 @@ export default class EntityStore {
    * @returns {{ status: 'ready'|'pending'|'none', data: Object|null }}
    */
   resolve(block, meta) {
-    const requested = this._getRequestedSchemas(meta)
+    let requested = this._getRequestedSchemas(meta)
+
+    // If the component doesn't declare inheritData but the block itself
+    // has a fetch config (e.g. data_source_info converted to fetch),
+    // use the block's schema directly. Block-level fetch is an explicit
+    // data assignment, not inheritance.
+    if (requested === null && block.fetch) {
+      const blockFetchList = Array.isArray(block.fetch) ? block.fetch : [block.fetch]
+      const schemas = blockFetchList
+        .filter((cfg) => cfg.schema)
+        .map((cfg) => cfg.schema)
+      if (schemas.length > 0) {
+        requested = schemas
+      }
+    }
+
     if (requested === null) {
       return { status: 'none', data: null }
     }
 
     // Walk hierarchy for fetch configs
     const configs = this._findFetchConfigs(block, requested)
+
     if (configs.size === 0) {
       return { status: 'none', data: null }
     }
 
     // Check DataStore cache for each config
     const dynamicContext = block.dynamicContext || block.page?.dynamicContext
+    const inheritDetail = this._shouldInheritDetail(meta, block)
+    const limit = this._inheritLimit(meta, block)
+    const order = this._inheritOrder(block)
     const data = {}
     let allCached = true
 
     for (const [schema, cfg] of configs) {
-      if (this.dataStore.has(cfg)) {
-        data[schema] = this.dataStore.get(cfg)
+      if (dynamicContext && cfg.detail && !inheritDetail) {
+        // detail: false — return collection minus the active item (sidebar/related use case)
+        if (this.dataStore.has(cfg)) {
+          const { paramName, paramValue } = dynamicContext
+          const items = this.dataStore.get(cfg)
+          let filtered = Array.isArray(items)
+            ? items.filter((item) => String(item[paramName]) !== String(paramValue))
+            : items
+          if (order) filtered = this._sortItems(filtered, order)
+          data[schema] = limit && Array.isArray(filtered) ? filtered.slice(0, limit) : filtered
+        } else {
+          allCached = false
+        }
       } else if (dynamicContext && cfg.detail) {
-        // Detail query: check if the single-entity result is cached
-        const detailCfg = this._buildDetailConfig(cfg, dynamicContext)
-        if (detailCfg && this.dataStore.has(detailCfg)) {
+        // Collection-first detail resolution:
+        // The collection acts as the access gate — the item must exist in the
+        // cached collection before we'll serve (or fetch) its detail data.
+        if (this.dataStore.has(cfg)) {
+          const collectionItems = this.dataStore.get(cfg)
+          const { paramName, paramValue } = dynamicContext
           const singularKey = singularize(schema) || schema
-          data[singularKey] = this.dataStore.get(detailCfg)
+          const match = Array.isArray(collectionItems)
+            ? collectionItems.find((item) => String(item[paramName]) === String(paramValue))
+            : null
+
+          if (!match) {
+            // Item not in collection — definitive "not found" (content gate).
+            data[singularKey] = null
+          } else {
+            // Item is valid. Check if the detail result is already cached.
+            const detailCfg = this._buildDetailConfig(cfg, dynamicContext)
+            if (detailCfg && this.dataStore.has(detailCfg)) {
+              data[singularKey] = this.dataStore.get(detailCfg)
+            } else if (detailCfg) {
+              allCached = false // Collection cached, item valid, detail still needed
+            } else {
+              data[singularKey] = match // No detail URL — use collection item directly
+            }
+          }
         } else {
-          allCached = false
+          allCached = false // Collection not yet cached — must fetch it first
         }
+      } else if (this.dataStore.has(cfg)) {
+        const items = this.dataStore.get(cfg)
+        data[schema] = order ? this._sortItems(items, order) : items
       } else {
         allCached = false
       }
@@ -248,7 +350,19 @@ export default class EntityStore {
    * @returns {Promise<{ data: Object|null }>}
    */
   async fetch(block, meta) {
-    const requested = this._getRequestedSchemas(meta)
+    let requested = this._getRequestedSchemas(meta)
+
+    // Same block-level fetch fallback as resolve()
+    if (requested === null && block.fetch) {
+      const blockFetchList = Array.isArray(block.fetch) ? block.fetch : [block.fetch]
+      const schemas = blockFetchList
+        .filter((cfg) => cfg.schema)
+        .map((cfg) => cfg.schema)
+      if (schemas.length > 0) {
+        requested = schemas
+      }
+    }
+
     if (requested === null) {
       return { data: null }
     }
@@ -258,42 +372,82 @@ export default class EntityStore {
       return { data: null }
     }
 
-    // Fetch all missing configs in parallel
+    // Fetch all missing configs
     const dynamicContext = block.dynamicContext || block.page?.dynamicContext
+    const inheritDetail = this._shouldInheritDetail(meta, block)
+    const limit = this._inheritLimit(meta, block)
+    const order = this._inheritOrder(block)
+
     const data = {}
-    const fetchPromises = []
+    const parallelFetches = []
 
     for (const [schema, cfg] of configs) {
-      // Detail query optimization: on template pages, if the collection
-      // isn't cached and a detail convention is defined, fetch just the
-      // single entity instead of the full collection.
-      if (dynamicContext && cfg.detail && !this.dataStore.has(cfg)) {
+      if (dynamicContext && cfg.detail && !inheritDetail) {
+        // detail: false — fetch collection and return it minus the active item
+        // (sidebar / related-posts use case on a dynamic page)
+        let collectionItems = this.dataStore.has(cfg) ? this.dataStore.get(cfg) : null
+        if (collectionItems === null) {
+          const result = await this.dataStore.fetch(cfg)
+          collectionItems = Array.isArray(result.data) ? result.data : null
+        }
+        const { paramName, paramValue } = dynamicContext
+        let filtered = Array.isArray(collectionItems)
+          ? collectionItems.filter((item) => String(item[paramName]) !== String(paramValue))
+          : (collectionItems ?? [])
+        if (order) filtered = this._sortItems(filtered, order)
+        data[schema] = limit && Array.isArray(filtered) ? filtered.slice(0, limit) : filtered
+      } else if (dynamicContext && cfg.detail) {
+        // Collection-first detail resolution:
+        // 1. Ensure the collection is in DataStore (fetching if needed).
+        // 2. Validate that paramValue exists in the collection (content gate).
+        // 3. Only then fetch the detail URL for richer item data.
+        const { paramName, paramValue } = dynamicContext
+        const singularKey = singularize(schema) || schema
+
+        // Step 1: ensure collection is cached (sequential — needed for validation)
+        let collectionItems = this.dataStore.has(cfg) ? this.dataStore.get(cfg) : null
+        if (collectionItems === null) {
+          const result = await this.dataStore.fetch(cfg)
+          collectionItems = Array.isArray(result.data) ? result.data : null
+        }
+
+        // Step 2: validate paramValue is in the collection (content gate)
+        const match = collectionItems?.find(
+          (item) => String(item[paramName]) === String(paramValue)
+        ) ?? null
+
+        if (!match) {
+          data[singularKey] = null // Not in collection — content gate
+          continue
+        }
+
+        // Step 3: fetch detail URL for richer data; fall back to collection item
         const detailCfg = this._buildDetailConfig(cfg, dynamicContext)
         if (detailCfg) {
-          fetchPromises.push(
+          parallelFetches.push(
             this.dataStore.fetch(detailCfg).then((result) => {
-              if (result.data !== undefined && result.data !== null) {
-                const singularKey = singularize(schema) || schema
-                data[singularKey] = result.data
-              }
+              data[singularKey] = (result.data !== undefined && result.data !== null)
+                ? result.data
+                : match // fallback: collection item is still valid
             })
           )
-          continue // skip collection fetch for this schema
+        } else {
+          data[singularKey] = match // No detail URL — collection item is enough
         }
+      } else {
+        // Default: fetch the full collection
+        parallelFetches.push(
+          this.dataStore.fetch(cfg).then((result) => {
+            if (result.data !== undefined && result.data !== null) {
+              data[schema] = result.data
+            }
+          })
+        )
       }
-
-      // Default: fetch the full collection
-      fetchPromises.push(
-        this.dataStore.fetch(cfg).then((result) => {
-          if (result.data !== undefined && result.data !== null) {
-            data[schema] = result.data
-          }
-        })
-      )
     }
 
-    if (fetchPromises.length > 0) {
-      await Promise.all(fetchPromises)
+    if (parallelFetches.length > 0) {
+      await Promise.all(parallelFetches)
     }
     const resolved = this._resolveSingularItem(data, dynamicContext)
     return { data: resolved }

package/src/website.js

@@ -33,7 +33,8 @@ export default class Website {
 
     // Store 404 page (for SPA routing)
     // Convention: pages/404/ directory
-    this.notFoundPage = notFound || pages.find((p) => p.route === '/404') || null
+    const notFoundData = notFound || pages.find((p) => p.route === '/404') || null
+    this.notFoundPage = notFoundData ? new Page(notFoundData, 'notFound', this) : null
 
     // Filter out 404 from regular pages array
     const regularPages = pages.filter((page) => page.route !== '/404')
@@ -49,6 +50,7 @@ export default class Website {
     // Cache for dynamically created page instances
     this._dynamicPageCache = new Map()
 
+
     this.pages = regularPages.map(
       (page, index) => new Page(page, index, this)
     )
@@ -66,7 +68,11 @@ export default class Website {
     this.config = config
 
     // Locale configuration
-    this.defaultLocale = config.defaultLanguage || 'en'
+    // siteDefaultLocale: the site's true default language (for route translations)
+    // defaultLocale: effective default for URL prefix logic — domainLocale overrides
+    //   to prevent unnecessary /{locale}/ prefixes on domain-locale pages
+    this.siteDefaultLocale = config.defaultLanguage || 'en'
+    this.defaultLocale = config.domainLocale || this.siteDefaultLocale
     this.activeLocale = config.activeLocale || this.defaultLocale
 
     // Build locales list from i18n config
@@ -169,7 +175,7 @@ export default class Website {
    * @returns {string} Translated route or original if no translation exists
    */
   translateRoute(canonicalRoute, locale = this.activeLocale) {
-    if (!locale || locale === this.defaultLocale) return canonicalRoute
+    if (!locale || locale === this.siteDefaultLocale) return canonicalRoute
     const entry = this._routeTranslations[locale]
     if (!entry) return canonicalRoute
     // Exact match
@@ -193,7 +199,7 @@ export default class Website {
    * @returns {string} Canonical route or original if no translation exists
    */
   reverseTranslateRoute(displayRoute, locale = this.activeLocale) {
-    if (!locale || locale === this.defaultLocale) return displayRoute
+    if (!locale || locale === this.siteDefaultLocale) return displayRoute
     const entry = this._routeTranslations[locale]
     if (!entry) return displayRoute
     // Exact match
@@ -280,6 +286,23 @@ export default class Website {
       }
     }
 
+    // Normalize trailing slashes for consistent matching
+    const normalizedStripped = stripped === '/' ? '/' : stripped.replace(/\/$/, '')
+
+    // Priority 1: Direct match on the (possibly display) route.
+    // Handles published-payload sites where the page map may already contain
+    // locale-translated display routes (e.g. fr pages have fr routes).
+    // For file-system sites whose page map uses canonical routes this will
+    // simply fall through to the reverse-translate path below.
+    const directMatch = this.pages.find((page) => page.route === normalizedStripped)
+    if (directMatch) {
+      if (!directMatch.hasContent()) {
+        const indexChild = directMatch.children.find((c) => c.isIndex)
+        if (indexChild) return indexChild
+      }
+      return directMatch
+    }
+
     // Reverse-translate display route to canonical (e.g., '/acerca-de' → '/about')
     stripped = this.reverseTranslateRoute(stripped)
 
@@ -287,7 +310,7 @@ export default class Website {
     // '/about/' and '/about' should match the same page
     const normalizedRoute = stripped === '/' ? '/' : stripped.replace(/\/$/, '')
 
-    // Priority 1: Exact match on actual route
+    // Priority 1b: Exact match on canonical route
     const exactMatch = this.pages.find((page) => page.route === normalizedRoute)
     if (exactMatch) {
       // Priority 1.5: folder page with an isIndex child — resolve to the index child.
@@ -318,10 +341,15 @@ export default class Website {
       const match = this._matchDynamicRoute(page.route, normalizedRoute)
       if (match) {
         // Create a dynamic page instance with the concrete route and params
-        const dynamicPage = this._createDynamicPage(page, normalizedRoute, match.params)
-        if (dynamicPage) {
-          // Cache for future requests
-          this._dynamicPageCache.set(normalizedRoute, dynamicPage)
+        const result = this._createDynamicPage(page, normalizedRoute, match.params)
+        if (result) {
+          const { page: dynamicPage, collectionLoaded } = result
+          // Only cache when collection data was available at creation time.
+          // If DataStore was empty, skip caching so the next render recreates
+          // the page with fresh data (correct title, not-found state, etc.).
+          if (collectionLoaded) {
+            this._dynamicPageCache.set(normalizedRoute, dynamicPage)
+          }
           return dynamicPage
         }
       }
@@ -432,11 +460,18 @@ export default class Website {
         if (currentItem.description || currentItem.excerpt) {
           pageData.description = currentItem.description || currentItem.excerpt
         }
+      } else if (items.length > 0) {
+        // Collection is loaded but this ID isn't in it — definitive not found
+        pageData.title = 'Not found'
+        pageData.notFound = true
       }
 
       // Store in dynamic context for entity resolution
       pageData.dynamicContext.currentItem = currentItem || null
       pageData.dynamicContext.allItems = items
+
+      // Track whether collection data was available at creation time
+      pageData._collectionLoaded = items.length > 0
     }
 
     // Create the page instance
@@ -445,7 +480,7 @@ export default class Website {
     // Copy parent reference from template
     dynamicPage.parent = templatePage.parent
 
-    return dynamicPage
+    return { page: dynamicPage, collectionLoaded: pageData._collectionLoaded ?? true }
   }
 
   /**
@@ -710,6 +745,18 @@ export default class Website {
     // Reverse-translate from current locale to canonical route
     targetRoute = this.reverseTranslateRoute(targetRoute)
 
+    // Per-domain locale: if a domain is designated for this locale,
+    // return a full cross-domain URL instead of a path-based prefix.
+    const domainLocales = this.config?.domainLocales
+    if (domainLocales) {
+      const designated = Object.entries(domainLocales).find(([, lang]) => lang === localeCode)
+      if (designated) {
+        const domain = designated[0]
+        const translatedRoute = this.translateRoute(targetRoute, localeCode)
+        return `https://${domain}${translatedRoute === '/' ? '/' : translatedRoute}`
+      }
+    }
+
     // Default locale uses root path (no prefix), no translation needed
     if (localeCode === this.defaultLocale) {
       return targetRoute