@uniweb/runtime 0.1.2 → 0.2.2

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

@@ -1,23 +1,23 @@
 /**
  * @uniweb/runtime - Main Entry Point
  *
- * This is the Vite/ESM-based runtime that loads foundations via dynamic import()
- * instead of Webpack Module Federation.
+ * Minimal runtime for loading foundations and orchestrating rendering.
+ * Foundations should import components from @uniweb/kit.
  */
 
 import React from 'react'
 import { createRoot } from 'react-dom/client'
-import { BrowserRouter, Routes, Route, useParams, useLocation, useNavigate } from 'react-router-dom'
+import { BrowserRouter, Routes, Route } from 'react-router-dom'
 
 // Components
 import { ChildBlocks } from './components/PageRenderer.jsx'
-import Link from './components/Link.jsx'
-import SafeHtml from './components/SafeHtml.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
-import Uniweb from './core/uniweb.js'
+// Core factory from @uniweb/core
+import { createUniweb } from '@uniweb/core'
 
 /**
  * Load foundation CSS from URL
@@ -60,8 +60,10 @@ async function loadFoundation(source) {
       import(/* @vite-ignore */ url)
     ])
 
-    console.log('[Runtime] Foundation loaded. Available components:',
-      typeof foundation.listComponents === 'function' ? foundation.listComponents() : 'unknown')
+    console.log(
+      '[Runtime] Foundation loaded. Available components:',
+      typeof foundation.listComponents === 'function' ? foundation.listComponents() : 'unknown'
+    )
 
     return foundation
   } catch (error) {
@@ -76,23 +78,12 @@ async function loadFoundation(source) {
  * @returns {Uniweb}
  */
 function initUniweb(configData) {
-  const uniwebInstance = new Uniweb(configData)
+  // Create singleton via @uniweb/core (also assigns to globalThis.uniweb)
+  const uniwebInstance = createUniweb(configData)
 
-  // Global assignment for component access
-  globalThis.uniweb = uniwebInstance
-
-  // Set up child block renderer
+  // Set up child block renderer for nested blocks
   uniwebInstance.childBlockRenderer = ChildBlocks
 
-  // Set up routing components for foundation components to use
-  uniwebInstance.routingComponents = {
-    Link,
-    SafeHtml,
-    useNavigate,
-    useParams,
-    useLocation
-  }
-
   return uniwebInstance
 }
 
@@ -149,9 +140,10 @@ async function initRuntime(foundationSource, options = {}) {
   } = options
 
   // Get config data from options, DOM, or global
-  const configData = providedConfig
-    ?? JSON.parse(document.getElementById('__SITE_CONTENT__')?.textContent || 'null')
-    ?? globalThis.__SITE_CONTENT__
+  const configData =
+    providedConfig ??
+    JSON.parse(document.getElementById('__SITE_CONTENT__')?.textContent || 'null') ??
+    globalThis.__SITE_CONTENT__
 
   if (!configData) {
     console.error('[Runtime] No site configuration found')
@@ -205,7 +197,7 @@ async function initRuntime(foundationSource, options = {}) {
         '%c<%c>%c Uniweb Runtime',
         'color: #FA8400; font-weight: bold; font-size: 18px;',
         'color: #00ADFE; font-weight: bold; font-size: 18px;',
-        "color: #333; font-size: 18px; font-family: system-ui, sans-serif;"
+        'color: #333; font-size: 18px; font-family: system-ui, sans-serif;'
       )
     }
   } catch (error) {
@@ -216,7 +208,15 @@ async function initRuntime(foundationSource, options = {}) {
     if (container) {
       const root = createRoot(container)
       root.render(
-        <div style={{ padding: '2rem', margin: '1rem', background: '#fef2f2', borderRadius: '0.5rem', color: '#dc2626' }}>
+        <div
+          style={{
+            padding: '2rem',
+            margin: '1rem',
+            background: '#fef2f2',
+            borderRadius: '0.5rem',
+            color: '#dc2626'
+          }}
+        >
           <h2>Runtime Error</h2>
           <p>{error.message}</p>
           {development && <pre style={{ fontSize: '0.75rem', overflow: 'auto' }}>{error.stack}</pre>}
@@ -226,20 +226,5 @@ async function initRuntime(foundationSource, options = {}) {
   }
 }
 
-// Legacy alias
-const initRTE = initRuntime
-
-// Exports
-export {
-  initRuntime,
-  initRTE,
-  // Components for external use
-  Link,
-  SafeHtml,
-  ChildBlocks,
-  ErrorBoundary,
-  // Core classes
-  Uniweb
-}
-
+export { initRuntime }
 export default initRuntime

package/src/components/Link.jsx

@@ -1,28 +0,0 @@
-/**
- * Link
- *
- * A wrapper around React Router's Link that integrates with the runtime.
- */
-
-import React from 'react'
-import { Link as RouterLink } from 'react-router-dom'
-
-export default function Link({ to, href, children, className, ...props }) {
-  const target = to || href
-
-  // External links
-  if (target?.startsWith('http') || target?.startsWith('mailto:') || target?.startsWith('tel:')) {
-    return (
-      <a href={target} className={className} {...props}>
-        {children}
-      </a>
-    )
-  }
-
-  // Internal links via React Router
-  return (
-    <RouterLink to={target || '/'} className={className} {...props}>
-      {children}
-    </RouterLink>
-  )
-}

package/src/components/SafeHtml.jsx

@@ -1,22 +0,0 @@
-/**
- * SafeHtml
- *
- * Safely render HTML content with sanitization.
- * TODO: Add DOMPurify for production use
- */
-
-import React from 'react'
-
-export default function SafeHtml({ html, className, as: Component = 'div', ...props }) {
-  if (!html) return null
-
-  // For now, render directly
-  // TODO: Integrate DOMPurify for sanitization
-  return (
-    <Component
-      className={className}
-      dangerouslySetInnerHTML={{ __html: html }}
-      {...props}
-    />
-  )
-}