@uniweb/core 0.1.13 → 0.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/core",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {

package/src/block.js

@@ -62,6 +62,10 @@ export default class Block {
     // Populated during render for components with inheritData
     this.cascadedData = blockData.cascadedData || {}
 
+    // Dynamic route context (params from URL matching)
+    // Set when accessing a dynamic page like /blog/:slug -> /blog/my-post
+    this.dynamicContext = blockData.dynamicContext || null
+
     // State management (dynamic, can change at runtime)
     this.startState = null
     this.state = null
@@ -350,6 +354,80 @@ export default class Block {
     return [state, (newState) => setState((this.state = newState))]
   }
 
+  // ─────────────────────────────────────────────────────────────────
+  // Dynamic Route Data Resolution
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Get dynamic route context (params from URL matching)
+   * @returns {Object|null} Dynamic context with params, or null if not a dynamic page
+   *
+   * @example
+   * // For route /blog/:slug matched against /blog/my-post
+   * block.getDynamicContext()
+   * // { templateRoute: '/blog/:slug', params: { slug: 'my-post' }, paramName: 'slug', paramValue: 'my-post' }
+   */
+  getDynamicContext() {
+    return this.dynamicContext
+  }
+
+  /**
+   * Get the current item from cascaded data using dynamic route params
+   * Looks up the item in cascadedData that matches the URL param value
+   *
+   * @param {string} [schema] - Schema name to look up (e.g., 'articles'). If omitted, uses parentSchema from dynamicContext.
+   * @returns {Object|null} The matched item, or null if not found
+   *
+   * @example
+   * // URL: /blog/my-post, cascadedData: { articles: [{slug: 'my-post', title: 'My Post'}, ...] }
+   * block.getCurrentItem('articles')
+   * // { slug: 'my-post', title: 'My Post', ... }
+   */
+  getCurrentItem(schema) {
+    const ctx = this.dynamicContext
+    if (!ctx) return null
+
+    const { paramName, paramValue } = ctx
+
+    // If schema not provided, try to infer from cascadedData keys
+    const lookupSchema = schema || this._inferSchema()
+    if (!lookupSchema) return null
+
+    const items = this.cascadedData[lookupSchema]
+    if (!Array.isArray(items)) return null
+
+    // Find item where the param field matches the URL value
+    return items.find(item => String(item[paramName]) === String(paramValue)) || null
+  }
+
+  /**
+   * Get all items from cascaded data for the dynamic route's schema
+   *
+   * @param {string} [schema] - Schema name to look up. If omitted, uses parentSchema from dynamicContext.
+   * @returns {Array} Array of items, or empty array if not found
+   */
+  getAllItems(schema) {
+    const lookupSchema = schema || this._inferSchema()
+    if (!lookupSchema) return []
+
+    const items = this.cascadedData[lookupSchema]
+    return Array.isArray(items) ? items : []
+  }
+
+  /**
+   * Infer the schema name from cascaded data keys
+   * Looks for the first array in cascadedData
+   * @private
+   */
+  _inferSchema() {
+    for (const key of Object.keys(this.cascadedData)) {
+      if (Array.isArray(this.cascadedData[key])) {
+        return key
+      }
+    }
+    return null
+  }
+
   /**
    * Parse nested links structure
    */

package/src/page.js

@@ -8,7 +8,15 @@
 import Block from './block.js'
 
 export default class Page {
-  constructor(pageData, id, website, pageHeader, pageFooter, pageLeft, pageRight) {
+  constructor(
+    pageData,
+    id,
+    website,
+    pageHeader,
+    pageFooter,
+    pageLeft,
+    pageRight,
+  ) {
     this.id = id
     this.route = pageData.route
     this.isIndex = pageData.isIndex || false // True if this page is the index for its parent route
@@ -32,7 +40,7 @@ export default class Page {
       right: pageData.layout?.right !== false,
       // Aliases for backwards compatibility
       leftPanel: pageData.layout?.left !== false,
-      rightPanel: pageData.layout?.right !== false
+      rightPanel: pageData.layout?.right !== false,
     }
 
     // SEO configuration
@@ -43,7 +51,7 @@ export default class Page {
       ogDescription: pageData.seo?.ogDescription || null,
       canonical: pageData.seo?.canonical || null,
       changefreq: pageData.seo?.changefreq || null,
-      priority: pageData.seo?.priority || null
+      priority: pageData.seo?.priority || null,
     }
 
     // Child pages (for nested hierarchy) - populated by Website
@@ -55,13 +63,16 @@ export default class Page {
     // Scroll position memory (for navigation restoration)
     this.scrollY = 0
 
+    // Dynamic route context (for pages created from dynamic routes like /blog/:slug)
+    this.dynamicContext = pageData.dynamicContext || null
+
     // Build block groups for all layout areas
     this.pageBlocks = this.buildPageBlocks(
       pageData.sections,
       pageHeader?.sections,
       pageFooter?.sections,
       pageLeft?.sections,
-      pageRight?.sections
+      pageRight?.sections,
     )
   }
 
@@ -80,11 +91,44 @@ export default class Page {
         title: this.seo.ogTitle || this.title,
         description: this.seo.ogDescription || this.description,
         image: this.seo.image,
-        url: this.route
-      }
+        url: this.route,
+      },
     }
   }
 
+  // ─────────────────────────────────────────────────────────────────
+  // Dynamic Route Support
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Check if this is a dynamic page (created from a route pattern like /blog/:slug)
+   * @returns {boolean}
+   */
+  isDynamicPage() {
+    return this.dynamicContext !== null
+  }
+
+  /**
+   * Get dynamic route context
+   * @returns {Object|null} Dynamic context with params, or null if not a dynamic page
+   *
+   * @example
+   * // For route /blog/:slug matched against /blog/my-post
+   * page.getDynamicContext()
+   * // { templateRoute: '/blog/:slug', params: { slug: 'my-post' }, paramName: 'slug', paramValue: 'my-post' }
+   */
+  getDynamicContext() {
+    return this.dynamicContext
+  }
+
+  /**
+   * Get the URL param value for dynamic routes
+   * @returns {string|null} The param value (e.g., 'my-post' for /blog/my-post), or null
+   */
+  getDynamicParam() {
+    return this.dynamicContext?.paramValue || null
+  }
+
   /**
    * Build the page block structure for all layout areas.
    * Each area can have multiple sections/blocks.
@@ -117,7 +161,7 @@ export default class Page {
       body: bodyBlocks,
       footer: buildBlocks(footer, 'footer'),
       left: buildBlocks(left, 'left'),
-      right: buildBlocks(right, 'right')
+      right: buildBlocks(right, 'right'),
     }
   }
 
@@ -279,7 +323,7 @@ export default class Page {
       ...this.pageBlocks.body,
       ...(this.pageBlocks.footer || []),
       ...(this.pageBlocks.left || []),
-      ...(this.pageBlocks.right || [])
+      ...(this.pageBlocks.right || []),
     ]
 
     for (const block of allBlocks) {
@@ -422,29 +466,31 @@ export default class Page {
 
   /**
    * Get route without leading/trailing slashes.
-   * Useful for route comparisons.
+   * Delegates to Website.normalizeRoute() for consistent normalization.
    *
    * @returns {string} Normalized route (e.g., 'docs/getting-started')
    */
   getNormalizedRoute() {
-    return (this.route || '').replace(/^\//, '').replace(/\/$/, '')
+    return this.website.normalizeRoute(this.route)
   }
 
   /**
    * Check if this page matches the given route exactly.
+   * Delegates to Website.isRouteActive() for consistent comparison.
    *
-   * @param {string} route - Normalized route (no leading/trailing slashes)
+   * @param {string} currentRoute - Current route to compare against
    * @returns {boolean} True if this page's route matches
    */
-  isActiveFor(route) {
-    return this.getNormalizedRoute() === route
+  isActiveFor(currentRoute) {
+    return this.website.isRouteActive(this.route, currentRoute)
   }
 
   /**
    * Check if this page or any descendant matches the given route.
    * Useful for highlighting parent nav items when a child page is active.
+   * Delegates to Website.isRouteActiveOrAncestor() for consistent logic.
    *
-   * @param {string} route - Normalized route (no leading/trailing slashes)
+   * @param {string} currentRoute - Current route to compare against
    * @returns {boolean} True if this page or a descendant is active
    *
    * @example
@@ -452,12 +498,7 @@ export default class Page {
    * // Current route: 'docs/getting-started/installation'
    * page.isActiveOrAncestor('docs/getting-started/installation') // true
    */
-  isActiveOrAncestor(route) {
-    const pageRoute = this.getNormalizedRoute()
-    if (pageRoute === route) return true
-    // Check if route starts with this page's route followed by /
-    // Handle empty pageRoute (root) specially
-    if (pageRoute === '') return true // Root is ancestor of all
-    return route.startsWith(pageRoute + '/')
+  isActiveOrAncestor(currentRoute) {
+    return this.website.isRouteActiveOrAncestor(this.route, currentRoute)
   }
 }

package/src/website.js

@@ -25,7 +25,7 @@ const LOCALE_NAMES = {
 
 export default class Website {
   constructor(websiteData) {
-    const { pages = [], theme = {}, config = {}, header, footer, left, right } = websiteData
+    const { pages = [], theme = {}, config = {}, header, footer, left, right, notFound } = websiteData
 
     // Site metadata
     this.name = config.name || ''
@@ -40,14 +40,29 @@ export default class Website {
     this.leftPage = left || pages.find((p) => p.route === '/@left') || null
     this.rightPage = right || pages.find((p) => p.route === '/@right') || null
 
+    // Store 404 page (for SPA routing)
+    // Convention: pages/404/ directory
+    this.notFoundPage = notFound || pages.find((p) => p.route === '/404') || null
+
     // Filter out special pages from regular pages array
-    const specialRoutes = ['/@header', '/@footer', '/@left', '/@right']
-    this.pages = pages
-      .filter((page) => !specialRoutes.includes(page.route))
-      .map(
-        (page, index) =>
-          new Page(page, index, this, this.headerPage, this.footerPage, this.leftPage, this.rightPage)
-      )
+    const specialRoutes = ['/@header', '/@footer', '/@left', '/@right', '/404']
+    const regularPages = pages.filter((page) => !specialRoutes.includes(page.route))
+
+    // Store original page data for dynamic pages (needed to create instances on-demand)
+    this._dynamicPageData = new Map()
+    for (const pageData of regularPages) {
+      if (pageData.isDynamic || pageData.route?.includes(':')) {
+        this._dynamicPageData.set(pageData.route, pageData)
+      }
+    }
+
+    // Cache for dynamically created page instances
+    this._dynamicPageCache = new Map()
+
+    this.pages = regularPages.map(
+      (page, index) =>
+        new Page(page, index, this, this.headerPage, this.footerPage, this.leftPage, this.rightPage)
+    )
 
     // Build parent-child relationships based on route structure
     this.buildPageHierarchy()
@@ -157,17 +172,245 @@ export default class Website {
 
   /**
    * Get page by route
-   * Matches both actual routes and nav routes (for index pages)
-   * @param {string} route
+   * Matches in priority order:
+   * 1. Exact match on actual route
+   * 2. Index page nav route match
+   * 3. Dynamic route pattern match (e.g., /blog/:slug matches /blog/my-post)
+   *
+   * @param {string} route - The route to find
    * @returns {Page|undefined}
    */
   getPage(route) {
-    // First try exact match on actual route
+    // Priority 1: Exact match on actual route
     const exactMatch = this.pages.find((page) => page.route === route)
     if (exactMatch) return exactMatch
 
-    // Then try matching nav route (for index pages accessible at parent route)
-    return this.pages.find((page) => page.isIndex && page.getNavRoute() === route)
+    // Priority 2: Index page nav route match
+    const indexMatch = this.pages.find((page) => page.isIndex && page.getNavRoute() === route)
+    if (indexMatch) return indexMatch
+
+    // Priority 3: Dynamic route pattern matching
+    // Check cache first
+    if (this._dynamicPageCache.has(route)) {
+      return this._dynamicPageCache.get(route)
+    }
+
+    // Try to match against dynamic route patterns
+    for (const page of this.pages) {
+      // Check if this is a dynamic page (has :param in route)
+      if (!page.route.includes(':')) continue
+
+      const match = this._matchDynamicRoute(page.route, route)
+      if (match) {
+        // Create a dynamic page instance with the concrete route and params
+        const dynamicPage = this._createDynamicPage(page, route, match.params)
+        if (dynamicPage) {
+          // Cache for future requests
+          this._dynamicPageCache.set(route, dynamicPage)
+          return dynamicPage
+        }
+      }
+    }
+
+    return undefined
+  }
+
+  /**
+   * Match a dynamic route pattern against a concrete path
+   * E.g., /blog/:slug matches /blog/my-post => { params: { slug: 'my-post' } }
+   *
+   * @private
+   * @param {string} pattern - Route pattern with :param placeholders
+   * @param {string} path - Actual path to match
+   * @returns {Object|null} Match result with params, or null if no match
+   */
+  _matchDynamicRoute(pattern, path) {
+    // Extract param names and build regex
+    const paramNames = []
+    const regexStr = pattern
+      .replace(/[.*+?^${}()|[\]\\]/g, '\\$&') // Escape special chars except :
+      .replace(/:(\w+)/g, (_, paramName) => {
+        paramNames.push(paramName)
+        return '([^/]+)' // Capture anything except /
+      })
+
+    const regex = new RegExp(`^${regexStr}$`)
+    const match = path.match(regex)
+
+    if (!match) return null
+
+    // Build params object
+    const params = {}
+    paramNames.forEach((name, i) => {
+      params[name] = decodeURIComponent(match[i + 1])
+    })
+
+    return { params }
+  }
+
+  /**
+   * Create a dynamic page instance with concrete route and params
+   *
+   * @private
+   * @param {Page} templatePage - The template page with :param route
+   * @param {string} concreteRoute - The actual route (e.g., /blog/my-post)
+   * @param {Object} params - Matched params (e.g., { slug: 'my-post' })
+   * @returns {Page|null} New page instance or null
+   */
+  _createDynamicPage(templatePage, concreteRoute, params) {
+    // Get the original page data
+    const originalData = this._dynamicPageData.get(templatePage.route)
+    if (!originalData) return null
+
+    // Deep clone the page data
+    const pageData = JSON.parse(JSON.stringify(originalData))
+
+    // Update with concrete route and dynamic context
+    pageData.route = concreteRoute
+    pageData.isDynamic = false // No longer a template
+
+    const paramName = Object.keys(params)[0]
+    const paramValue = Object.values(params)[0]
+    const pluralSchema = originalData.parentSchema // e.g., 'articles'
+    const singularSchema = this._singularize(pluralSchema) // e.g., 'article'
+
+    // Store dynamic context for components to access
+    pageData.dynamicContext = {
+      templateRoute: templatePage.route,
+      params,
+      paramName,
+      paramValue,
+      schema: pluralSchema,
+      singularSchema,
+    }
+
+    // Get the parent page's data to find the items array
+    // Parent route is the template route without the :param suffix
+    const parentRoute = templatePage.route.replace(/\/:[\w]+$/, '') || '/'
+    const parentPage = this.pages.find(p => p.route === parentRoute || p.getNavRoute() === parentRoute)
+
+    // Get items from parent's cascaded data
+    let items = []
+    let currentItem = null
+
+    if (parentPage && pluralSchema) {
+      // Get items from parent page's first section's cascadedData
+      // This is where the page-level fetch stores its data
+      const firstSection = parentPage.pageBlocks?.body?.[0]
+      if (firstSection) {
+        items = firstSection.cascadedData?.[pluralSchema] || []
+      }
+
+      // Find the current item using the param
+      if (items.length > 0) {
+        currentItem = items.find(item => String(item[paramName]) === String(paramValue))
+      }
+    }
+
+    // Store items in dynamic context for Block.getCurrentItem() / getAllItems()
+    pageData.dynamicContext.currentItem = currentItem
+    pageData.dynamicContext.allItems = items
+
+    // Inject cascaded data into sections for components with inheritData
+    // This provides both singular (article) and plural (articles) data
+    const cascadedData = {}
+    if (currentItem && singularSchema) {
+      cascadedData[singularSchema] = currentItem
+    }
+    if (items.length > 0 && pluralSchema) {
+      cascadedData[pluralSchema] = items
+    }
+
+    this._injectDynamicData(pageData.sections, cascadedData, pageData.dynamicContext)
+
+    // Update page metadata from current item if available
+    if (currentItem) {
+      if (currentItem.title) pageData.title = currentItem.title
+      if (currentItem.description || currentItem.excerpt) {
+        pageData.description = currentItem.description || currentItem.excerpt
+      }
+    }
+
+    // Create the page instance
+    const dynamicPage = new Page(
+      pageData,
+      `dynamic-${concreteRoute}`,
+      this,
+      this.headerPage,
+      this.footerPage,
+      this.leftPage,
+      this.rightPage
+    )
+
+    // Copy parent reference from template
+    dynamicPage.parent = templatePage.parent
+
+    return dynamicPage
+  }
+
+  /**
+   * Singularize a plural schema name
+   * @private
+   */
+  _singularize(name) {
+    if (!name) return name
+    // Common irregular plurals
+    const irregulars = {
+      people: 'person',
+      children: 'child',
+      men: 'men',
+      women: 'woman',
+      series: 'series',
+    }
+    if (irregulars[name]) return irregulars[name]
+    // -ies → -y (categories → category)
+    if (name.endsWith('ies')) return name.slice(0, -3) + 'y'
+    // -es endings that should only remove 's' (not 'es')
+    // e.g., articles → article, courses → course
+    if (name.endsWith('es')) {
+      // Check if the base word ends in a consonant that requires 'es' plural
+      // (boxes, dishes, classes, heroes) vs just 's' plural (articles, courses)
+      const base = name.slice(0, -2)
+      const lastChar = base.slice(-1)
+      // If base ends in s, x, z, ch, sh - these need 'es' for plural, so remove 'es'
+      if (['s', 'x', 'z'].includes(lastChar) || base.endsWith('ch') || base.endsWith('sh')) {
+        return base
+      }
+      // Otherwise just remove 's' (articles → article)
+      return name.slice(0, -1)
+    }
+    // Regular -s plurals
+    if (name.endsWith('s')) return name.slice(0, -1)
+    return name
+  }
+
+  /**
+   * Inject dynamic route data into sections for components with inheritData
+   * This provides both the current item (singular) and all items (plural)
+   *
+   * @private
+   * @param {Array} sections - Sections to update
+   * @param {Object} cascadedData - Data to inject { article: {...}, articles: [...] }
+   * @param {Object} dynamicContext - Dynamic route context
+   */
+  _injectDynamicData(sections, cascadedData, dynamicContext) {
+    if (!sections || !Array.isArray(sections)) return
+
+    for (const section of sections) {
+      // Merge cascaded data into section's existing cascadedData
+      section.cascadedData = {
+        ...(section.cascadedData || {}),
+        ...cascadedData,
+      }
+
+      // Also set dynamic context for Block.getDynamicContext()
+      section.dynamicContext = dynamicContext
+
+      // Recurse into subsections
+      if (section.subsections && section.subsections.length > 0) {
+        this._injectDynamicData(section.subsections, cascadedData, dynamicContext)
+      }
+    }
   }
 
   /**
@@ -530,6 +773,14 @@ export default class Website {
     return this.getPageHierarchy({ nested: false, includeHidden })
   }
 
+  /**
+   * Get the 404 (not found) page if defined
+   * @returns {Page|null} The 404 page or null
+   */
+  getNotFoundPage() {
+    return this.notFoundPage
+  }
+
   // ─────────────────────────────────────────────────────────────────
   // Active Route API (for navigation components)
   // ─────────────────────────────────────────────────────────────────
@@ -560,4 +811,64 @@ export default class Website {
   getActiveRootSegment() {
     return this.getActiveRoute().split('/')[0]
   }
+
+  /**
+   * Normalize a route by removing leading/trailing slashes.
+   * This is the single source of truth for route normalization.
+   *
+   * @param {string} route - Route to normalize
+   * @returns {string} Normalized route (e.g., 'docs/getting-started')
+   *
+   * @example
+   * website.normalizeRoute('/docs/guide/') // 'docs/guide'
+   * website.normalizeRoute('about')        // 'about'
+   * website.normalizeRoute('/')            // ''
+   */
+  normalizeRoute(route) {
+    return (route || '').replace(/^\/+/, '').replace(/\/+$/, '')
+  }
+
+  /**
+   * Check if a target route matches the current route exactly.
+   *
+   * @param {string} targetRoute - Route to check (will be normalized)
+   * @param {string} currentRoute - Current route (will be normalized)
+   * @returns {boolean} True if routes match exactly
+   *
+   * @example
+   * website.isRouteActive('/about', '/about') // true
+   * website.isRouteActive('/about', '/about/team') // false
+   */
+  isRouteActive(targetRoute, currentRoute) {
+    return this.normalizeRoute(targetRoute) === this.normalizeRoute(currentRoute)
+  }
+
+  /**
+   * Check if a target route matches the current route or is an ancestor of it.
+   * Used for navigation highlighting where parent items should be highlighted
+   * when a child page is active.
+   *
+   * @param {string} targetRoute - Route to check (will be normalized)
+   * @param {string} currentRoute - Current route (will be normalized)
+   * @returns {boolean} True if target matches current or is an ancestor
+   *
+   * @example
+   * website.isRouteActiveOrAncestor('/docs', '/docs')           // true (exact)
+   * website.isRouteActiveOrAncestor('/docs', '/docs/guide')     // true (ancestor)
+   * website.isRouteActiveOrAncestor('/about', '/docs/guide')    // false
+   * website.isRouteActiveOrAncestor('/', '/docs')               // false (root is not ancestor of all)
+   */
+  isRouteActiveOrAncestor(targetRoute, currentRoute) {
+    const target = this.normalizeRoute(targetRoute)
+    const current = this.normalizeRoute(currentRoute)
+
+    // Exact match
+    if (target === current) return true
+
+    // Empty target (root) is not considered ancestor of everything
+    if (target === '') return false
+
+    // Check if current starts with target followed by /
+    return current.startsWith(target + '/')
+  }
 }