@uniweb/runtime 0.2.1 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/runtime",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Minimal runtime for loading Uniweb foundations",
   "type": "module",
   "exports": {
@@ -29,7 +29,7 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "@uniweb/core": "0.1.2"
+    "@uniweb/core": "0.1.5"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

package/src/components/Blocks.jsx

@@ -0,0 +1,26 @@
+/**
+ * Blocks
+ *
+ * Renders an array of blocks for a layout area (header, body, footer, panels).
+ * Used by the Layout component to pre-render each area.
+ */
+
+import React from 'react'
+import BlockRenderer from './BlockRenderer.jsx'
+
+/**
+ * Render a list of blocks
+ *
+ * @param {Object} props
+ * @param {Block[]} props.blocks - Array of Block instances to render
+ * @param {Object} [props.extra] - Extra props to pass to each block
+ */
+export default function Blocks({ blocks, extra = {} }) {
+  if (!blocks || blocks.length === 0) return null
+
+  return blocks.map((block, index) => (
+    <React.Fragment key={block.id || index}>
+      <BlockRenderer block={block} extra={extra} />
+    </React.Fragment>
+  ))
+}

package/src/components/Layout.jsx

@@ -0,0 +1,100 @@
+/**
+ * Layout
+ *
+ * Orchestrates page rendering by assembling layout areas (header, body, footer, panels).
+ * Supports foundation-provided custom Layout components via website.getRemoteLayout().
+ *
+ * Layout Areas:
+ * - header: Top navigation, branding (from @header page)
+ * - body: Main page content (from page sections)
+ * - footer: Bottom navigation, copyright (from @footer page)
+ * - left: Left sidebar/panel (from @left page)
+ * - right: Right sidebar/panel (from @right page)
+ *
+ * Custom Layouts:
+ * Foundations can export a Layout component that receives pre-rendered areas as props:
+ *
+ * ```jsx
+ * export const site = {
+ *   Layout: ({ page, website, header, body, footer, left, right }) => (
+ *     <div className="my-layout">
+ *       <header>{header}</header>
+ *       <aside>{left}</aside>
+ *       <main>{body}</main>
+ *       <aside>{right}</aside>
+ *       <footer>{footer}</footer>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+
+import React from 'react'
+import Blocks from './Blocks.jsx'
+
+/**
+ * Default layout - renders header, body, footer in sequence
+ * (no panels in default layout)
+ */
+function DefaultLayout({ header, body, footer }) {
+  return (
+    <>
+      {header}
+      {body}
+      {footer}
+    </>
+  )
+}
+
+/**
+ * Layout component
+ *
+ * @param {Object} props
+ * @param {Page} props.page - Current page instance
+ * @param {Website} props.website - Website instance
+ */
+export default function Layout({ page, website }) {
+  // Check if foundation provides a custom Layout
+  const RemoteLayout = website.getRemoteLayout()
+
+  // Get block groups from page (respects layout preferences)
+  const headerBlocks = page.getHeaderBlocks()
+  const bodyBlocks = page.getBodyBlocks()
+  const footerBlocks = page.getFooterBlocks()
+  const leftBlocks = page.getLeftBlocks()
+  const rightBlocks = page.getRightBlocks()
+
+  // Pre-render each area as React elements
+  const headerElement = headerBlocks ? <Blocks blocks={headerBlocks} /> : null
+  const bodyElement = bodyBlocks ? <Blocks blocks={bodyBlocks} /> : null
+  const footerElement = footerBlocks ? <Blocks blocks={footerBlocks} /> : null
+  const leftElement = leftBlocks ? <Blocks blocks={leftBlocks} /> : null
+  const rightElement = rightBlocks ? <Blocks blocks={rightBlocks} /> : null
+
+  // Use foundation's custom Layout if provided
+  if (RemoteLayout) {
+    return (
+      <RemoteLayout
+        page={page}
+        website={website}
+        header={headerElement}
+        body={bodyElement}
+        footer={footerElement}
+        left={leftElement}
+        right={rightElement}
+        // Aliases for backwards compatibility
+        leftPanel={leftElement}
+        rightPanel={rightElement}
+      />
+    )
+  }
+
+  // Default layout
+  return (
+    <DefaultLayout
+      header={headerElement}
+      body={bodyElement}
+      footer={footerElement}
+    />
+  )
+}

package/src/components/PageRenderer.jsx

@@ -1,11 +1,15 @@
 /**
  * PageRenderer
  *
- * Renders a page by iterating through its blocks.
+ * Renders a page using the Layout component for proper orchestration
+ * of header, body, footer, and panel areas.
+ * Manages head meta tags for SEO and social sharing.
  */
 
-import React, { useEffect } from 'react'
+import React from 'react'
 import BlockRenderer from './BlockRenderer.jsx'
+import Layout from './Layout.jsx'
+import { useHeadMeta } from '../hooks/useHeadMeta.js'
 
 /**
  * ChildBlocks - renders child blocks of a block
@@ -23,17 +27,27 @@ export function ChildBlocks({ block, childBlocks, pure = false, extra = {} }) {
 
 /**
  * PageRenderer component
+ *
+ * Renders the current page using the Layout system which supports:
+ * - Header, body, footer areas
+ * - Left and right panels
+ * - Foundation-provided custom layouts
+ * - Per-page layout preferences
  */
 export default function PageRenderer() {
-  const page = globalThis.uniweb?.activeWebsite?.activePage
-  const pageTitle = page?.title || 'Website'
+  const uniweb = globalThis.uniweb
+  const website = uniweb?.activeWebsite
+  const page = website?.activePage
+  const siteName = website?.name || ''
+
+  // Get head metadata from page (uses Page.getHeadMeta() if available)
+  const headMeta = page?.getHeadMeta?.() || {
+    title: page?.title || 'Website',
+    description: page?.description || ''
+  }
 
-  useEffect(() => {
-    document.title = pageTitle
-    return () => {
-      document.title = 'Website'
-    }
-  }, [pageTitle])
+  // Manage head meta tags
+  useHeadMeta(headMeta, { siteName })
 
   if (!page) {
     return (
@@ -43,15 +57,6 @@ export default function PageRenderer() {
     )
   }
 
-  const blocks = page.getPageBlocks()
-
-  return (
-    <>
-      {blocks.map((block, index) => (
-        <React.Fragment key={block.id || index}>
-          <BlockRenderer block={block} />
-        </React.Fragment>
-      ))}
-    </>
-  )
+  // Use Layout component for proper orchestration
+  return <Layout page={page} website={website} />
 }

package/src/components/WebsiteRenderer.jsx

@@ -2,10 +2,12 @@
  * WebsiteRenderer
  *
  * Top-level renderer that sets up theme styles and renders pages.
+ * Manages scroll memory for navigation and optional analytics.
  */
 
 import React from 'react'
 import PageRenderer from './PageRenderer.jsx'
+import { useRememberScroll } from '../hooks/useRememberScroll.js'
 
 /**
  * Build CSS custom properties from theme data
@@ -57,6 +59,9 @@ function Fonts({ fontsData }) {
 export default function WebsiteRenderer() {
   const website = globalThis.uniweb?.activeWebsite
 
+  // Enable scroll memory for navigation
+  useRememberScroll({ enabled: true })
+
   if (!website) {
     return (
       <div className="website-loading" style={{ padding: '2rem', textAlign: 'center', color: '#64748b' }}>

package/src/hooks/useHeadMeta.js

@@ -0,0 +1,188 @@
+/**
+ * useHeadMeta Hook
+ *
+ * Manages document head meta tags for SEO and social sharing.
+ * Updates meta tags when page changes in SPA navigation.
+ */
+
+import { useEffect, useRef } from 'react'
+
+/**
+ * Meta tag definitions for easy management
+ */
+const META_TAGS = {
+  description: { name: 'description' },
+  keywords: { name: 'keywords' },
+  robots: { name: 'robots' },
+  'og:title': { property: 'og:title' },
+  'og:description': { property: 'og:description' },
+  'og:image': { property: 'og:image' },
+  'og:url': { property: 'og:url' },
+  'og:type': { property: 'og:type' },
+  'twitter:card': { name: 'twitter:card' },
+  'twitter:title': { name: 'twitter:title' },
+  'twitter:description': { name: 'twitter:description' },
+  'twitter:image': { name: 'twitter:image' }
+}
+
+/**
+ * Get or create a meta tag element
+ * @param {string} key - Meta tag key (e.g., 'description', 'og:title')
+ * @returns {HTMLMetaElement}
+ */
+function getOrCreateMetaTag(key) {
+  const config = META_TAGS[key]
+  if (!config) return null
+
+  const selector = config.property
+    ? `meta[property="${config.property}"]`
+    : `meta[name="${config.name}"]`
+
+  let element = document.querySelector(selector)
+
+  if (!element) {
+    element = document.createElement('meta')
+    if (config.property) {
+      element.setAttribute('property', config.property)
+    } else {
+      element.setAttribute('name', config.name)
+    }
+    document.head.appendChild(element)
+  }
+
+  return element
+}
+
+/**
+ * Get or create a link element (for canonical)
+ * @param {string} rel - Link rel attribute
+ * @returns {HTMLLinkElement}
+ */
+function getOrCreateLinkTag(rel) {
+  let element = document.querySelector(`link[rel="${rel}"]`)
+
+  if (!element) {
+    element = document.createElement('link')
+    element.setAttribute('rel', rel)
+    document.head.appendChild(element)
+  }
+
+  return element
+}
+
+/**
+ * Set or remove a meta tag's content
+ * @param {string} key - Meta tag key
+ * @param {string|null} content - Content value (null to remove)
+ */
+function setMetaContent(key, content) {
+  const element = getOrCreateMetaTag(key)
+  if (!element) return
+
+  if (content) {
+    element.setAttribute('content', content)
+  } else {
+    // Remove the tag if no content
+    element.remove()
+  }
+}
+
+/**
+ * useHeadMeta hook
+ *
+ * @param {Object} meta - Head metadata
+ * @param {string} meta.title - Page title
+ * @param {string} meta.description - Meta description
+ * @param {string} meta.keywords - Meta keywords (string or array)
+ * @param {string} meta.canonical - Canonical URL
+ * @param {string} meta.robots - Robots directive (e.g., 'noindex, nofollow')
+ * @param {Object} meta.og - Open Graph metadata
+ * @param {string} meta.og.title - OG title
+ * @param {string} meta.og.description - OG description
+ * @param {string} meta.og.image - OG image URL
+ * @param {string} meta.og.url - OG URL
+ * @param {Object} options - Hook options
+ * @param {string} options.siteName - Site name for title suffix
+ * @param {string} options.titleSeparator - Separator between page title and site name
+ */
+export function useHeadMeta(meta, options = {}) {
+  const {
+    siteName = '',
+    titleSeparator = ' | '
+  } = options
+
+  // Track created elements for cleanup
+  const createdElements = useRef([])
+
+  useEffect(() => {
+    if (!meta) return
+
+    // Update document title
+    if (meta.title) {
+      const fullTitle = siteName
+        ? `${meta.title}${titleSeparator}${siteName}`
+        : meta.title
+      document.title = fullTitle
+    }
+
+    // Update meta description
+    setMetaContent('description', meta.description || null)
+
+    // Update meta keywords
+    const keywords = Array.isArray(meta.keywords)
+      ? meta.keywords.join(', ')
+      : meta.keywords
+    setMetaContent('keywords', keywords || null)
+
+    // Update robots
+    setMetaContent('robots', meta.robots || null)
+
+    // Update Open Graph tags
+    if (meta.og) {
+      setMetaContent('og:title', meta.og.title || meta.title || null)
+      setMetaContent('og:description', meta.og.description || meta.description || null)
+      setMetaContent('og:image', meta.og.image || null)
+      setMetaContent('og:url', meta.og.url || null)
+      setMetaContent('og:type', 'website')
+
+      // Twitter cards (fallback to OG values)
+      setMetaContent('twitter:card', meta.og.image ? 'summary_large_image' : 'summary')
+      setMetaContent('twitter:title', meta.og.title || meta.title || null)
+      setMetaContent('twitter:description', meta.og.description || meta.description || null)
+      setMetaContent('twitter:image', meta.og.image || null)
+    }
+
+    // Update canonical link
+    if (meta.canonical) {
+      const canonicalLink = getOrCreateLinkTag('canonical')
+      canonicalLink.setAttribute('href', meta.canonical)
+    } else {
+      // Remove canonical if not set
+      const existingCanonical = document.querySelector('link[rel="canonical"]')
+      if (existingCanonical) {
+        existingCanonical.remove()
+      }
+    }
+
+    // Cleanup function - reset to defaults on unmount
+    return () => {
+      // We don't remove tags on cleanup because another page will set them
+      // Just reset title as a fallback
+      document.title = siteName || 'Website'
+    }
+  }, [
+    meta?.title,
+    meta?.description,
+    meta?.keywords,
+    meta?.canonical,
+    meta?.robots,
+    meta?.og?.title,
+    meta?.og?.description,
+    meta?.og?.image,
+    meta?.og?.url,
+    siteName,
+    titleSeparator
+  ])
+}
+
+export default useHeadMeta

package/src/hooks/useRememberScroll.js

@@ -0,0 +1,105 @@
+/**
+ * useRememberScroll Hook
+ *
+ * Remembers scroll position per page and restores it on navigation.
+ * Works with Page.scrollY property for persistence.
+ *
+ * Behavior:
+ * - Saves scroll position when navigating away from a page
+ * - Restores scroll position when returning to a previously visited page
+ * - Scrolls to top for newly visited pages
+ * - Optionally resets block states on scroll restoration
+ */
+
+import { useEffect, useRef } from 'react'
+import { useLocation } from 'react-router-dom'
+
+/**
+ * useRememberScroll hook
+ *
+ * @param {Object} options
+ * @param {boolean} options.enabled - Enable scroll memory (default: true)
+ * @param {boolean} options.resetBlockStates - Reset block states on restore (default: true)
+ * @param {number} options.scrollDelay - Delay before restoring scroll (default: 0)
+ */
+export function useRememberScroll(options = {}) {
+  const { enabled = true, resetBlockStates = true, scrollDelay = 0 } = options
+
+  const location = useLocation()
+  const previousPathRef = useRef(location.pathname)
+  const isFirstRender = useRef(true)
+
+  useEffect(() => {
+    if (!enabled) return
+
+    const uniweb = globalThis.uniweb
+    const website = uniweb?.activeWebsite
+    if (!website) return
+
+    // Get current and previous pages
+    const currentPage = website.activePage
+    const previousPath = previousPathRef.current
+    const currentPath = location.pathname
+
+    // Skip on first render
+    if (isFirstRender.current) {
+      isFirstRender.current = false
+      previousPathRef.current = currentPath
+      return
+    }
+
+    // Path hasn't changed (might be hash or search change)
+    if (previousPath === currentPath) {
+      return
+    }
+
+    // Save scroll position from previous page
+    const previousPage = website.getPage(previousPath)
+    if (previousPage) {
+      previousPage.scrollY = window.scrollY
+    }
+
+    // Restore or reset scroll for current page
+    if (currentPage) {
+      const targetScroll = currentPage.scrollY || 0
+
+      // Reset block states if requested (for animations, etc.)
+      if (resetBlockStates && typeof currentPage.resetBlockStates === 'function') {
+        currentPage.resetBlockStates()
+      }
+
+      // Restore scroll position
+      const restore = () => {
+        window.scrollTo(0, targetScroll)
+      }
+
+      if (scrollDelay > 0) {
+        setTimeout(restore, scrollDelay)
+      } else {
+        // Use requestAnimationFrame for smoother restoration
+        requestAnimationFrame(restore)
+      }
+    }
+
+    // Update previous path ref
+    previousPathRef.current = currentPath
+  }, [location.pathname, enabled, resetBlockStates, scrollDelay])
+
+  // Save scroll position before page unload
+  useEffect(() => {
+    if (!enabled) return
+
+    const handleBeforeUnload = () => {
+      const uniweb = globalThis.uniweb
+      const page = uniweb?.activeWebsite?.activePage
+      if (page) {
+        page.scrollY = window.scrollY
+      }
+    }
+
+    window.addEventListener('beforeunload', handleBeforeUnload)
+    return () => window.removeEventListener('beforeunload', handleBeforeUnload)
+  }, [enabled])
+}
+
+export default useRememberScroll

package/src/hooks/useScrollDepth.js

@@ -0,0 +1,71 @@
+/**
+ * useScrollDepth Hook
+ *
+ * Tracks scroll depth and reports to uniweb.analytics at milestones (25%, 50%, 75%, 100%).
+ * Only tracks if analytics is enabled.
+ */
+
+import { useEffect, useRef } from 'react'
+
+/**
+ * Calculate current scroll depth percentage
+ * @returns {number} Scroll depth 0-100
+ */
+function getScrollDepth() {
+  const scrollTop = window.scrollY
+  const docHeight = document.documentElement.scrollHeight - window.innerHeight
+
+  if (docHeight <= 0) return 100 // Page fits in viewport
+
+  return Math.min(100, Math.round((scrollTop / docHeight) * 100))
+}
+
+/**
+ * useScrollDepth hook
+ *
+ * Uses globalThis.uniweb.analytics for tracking.
+ *
+ * @param {Object} options
+ * @param {boolean} options.enabled - Enable tracking (default: true)
+ * @param {number} options.throttleMs - Throttle scroll events (default: 200)
+ */
+export function useScrollDepth(options = {}) {
+  const { enabled = true, throttleMs = 200 } = options
+
+  const lastCheck = useRef(0)
+  const reportedMilestones = useRef(new Set())
+
+  useEffect(() => {
+    const analytics = globalThis.uniweb?.analytics
+
+    // Skip if analytics not available or disabled
+    if (!enabled || !analytics?.isEnabled?.()) return
+
+    // Reset milestones on mount (new page)
+    reportedMilestones.current.clear()
+
+    const handleScroll = () => {
+      const now = Date.now()
+      if (now - lastCheck.current < throttleMs) return
+      lastCheck.current = now
+
+      const depth = getScrollDepth()
+      const milestones = [25, 50, 75, 100]
+
+      for (const milestone of milestones) {
+        if (depth >= milestone && !reportedMilestones.current.has(milestone)) {
+          reportedMilestones.current.add(milestone)
+          analytics.trackScrollDepth(milestone)
+        }
+      }
+    }
+
+    // Check initial scroll position
+    handleScroll()
+
+    window.addEventListener('scroll', handleScroll, { passive: true })
+    return () => window.removeEventListener('scroll', handleScroll)
+  }, [enabled, throttleMs])
+}
+
+export default useScrollDepth

package/src/index.jsx

@@ -13,6 +13,8 @@ import { BrowserRouter, Routes, Route } from 'react-router-dom'
 import { ChildBlocks } from './components/PageRenderer.jsx'
 import WebsiteRenderer from './components/WebsiteRenderer.jsx'
 import ErrorBoundary from './components/ErrorBoundary.jsx'
+import Layout from './components/Layout.jsx'
+import Blocks from './components/Blocks.jsx'
 
 // Core factory from @uniweb/core
 import { createUniweb } from '@uniweb/core'