@uniweb/core 0.1.4 → 0.1.5

package/README.md

@@ -56,22 +56,130 @@ uniweb.setFoundation(module)  // Set the foundation module
 Manages pages, theme, and localization.
 
 ```js
+// Page navigation
 website.getPage(route)        // Get page by route
 website.setActivePage(route)  // Navigate to page
-website.localize(value)       // Localize a multilingual value
-website.getLanguage()         // Get current language code
-website.getLanguages()        // Get available languages
+website.activePage            // Current active page
+website.pages                 // All pages
+website.pageRoutes            // Array of route strings
+
+// Page Hierarchy API (for navbars, footers, sitemaps)
+website.getPageHierarchy(options)  // Get pages for navigation
+website.getHeaderPages()           // Convenience: pages for header nav
+website.getFooterPages()           // Convenience: pages for footer nav
+website.getAllPages()              // Get flat list of all pages
+
+// Locale API
+website.getLocales()          // Get all locales: [{code, label, isDefault}]
+website.getActiveLocale()     // Get current locale code
+website.getDefaultLocale()    // Get default locale code
+website.hasMultipleLocales()  // Check if site has multiple locales
+website.getLocaleUrl(code, route)  // Build URL for a locale
+website.setActiveLocale(code) // Set active locale
+website.getLocale(code)       // Get locale info by code
+
+// Content localization (for multilingual values)
+website.localize(value)       // Localize {en: "Hello", es: "Hola"} to active lang
 website.makeHref(href)        // Transform href for routing
+
+// Deprecated (use Locale API instead)
+website.getLanguage()         // Use getActiveLocale()
+website.getLanguages()        // Use getLocales()
 ```
 
+**Page Hierarchy API**
+
+The `getPageHierarchy()` method returns pages filtered and formatted for navigation:
+
+```js
+// Get pages for header navigation
+const headerPages = website.getPageHierarchy({ for: 'header' })
+// Returns: [{ id, route, title, label, description, order, hasContent, children }]
+
+// Get flat list of all pages (for sitemaps)
+const allPages = website.getPageHierarchy({ nested: false, includeHidden: true })
+
+// Custom filtering and sorting
+const topLevel = website.getPageHierarchy({
+  filter: (page) => page.order < 10,
+  sort: (a, b) => a.title.localeCompare(b.title)
+})
+```
+
+Options:
+- `nested` (default: true) - Return with nested children or flat list
+- `for` - Filter for 'header', 'footer', or undefined (all)
+- `includeHidden` (default: false) - Include hidden pages
+- `filter` - Custom filter function: `(page) => boolean`
+- `sort` - Custom sort function: `(a, b) => number`
+
 #### Page
 
 Represents a page with its sections.
 
 ```js
+// Basic properties
 page.route                    // Page route path
 page.title                    // Page title
-page.sections                 // Array of section blocks
+page.description              // Page description
+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
+page.hideInHeader             // Hidden from header nav only
+page.hideInFooter             // Hidden from footer nav only
+page.isHidden()               // Check if hidden from navigation
+page.showInHeader()           // Should appear in header nav?
+page.showInFooter()           // Should appear in footer nav?
+page.getLabel()               // Get navigation label (falls back to title)
+
+// Layout options (per-page overrides)
+page.layout.header            // Show header on this page?
+page.layout.footer            // Show footer on this page?
+page.layout.leftPanel         // Show left panel?
+page.layout.rightPanel        // Show right panel?
+page.hasHeader()              // Convenience: page.layout.header
+page.hasFooter()              // Convenience: page.layout.footer
+page.hasLeftPanel()           // Convenience: page.layout.leftPanel
+page.hasRightPanel()          // Convenience: page.layout.rightPanel
+
+// Content
+page.getPageBlocks()          // Get header + body + footer blocks
+page.getBodyBlocks()          // Get just body blocks
+page.getHeader()              // Get header block
+page.getFooter()              // Get footer block
+page.hasChildren()            // Has child pages?
+page.getHeadMeta()            // Get SEO meta tags
+```
+
+**Page Configuration (page.yml)**
+
+```yaml
+title: About Us
+description: Learn about our company
+label: About                  # Short nav label (optional)
+order: 2
+
+# Navigation visibility
+hidden: true                  # Hide from all navigation
+hideInHeader: true            # Hide from header nav only
+hideInFooter: true            # Hide from footer nav only
+
+# Layout overrides (default: all true)
+layout:
+  header: false               # Don't show header on this page
+  footer: false               # Don't show footer on this page
+  leftPanel: false            # Don't show left panel
+  rightPanel: false           # Don't show right panel
+
+# SEO (optional)
+seo:
+  noindex: false
+  image: /about-og.png
 ```
 
 #### Block

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/core",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "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.3"
+    "@uniweb/semantic-parser": "1.0.7"
   }
 }

package/src/analytics.js

@@ -0,0 +1,232 @@
+/**
+ * Analytics
+ *
+ * Lightweight analytics class for tracking page views, events, and scroll depth.
+ * Uses batched sending with sendBeacon for reliable delivery.
+ *
+ * Features:
+ * - Batched event queue with periodic flush
+ * - Page view tracking
+ * - Custom event tracking
+ * - Scroll depth tracking (25%, 50%, 75%, 100%)
+ * - sendBeacon for reliable unload delivery
+ * - Optional - silently ignores if not configured
+ *
+ * Usage via uniweb singleton:
+ * ```js
+ * // Track events (no-op if analytics not configured)
+ * uniweb.analytics.trackPageView('/about', 'About Us')
+ * uniweb.analytics.trackEvent('button_click', { buttonId: 'cta' })
+ * uniweb.analytics.trackScrollDepth(50)
+ * ```
+ */
+
+// Check if running in browser environment
+const isBrowser = typeof window !== 'undefined' && typeof document !== 'undefined'
+
+export default class Analytics {
+  /**
+   * @param {Object} options
+   * @param {string} options.endpoint - Analytics endpoint URL (required to enable)
+   * @param {number} options.flushInterval - Interval to flush queue in ms (default: 5000)
+   * @param {number} options.maxQueueSize - Max events before auto-flush (default: 10)
+   * @param {boolean} options.debug - Enable debug logging (default: false)
+   */
+  constructor(options = {}) {
+    this.endpoint = options.endpoint || null
+    this.flushInterval = options.flushInterval || 5000
+    this.maxQueueSize = options.maxQueueSize || 10
+    this.debug = options.debug || false
+
+    // Event queue
+    this.queue = []
+
+    // Track scroll depth milestones already sent (to avoid duplicates)
+    this.scrollMilestones = new Set()
+
+    // Session info
+    this.sessionId = this.generateSessionId()
+    this.sessionStart = Date.now()
+
+    // Only set up browser handlers if in browser and configured
+    if (isBrowser && this.isEnabled()) {
+      this.setupFlushInterval()
+      this.setupUnloadHandler()
+    }
+  }
+
+  /**
+   * Check if analytics is enabled
+   * @returns {boolean}
+   */
+  isEnabled() {
+    return !!this.endpoint
+  }
+
+  /**
+   * Generate a simple session ID
+   * @returns {string}
+   */
+  generateSessionId() {
+    return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`
+  }
+
+  /**
+   * Set up periodic flush interval
+   */
+  setupFlushInterval() {
+    this.flushIntervalId = setInterval(() => {
+      this.flush()
+    }, this.flushInterval)
+  }
+
+  /**
+   * Set up unload handler for final flush
+   */
+  setupUnloadHandler() {
+    const handleUnload = () => {
+      this.flush(true) // Force beacon
+    }
+
+    window.addEventListener('visibilitychange', () => {
+      if (document.visibilityState === 'hidden') {
+        handleUnload()
+      }
+    })
+
+    window.addEventListener('pagehide', handleUnload)
+  }
+
+  /**
+   * Add event to queue
+   * @param {string} type - Event type
+   * @param {Object} data - Event data
+   */
+  addToQueue(type, data) {
+    if (!this.isEnabled() || !isBrowser) return
+
+    const event = {
+      type,
+      data,
+      timestamp: Date.now(),
+      sessionId: this.sessionId,
+      url: window.location.href,
+      referrer: document.referrer || null
+    }
+
+    this.queue.push(event)
+
+    if (this.debug) {
+      console.log('[Analytics] Event queued:', event)
+    }
+
+    // Auto-flush if queue is full
+    if (this.queue.length >= this.maxQueueSize) {
+      this.flush()
+    }
+  }
+
+  /**
+   * Track a page view
+   * @param {string} path - Page path
+   * @param {string} title - Page title
+   * @param {Object} meta - Additional metadata
+   */
+  trackPageView(path, title, meta = {}) {
+    // Reset scroll milestones for new page
+    this.scrollMilestones.clear()
+
+    this.addToQueue('pageview', {
+      path,
+      title,
+      ...meta
+    })
+  }
+
+  /**
+   * Track a custom event
+   * @param {string} name - Event name
+   * @param {Object} data - Event data
+   */
+  trackEvent(name, data = {}) {
+    this.addToQueue('event', {
+      name,
+      ...data
+    })
+  }
+
+  /**
+   * Track scroll depth milestone
+   * @param {number} percentage - Scroll depth percentage (25, 50, 75, 100)
+   */
+  trackScrollDepth(percentage) {
+    // Only track standard milestones
+    const milestones = [25, 50, 75, 100]
+    if (!milestones.includes(percentage)) return
+
+    // Don't track the same milestone twice per page
+    if (this.scrollMilestones.has(percentage)) return
+
+    this.scrollMilestones.add(percentage)
+
+    this.addToQueue('scroll_depth', {
+      depth: percentage
+    })
+  }
+
+  /**
+   * Flush the event queue
+   * @param {boolean} useBeacon - Force use of sendBeacon (for unload)
+   */
+  flush(useBeacon = false) {
+    if (!this.isEnabled() || !isBrowser || this.queue.length === 0) return
+
+    const events = [...this.queue]
+    this.queue = []
+
+    const payload = JSON.stringify({
+      events,
+      sessionId: this.sessionId,
+      sessionDuration: Date.now() - this.sessionStart
+    })
+
+    if (this.debug) {
+      console.log('[Analytics] Flushing', events.length, 'events')
+    }
+
+    // Use sendBeacon for reliable delivery on page unload
+    if (useBeacon && navigator.sendBeacon) {
+      const blob = new Blob([payload], { type: 'application/json' })
+      const sent = navigator.sendBeacon(this.endpoint, blob)
+
+      if (!sent && this.debug) {
+        console.warn('[Analytics] sendBeacon failed, events may be lost')
+      }
+      return
+    }
+
+    // Use fetch for normal flush
+    fetch(this.endpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: payload,
+      keepalive: true // Allows request to outlive page
+    }).catch((error) => {
+      if (this.debug) {
+        console.warn('[Analytics] Flush failed:', error)
+      }
+      // Put events back in queue for retry
+      this.queue.unshift(...events)
+    })
+  }
+
+  /**
+   * Clean up (stop interval, flush remaining events)
+   */
+  destroy() {
+    if (this.flushIntervalId) {
+      clearInterval(this.flushIntervalId)
+    }
+    this.flush(true)
+  }
+}

package/src/index.js

@@ -13,6 +13,7 @@ export { default as Website } from './website.js'
 export { default as Page } from './page.js'
 export { default as Block } from './block.js'
 export { default as Input } from './input.js'
+export { default as Analytics } from './analytics.js'
 
 /**
  * The singleton Uniweb instance.

package/src/page.js

@@ -1,52 +1,143 @@
 /**
  * Page
  *
- * Represents a single page with header, body sections, and footer.
+ * Represents a single page with header, body, footer, and panel sections.
+ * Each layout area can have multiple sections/blocks.
  */
 
 import Block from './block.js'
 
 export default class Page {
-  constructor(pageData, id, pageHeader, pageFooter) {
+  constructor(pageData, id, pageHeader, pageFooter, pageLeft, pageRight) {
     this.id = id
     this.route = pageData.route
     this.title = pageData.title || ''
     this.description = pageData.description || ''
+    this.label = pageData.label || null // Short label for navigation (null = use title)
+    this.keywords = pageData.keywords || null
+    this.order = pageData.order ?? 0
+    this.lastModified = pageData.lastModified || null
 
+    // Navigation visibility options
+    this.hidden = pageData.hidden || false
+    this.hideInHeader = pageData.hideInHeader || false
+    this.hideInFooter = pageData.hideInFooter || false
+
+    // Layout options (per-page overrides for header/footer/panels)
+    this.layout = {
+      header: pageData.layout?.header !== false,
+      footer: pageData.layout?.footer !== false,
+      left: pageData.layout?.left !== false,
+      right: pageData.layout?.right !== false,
+      // Aliases for backwards compatibility
+      leftPanel: pageData.layout?.left !== false,
+      rightPanel: pageData.layout?.right !== false
+    }
+
+    // SEO configuration
+    this.seo = {
+      noindex: pageData.seo?.noindex || false,
+      image: pageData.seo?.image || null,
+      ogTitle: pageData.seo?.ogTitle || null,
+      ogDescription: pageData.seo?.ogDescription || null,
+      canonical: pageData.seo?.canonical || null,
+      changefreq: pageData.seo?.changefreq || null,
+      priority: pageData.seo?.priority || null
+    }
+
+    // Child pages (for nested hierarchy) - populated by Website
+    this.children = []
+
+    // Back-reference to website (set by Website constructor)
+    this.website = null
+    this.site = null // Alias
+
+    // Scroll position memory (for navigation restoration)
+    this.scrollY = 0
+
+    // Build block groups for all layout areas
     this.pageBlocks = this.buildPageBlocks(
       pageData.sections,
       pageHeader?.sections,
-      pageFooter?.sections
+      pageFooter?.sections,
+      pageLeft?.sections,
+      pageRight?.sections
     )
   }
 
   /**
-   * Build the page block structure
+   * Get metadata for head tags
+   * @returns {Object} Head metadata
    */
-  buildPageBlocks(body, header, footer) {
-    const headerSection = header?.[0]
-    const footerSection = footer?.[0]
-    const bodySections = body || []
+  getHeadMeta() {
+    return {
+      title: this.title,
+      description: this.description,
+      keywords: this.keywords,
+      canonical: this.seo.canonical,
+      robots: this.seo.noindex ? 'noindex, nofollow' : null,
+      og: {
+        title: this.seo.ogTitle || this.title,
+        description: this.seo.ogDescription || this.description,
+        image: this.seo.image,
+        url: this.route
+      }
+    }
+  }
+
+  /**
+   * Build the page block structure for all layout areas.
+   * Each area can have multiple sections/blocks.
+   *
+   * @param {Array} body - Body sections from page content
+   * @param {Array} header - Header sections from @header page
+   * @param {Array} footer - Footer sections from @footer page
+   * @param {Array} left - Left panel sections from @left page
+   * @param {Array} right - Right panel sections from @right page
+   * @returns {Object} Block groups for each layout area
+   */
+  buildPageBlocks(body, header, footer, left, right) {
+    const buildBlocks = (sections, prefix) => {
+      if (!sections || sections.length === 0) return null
+      return sections.map((section, index) => new Block(section, `${prefix}-${index}`))
+    }
 
     return {
-      header: headerSection ? new Block(headerSection, 'header') : null,
-      body: bodySections.map((section, index) => new Block(section, index)),
-      footer: footerSection ? new Block(footerSection, 'footer') : null,
-      leftPanel: null,
-      rightPanel: null
+      header: buildBlocks(header, 'header'),
+      body: (body || []).map((section, index) => new Block(section, index)),
+      footer: buildBlocks(footer, 'footer'),
+      left: buildBlocks(left, 'left'),
+      right: buildBlocks(right, 'right')
     }
   }
 
+  /**
+   * Get all block groups (for Layout component)
+   * @returns {Object} { header, body, footer, left, right }
+   */
+  getBlockGroups() {
+    return this.pageBlocks
+  }
+
   /**
    * Get all blocks (header, body, footer) as flat array
+   * Respects page layout preferences (hasHeader, hasFooter, etc.)
    * @returns {Block[]}
    */
   getPageBlocks() {
-    return [
-      this.pageBlocks.header,
-      ...this.pageBlocks.body,
-      this.pageBlocks.footer
-    ].filter(Boolean)
+    const blocks = []
+
+    if (this.hasHeader() && this.pageBlocks.header) {
+      blocks.push(...this.pageBlocks.header)
+    }
+
+    blocks.push(...this.pageBlocks.body)
+
+    if (this.hasFooter() && this.pageBlocks.footer) {
+      blocks.push(...this.pageBlocks.footer)
+    }
+
+    return blocks
   }
 
   /**
@@ -58,18 +149,151 @@ export default class Page {
   }
 
   /**
-   * Get header block
+   * Get header blocks (respects layout preference)
+   * @returns {Block[]|null}
+   */
+  getHeaderBlocks() {
+    if (!this.hasHeader()) return null
+    return this.pageBlocks.header
+  }
+
+  /**
+   * Get footer blocks (respects layout preference)
+   * @returns {Block[]|null}
+   */
+  getFooterBlocks() {
+    if (!this.hasFooter()) return null
+    return this.pageBlocks.footer
+  }
+
+  /**
+   * Get left panel blocks (respects layout preference)
+   * @returns {Block[]|null}
+   */
+  getLeftBlocks() {
+    if (!this.hasLeftPanel()) return null
+    return this.pageBlocks.left
+  }
+
+  /**
+   * Get right panel blocks (respects layout preference)
+   * @returns {Block[]|null}
+   */
+  getRightBlocks() {
+    if (!this.hasRightPanel()) return null
+    return this.pageBlocks.right
+  }
+
+  /**
+   * Get header block (legacy - returns first block)
    * @returns {Block|null}
+   * @deprecated Use getHeaderBlocks() instead
    */
   getHeader() {
-    return this.pageBlocks.header
+    return this.pageBlocks.header?.[0] || null
   }
 
   /**
-   * Get footer block
+   * Get footer block (legacy - returns first block)
    * @returns {Block|null}
+   * @deprecated Use getFooterBlocks() instead
    */
   getFooter() {
-    return this.pageBlocks.footer
+    return this.pageBlocks.footer?.[0] || null
+  }
+
+  /**
+   * Reset block states (for scroll restoration)
+   */
+  resetBlockStates() {
+    const allBlocks = [
+      ...(this.pageBlocks.header || []),
+      ...this.pageBlocks.body,
+      ...(this.pageBlocks.footer || []),
+      ...(this.pageBlocks.left || []),
+      ...(this.pageBlocks.right || [])
+    ]
+
+    for (const block of allBlocks) {
+      if (typeof block.initState === 'function') {
+        block.initState()
+      }
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Navigation and Layout Helpers
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Get display label for navigation (short form of title)
+   * @returns {string}
+   */
+  getLabel() {
+    return this.label || this.title
+  }
+
+  /**
+   * Check if page should be hidden from navigation
+   * @returns {boolean}
+   */
+  isHidden() {
+    return this.hidden
+  }
+
+  /**
+   * Check if page should appear in header navigation
+   * @returns {boolean}
+   */
+  showInHeader() {
+    return !this.hidden && !this.hideInHeader
+  }
+
+  /**
+   * Check if page should appear in footer navigation
+   * @returns {boolean}
+   */
+  showInFooter() {
+    return !this.hidden && !this.hideInFooter
+  }
+
+  /**
+   * Check if header should be rendered on this page
+   * @returns {boolean}
+   */
+  hasHeader() {
+    return this.layout.header
+  }
+
+  /**
+   * Check if footer should be rendered on this page
+   * @returns {boolean}
+   */
+  hasFooter() {
+    return this.layout.footer
+  }
+
+  /**
+   * Check if left panel should be rendered on this page
+   * @returns {boolean}
+   */
+  hasLeftPanel() {
+    return this.layout.leftPanel
+  }
+
+  /**
+   * Check if right panel should be rendered on this page
+   * @returns {boolean}
+   */
+  hasRightPanel() {
+    return this.layout.rightPanel
+  }
+
+  /**
+   * Check if page has child pages
+   * @returns {boolean}
+   */
+  hasChildren() {
+    return this.children.length > 0
   }
 }

package/src/uniweb.js

@@ -6,6 +6,7 @@
  */
 
 import Website from './website.js'
+import Analytics from './analytics.js'
 
 export default class Uniweb {
   constructor(configData) {
@@ -15,6 +16,9 @@ export default class Uniweb {
     this.foundation = null // The loaded foundation module
     this.foundationConfig = {} // Configuration from foundation
     this.language = 'en'
+
+    // Initialize analytics (disabled by default, configure via site config)
+    this.analytics = new Analytics(configData.analytics || {})
   }
 
   /**

package/src/website.js

@@ -6,21 +6,55 @@
 
 import Page from './page.js'
 
+// Common locale display names
+const LOCALE_NAMES = {
+  en: 'English',
+  es: 'Español',
+  fr: 'Français',
+  de: 'Deutsch',
+  it: 'Italiano',
+  pt: 'Português',
+  nl: 'Nederlands',
+  pl: 'Polski',
+  ru: 'Русский',
+  ja: '日本語',
+  ko: '한국어',
+  zh: '中文',
+  ar: 'العربية'
+}
+
 export default class Website {
   constructor(websiteData) {
-    const { pages = [], theme = {}, config = {} } = websiteData
+    const { pages = [], theme = {}, config = {}, header, footer, left, right } = websiteData
+
+    // Site metadata
+    this.name = config.name || ''
+    this.description = config.description || ''
+    this.url = config.url || ''
 
-    // Extract special pages (header, footer) and regular pages
-    this.headerPage = pages.find((p) => p.route === '/@header')
-    this.footerPage = pages.find((p) => p.route === '/@footer')
+    // Store special pages (layout areas)
+    // These come from top-level properties set by content-collector
+    // Fallback to searching pages array for backwards compatibility
+    this.headerPage = header || pages.find((p) => p.route === '/@header') || null
+    this.footerPage = footer || pages.find((p) => p.route === '/@footer') || null
+    this.leftPage = left || pages.find((p) => p.route === '/@left') || null
+    this.rightPage = right || pages.find((p) => p.route === '/@right') || null
 
+    // Filter out special pages from regular pages array
+    const specialRoutes = ['/@header', '/@footer', '/@left', '/@right']
     this.pages = pages
-      .filter((page) => page.route !== '/@header' && page.route !== '/@footer')
+      .filter((page) => !specialRoutes.includes(page.route))
       .map(
         (page, index) =>
-          new Page(page, index, this.headerPage, this.footerPage)
+          new Page(page, index, this.headerPage, this.footerPage, this.leftPage, this.rightPage)
       )
 
+    // Set reference from pages back to website
+    for (const page of this.pages) {
+      page.website = this
+      page.site = this // Alias
+    }
+
     this.activePage =
       this.pages.find((page) => page.route === '/' || page.route === '/index') ||
       this.pages[0]
@@ -28,11 +62,46 @@ export default class Website {
     this.pageRoutes = this.pages.map((page) => page.route)
     this.themeData = theme
     this.config = config
-    this.activeLang = config.defaultLanguage || 'en'
-    this.langs = config.languages || [
-      { label: 'English', value: 'en' },
-      { label: 'français', value: 'fr' }
-    ]
+
+    // Locale configuration
+    this.defaultLocale = config.defaultLanguage || 'en'
+    this.activeLocale = config.activeLocale || this.defaultLocale
+
+    // Build locales list from i18n config
+    this.locales = this.buildLocalesList(config)
+
+    // Legacy language support (for editor multilingual)
+    this.activeLang = this.activeLocale
+    this.langs = config.languages || this.locales.map(l => ({
+      label: l.label,
+      value: l.code
+    }))
+  }
+
+  /**
+   * Build locales list from config
+   * @private
+   */
+  buildLocalesList(config) {
+    const defaultLocale = config.defaultLanguage || 'en'
+    const i18nLocales = config.i18n?.locales || []
+
+    // Start with default locale
+    const allLocaleCodes = [defaultLocale]
+
+    // Add translated locales (avoiding duplicates)
+    for (const locale of i18nLocales) {
+      if (!allLocaleCodes.includes(locale)) {
+        allLocaleCodes.push(locale)
+      }
+    }
+
+    // Build full locale objects
+    return allLocaleCodes.map(code => ({
+      code,
+      label: LOCALE_NAMES[code] || code.toUpperCase(),
+      isDefault: code === defaultLocale
+    }))
   }
 
   /**
@@ -88,6 +157,7 @@ export default class Website {
 
   /**
    * Get available languages
+   * @deprecated Use getLocales() instead
    */
   getLanguages() {
     return this.langs
@@ -95,11 +165,91 @@ export default class Website {
 
   /**
    * Get current language
+   * @deprecated Use getActiveLocale() instead
    */
   getLanguage() {
     return this.activeLang
   }
 
+  // ─────────────────────────────────────────────────────────────────
+  // Locale API (new)
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Get all available locales
+   * @returns {Array<{code: string, label: string, isDefault: boolean}>}
+   */
+  getLocales() {
+    return this.locales
+  }
+
+  /**
+   * Get currently active locale code
+   * @returns {string}
+   */
+  getActiveLocale() {
+    return this.activeLocale
+  }
+
+  /**
+   * Get the default locale code
+   * @returns {string}
+   */
+  getDefaultLocale() {
+    return this.defaultLocale
+  }
+
+  /**
+   * Check if site has multiple locales (useful for showing language switcher)
+   * @returns {boolean}
+   */
+  hasMultipleLocales() {
+    return this.locales.length > 1
+  }
+
+  /**
+   * Set the active locale
+   * @param {string} localeCode - Locale code to activate
+   */
+  setActiveLocale(localeCode) {
+    const locale = this.locales.find(l => l.code === localeCode)
+    if (locale) {
+      this.activeLocale = localeCode
+      this.activeLang = localeCode // Keep legacy in sync
+    }
+  }
+
+  /**
+   * Build URL for a specific locale
+   * @param {string} localeCode - Target locale code
+   * @param {string} route - Page route (default: current page route)
+   * @returns {string}
+   */
+  getLocaleUrl(localeCode, route = null) {
+    const targetRoute = route || this.activePage?.route || '/'
+
+    // Default locale uses root path (no prefix)
+    if (localeCode === this.defaultLocale) {
+      return targetRoute
+    }
+
+    // Other locales use /locale/ prefix
+    if (targetRoute === '/') {
+      return `/${localeCode}/`
+    }
+
+    return `/${localeCode}${targetRoute}`
+  }
+
+  /**
+   * Get locale info by code
+   * @param {string} localeCode - Locale code
+   * @returns {Object|undefined} Locale object or undefined
+   */
+  getLocale(localeCode) {
+    return this.locales.find(l => l.code === localeCode)
+  }
+
   /**
    * Localize a value
    * @param {any} val - Value to localize (object with lang keys, or string)
@@ -154,4 +304,111 @@ export default class Website {
         .join('\n')
     }))
   }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Page Hierarchy API (for navigation components)
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Get page hierarchy for building navigation (navbar, footer, sitemap)
+   *
+   * This is the primary API for navigation components. It returns pages
+   * filtered and formatted for navigation use.
+   *
+   * @param {Object} options - Configuration options
+   * @param {boolean} [options.nested=true] - Return nested hierarchy (with children) or flat list
+   * @param {string} [options.for] - Filter for specific navigation: 'header', 'footer', or undefined (all)
+   * @param {boolean} [options.includeHidden=false] - Include hidden pages
+   * @param {function} [options.filter] - Custom filter function (page) => boolean
+   * @param {function} [options.sort] - Custom sort function (a, b) => number
+   * @returns {Array<Object>} Array of page info objects for navigation
+   *
+   * @example
+   * // Get pages for header navigation
+   * const headerPages = website.getPageHierarchy({ for: 'header' })
+   *
+   * // Get flat list of all pages
+   * const allPages = website.getPageHierarchy({ nested: false, includeHidden: true })
+   *
+   * // Custom filtering
+   * const topLevel = website.getPageHierarchy({
+   *   filter: (page) => page.order < 10
+   * })
+   */
+  getPageHierarchy(options = {}) {
+    const {
+      nested = true,
+      for: navType,
+      includeHidden = false,
+      filter: customFilter,
+      sort: customSort
+    } = options
+
+    // Filter pages based on navigation type and visibility
+    let filteredPages = this.pages.filter(page => {
+      // Always exclude special pages (header/footer are already separated)
+      if (page.route.startsWith('/@')) return false
+
+      // Check visibility based on navigation type
+      if (!includeHidden) {
+        if (page.hidden) return false
+        if (navType === 'header' && page.hideInHeader) return false
+        if (navType === 'footer' && page.hideInFooter) return false
+      }
+
+      // Apply custom filter if provided
+      if (customFilter && !customFilter(page)) return false
+
+      return true
+    })
+
+    // Apply custom sort or default to order
+    if (customSort) {
+      filteredPages.sort(customSort)
+    }
+    // Already sorted by order in constructor, so no need to re-sort
+
+    // Build page info objects
+    const buildPageInfo = (page) => ({
+      id: page.id,
+      route: page.route === '/' ? '' : page.route,
+      title: page.title,
+      label: page.getLabel(),
+      description: page.description,
+      order: page.order,
+      hasContent: page.getBodyBlocks().length > 0,
+      children: nested && page.hasChildren()
+        ? page.children.map(buildPageInfo)
+        : []
+    })
+
+    return filteredPages.map(buildPageInfo)
+  }
+
+  /**
+   * Get pages for header navigation
+   * Convenience method equivalent to getPageHierarchy({ for: 'header' })
+   * @returns {Array<Object>}
+   */
+  getHeaderPages() {
+    return this.getPageHierarchy({ for: 'header' })
+  }
+
+  /**
+   * Get pages for footer navigation
+   * Convenience method equivalent to getPageHierarchy({ for: 'footer' })
+   * @returns {Array<Object>}
+   */
+  getFooterPages() {
+    return this.getPageHierarchy({ for: 'footer' })
+  }
+
+  /**
+   * Get flat list of all pages (for sitemaps, search, etc.)
+   * @param {boolean} includeHidden - Include hidden pages
+   * @returns {Array<Object>}
+   */
+  getAllPages(includeHidden = false) {
+    return this.getPageHierarchy({ nested: false, includeHidden })
+  }
 }