@uniweb/core 0.1.9 → 0.1.11

package/README.md

@@ -126,7 +126,6 @@ page.label                    // Short navigation label (or null)
 page.order                    // Sort order
 page.children                 // Child pages (for nested hierarchy)
 page.website                  // Back-reference to parent Website
-page.site                     // Alias for page.website
 
 // Navigation visibility
 page.hidden                   // Hidden from all navigation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/core",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {
@@ -27,6 +27,6 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "@uniweb/semantic-parser": "1.0.7"
+    "@uniweb/semantic-parser": "1.0.8"
   }
 }

package/src/block.js

@@ -175,17 +175,18 @@ export default class Block {
       return null
     }
 
-    // Get component-level block configuration
-    // Supports: Component.block (preferred), Component.blockDefaults (legacy)
-    const blockConfig = this.Component.block || this.Component.blockDefaults || {}
+    // Get runtime metadata for this component (from meta.js, extracted at build time)
+    const meta = globalThis.uniweb?.getComponentMeta(this.type) || {}
 
     // Initialize state (dynamic, can change at runtime)
-    const stateDefaults = blockConfig.state || this.Component.blockState
+    // Source: meta.js initialState field
+    const stateDefaults = meta.initialState
     this.startState = stateDefaults ? { ...stateDefaults } : null
     this.initState()
 
     // Initialize context (static, per component type)
-    this.context = blockConfig.context ? { ...blockConfig.context } : null
+    // Source: meta.js context field
+    this.context = meta.context ? { ...meta.context } : null
 
     return this.Component
   }

package/src/page.js

@@ -11,6 +11,7 @@ export default class Page {
   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
     this.title = pageData.title || ''
     this.description = pageData.description || ''
     this.label = pageData.label || null // Short label for navigation (null = use title)
@@ -50,7 +51,6 @@ export default class Page {
 
     // Back-reference to website
     this.website = website
-    this.site = website // Alias
 
     // Scroll position memory (for navigation restoration)
     this.scrollY = 0
@@ -293,6 +293,26 @@ export default class Page {
   // Navigation and Layout Helpers
   // ─────────────────────────────────────────────────────────────────
 
+  /**
+   * Get the navigation route (canonical route for links)
+   * For index pages, returns the parent route (e.g., '/' for homepage)
+   * For regular pages, returns the actual route
+   * @returns {string}
+   */
+  getNavRoute() {
+    if (!this.isIndex) {
+      return this.route
+    }
+    // Index page - compute parent route
+    // /home -> /
+    // /docs/getting-started -> /docs
+    const segments = this.route.split('/').filter(Boolean)
+    if (segments.length <= 1) {
+      return '/'
+    }
+    return '/' + segments.slice(0, -1).join('/')
+  }
+
   /**
    * Get display label for navigation (short form of title)
    * @returns {string}
@@ -364,4 +384,80 @@ export default class Page {
   hasChildren() {
     return this.children.length > 0
   }
+
+  /**
+   * Check if page has body content (sections)
+   * @returns {boolean}
+   */
+  hasContent() {
+    return this.pageBlocks.body.length > 0
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Active Route Detection
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Get the first navigable route for this page.
+   * If page has no content, recursively finds first child with content.
+   * Useful for category pages that are just navigation containers.
+   *
+   * @returns {string} The route to navigate to
+   *
+   * @example
+   * // For a "Docs" category page with no content but children:
+   * // page.route = '/docs'
+   * // page.hasContent() = false
+   * // First child with content: '/docs/getting-started'
+   * page.getNavigableRoute() // Returns '/docs/getting-started'
+   */
+  getNavigableRoute() {
+    if (this.hasContent()) return this.route
+    for (const child of this.children || []) {
+      const route = child.getNavigableRoute()
+      if (route) return route
+    }
+    return this.route // Fallback to own route
+  }
+
+  /**
+   * Get route without leading/trailing slashes.
+   * Useful for route comparisons.
+   *
+   * @returns {string} Normalized route (e.g., 'docs/getting-started')
+   */
+  getNormalizedRoute() {
+    return (this.route || '').replace(/^\//, '').replace(/\/$/, '')
+  }
+
+  /**
+   * Check if this page matches the given route exactly.
+   *
+   * @param {string} route - Normalized route (no leading/trailing slashes)
+   * @returns {boolean} True if this page's route matches
+   */
+  isActiveFor(route) {
+    return this.getNormalizedRoute() === route
+  }
+
+  /**
+   * Check if this page or any descendant matches the given route.
+   * Useful for highlighting parent nav items when a child page is active.
+   *
+   * @param {string} route - Normalized route (no leading/trailing slashes)
+   * @returns {boolean} True if this page or a descendant is active
+   *
+   * @example
+   * // Page route: '/docs'
+   * // 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 + '/')
+  }
 }

package/src/uniweb.js

@@ -14,7 +14,8 @@ export default class Uniweb {
     this.childBlockRenderer = null // Function to render child blocks
     this.routingComponents = {} // Link, SafeHtml, useNavigate, etc.
     this.foundation = null // The loaded foundation module
-    this.foundationConfig = {} // Configuration from foundation
+    this.foundationConfig = {} // Configuration from foundation (capabilities)
+    this.meta = {} // Per-component runtime metadata (from meta.js)
     this.language = 'en'
 
     // Initialize analytics (disabled by default, configure via site config)
@@ -27,6 +28,29 @@ export default class Uniweb {
    */
   setFoundation(foundation) {
     this.foundation = foundation
+
+    // Store per-component metadata if present
+    if (foundation.meta) {
+      this.meta = foundation.meta
+    }
+  }
+
+  /**
+   * Get runtime metadata for a component
+   * @param {string} componentName
+   * @returns {Object|null} Meta with defaults, context, initialState, background, data
+   */
+  getComponentMeta(componentName) {
+    return this.meta[componentName] || null
+  }
+
+  /**
+   * Get default param values for a component
+   * @param {string} componentName
+   * @returns {Object} Default values (empty object if none)
+   */
+  getComponentDefaults(componentName) {
+    return this.meta[componentName]?.defaults || {}
   }
 
   /**

package/src/website.js

@@ -52,8 +52,9 @@ export default class Website {
     // Build parent-child relationships based on route structure
     this.buildPageHierarchy()
 
+    // Find the homepage (root-level index page)
     this.activePage =
-      this.pages.find((page) => page.route === '/' || page.route === '/index') ||
+      this.pages.find((page) => page.isIndex && page.getNavRoute() === '/') ||
       this.pages[0]
 
     this.pageRoutes = this.pages.map((page) => page.route)
@@ -115,22 +116,28 @@ export default class Website {
     })
 
     // Build a map of route to page for quick lookup
+    // Include both actual routes and nav routes (for index pages)
     const pageMap = new Map()
     for (const page of sortedPages) {
       pageMap.set(page.route, page)
+      // Also map the nav route for index pages so parent lookup works
+      if (page.isIndex) {
+        const navRoute = page.getNavRoute()
+        if (navRoute !== page.route) {
+          pageMap.set(navRoute, page)
+        }
+      }
     }
 
     // For each page, find its parent and add it as a child
     for (const page of sortedPages) {
       const route = page.route
-      if (route === '/' || route === '') continue
-
-      // Find parent route by removing the last segment
-      // /getting-started/installation -> /getting-started
+      // Skip root-level pages (single segment like /home, /about)
       const segments = route.split('/').filter(Boolean)
-      if (segments.length <= 1) continue // Root-level pages have no parent
+      if (segments.length <= 1) continue
 
-      // Build parent route
+      // Build parent route by removing the last segment
+      // /docs/getting-started -> /docs
       const parentRoute = '/' + segments.slice(0, -1).join('/')
       const parent = pageMap.get(parentRoute)
 
@@ -150,11 +157,17 @@ export default class Website {
 
   /**
    * Get page by route
+   * Matches both actual routes and nav routes (for index pages)
    * @param {string} route
    * @returns {Page|undefined}
    */
   getPage(route) {
-    return this.pages.find((page) => page.route === route)
+    // First try 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)
   }
 
   /**
@@ -475,12 +488,13 @@ export default class Website {
     // Build page info objects
     const buildPageInfo = (page) => ({
       id: page.id,
-      route: page.route,
+      route: page.getNavRoute(), // Use canonical nav route (e.g., '/' for index pages)
+      navigableRoute: page.getNavigableRoute(), // First route with content (for links)
       title: page.title,
       label: page.getLabel(),
       description: page.description,
       order: page.order,
-      hasContent: page.getBodyBlocks().length > 0,
+      hasContent: page.hasContent(),
       children: nested && page.hasChildren()
         ? page.children.filter(isPageVisible).map(buildPageInfo)
         : []
@@ -515,4 +529,35 @@ export default class Website {
   getAllPages(includeHidden = false) {
     return this.getPageHierarchy({ nested: false, includeHidden })
   }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Active Route API (for navigation components)
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Get the current active route, normalized (no leading/trailing slashes).
+   * Works in both SSR (from activePage) and client (from activePage).
+   *
+   * @returns {string} Normalized route (e.g., 'docs/getting-started')
+   *
+   * @example
+   * website.getActiveRoute() // 'docs/getting-started'
+   */
+  getActiveRoute() {
+    return this.activePage?.getNormalizedRoute() || ''
+  }
+
+  /**
+   * Get the first segment of the active route.
+   * Useful for root-level navigation highlighting.
+   *
+   * @returns {string} First segment (e.g., 'docs' for 'docs/getting-started')
+   *
+   * @example
+   * // Active route: 'docs/getting-started/installation'
+   * website.getActiveRootSegment() // 'docs'
+   */
+  getActiveRootSegment() {
+    return this.getActiveRoute().split('/')[0]
+  }
 }