@uniweb/kit 0.1.10 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.1.10",
+  "version": "0.2.0",
   "description": "Standard component library for Uniweb foundations",
   "type": "module",
   "exports": {
@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "tailwind-merge": "^2.6.0",
-    "@uniweb/core": "0.1.15"
+    "@uniweb/core": "0.2.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

package/src/components/Link/Link.jsx

@@ -170,8 +170,10 @@ export function Link({
   // Normalize href
   let linkHref = href || to || ''
 
-  // Handle topic: protocol (internal reference)
-  if (linkHref.startsWith('topic:')) {
+  // Handle internal reference protocols
+  // - topic: legacy internal reference
+  // - page: stable page reference (page:pageId#sectionId)
+  if (linkHref.startsWith('topic:') || linkHref.startsWith('page:')) {
     linkHref = makeHref(linkHref)
   }
 

package/src/hooks/index.js

@@ -1,8 +1,19 @@
 export { useWebsite, default } from './useWebsite.js'
 export { useRouting } from './useRouting.js'
 export { useActiveRoute } from './useActiveRoute.js'
+export { useVersion } from './useVersion.js'
 export { useScrolled } from './useScrolled.js'
 export { useMobileMenu } from './useMobileMenu.js'
 export { useAccordion } from './useAccordion.js'
 export { useGridLayout, getGridClasses } from './useGridLayout.js'
 export { useTheme, getThemeClasses, THEMES, THEME_NAMES } from './useTheme.js'
+export { useInView, useIsInView } from './useInView.js'
+
+// Theme data hooks (runtime theme access)
+export {
+  useThemeData,
+  useColorContext,
+  useAppearance,
+  useThemeColor,
+  useThemeColorVar
+} from './useThemeData.js'

package/src/hooks/useInView.js

@@ -0,0 +1,200 @@
+/**
+ * useInView Hook
+ *
+ * Detects when an element enters or leaves the viewport using IntersectionObserver.
+ * Useful for lazy loading, animations on scroll, and infinite scroll.
+ *
+ * @example
+ * // Basic usage - trigger animation when element enters viewport
+ * function AnimatedSection() {
+ *   const { ref, inView } = useInView()
+ *   return (
+ *     <div ref={ref} className={inView ? 'animate-fade-in' : 'opacity-0'}>
+ *       Content appears when scrolled into view
+ *     </div>
+ *   )
+ * }
+ *
+ * @example
+ * // Lazy load image when near viewport
+ * function LazyImage({ src, alt }) {
+ *   const { ref, inView } = useInView({
+ *     triggerOnce: true,
+ *     rootMargin: '200px',  // Load 200px before entering viewport
+ *   })
+ *   return (
+ *     <div ref={ref}>
+ *       {inView ? <img src={src} alt={alt} /> : <div className="placeholder" />}
+ *     </div>
+ *   )
+ * }
+ *
+ * @example
+ * // Threshold for partial visibility
+ * const { ref, inView } = useInView({
+ *   threshold: 0.5,  // Trigger when 50% visible
+ * })
+ */
+
+import { useState, useEffect, useRef, useCallback } from 'react'
+
+/**
+ * Default options for IntersectionObserver
+ */
+const DEFAULT_OPTIONS = {
+  threshold: 0,
+  rootMargin: '0px',
+  triggerOnce: false,
+  root: null,
+}
+
+/**
+ * Hook to detect when an element enters/leaves the viewport.
+ *
+ * @param {Object} options - Configuration options
+ * @param {number|number[]} options.threshold - Visibility ratio(s) to trigger (0-1). Default: 0
+ * @param {string} options.rootMargin - Margin around root. Default: '0px'
+ * @param {boolean} options.triggerOnce - Only trigger once, then stop observing. Default: false
+ * @param {Element|null} options.root - Scroll container (null = viewport). Default: null
+ * @param {boolean} options.initialInView - Initial inView state for SSR. Default: false
+ *
+ * @returns {Object} { ref, inView, entry }
+ * @returns {Function} ref - Callback ref to attach to the target element
+ * @returns {boolean} inView - Whether element is currently in viewport
+ * @returns {IntersectionObserverEntry|null} entry - Latest IntersectionObserver entry
+ */
+export function useInView(options = {}) {
+  const {
+    threshold = DEFAULT_OPTIONS.threshold,
+    rootMargin = DEFAULT_OPTIONS.rootMargin,
+    triggerOnce = DEFAULT_OPTIONS.triggerOnce,
+    root = DEFAULT_OPTIONS.root,
+    initialInView = false,
+  } = options
+
+  const [inView, setInView] = useState(initialInView)
+  const [entry, setEntry] = useState(null)
+
+  // Track if we've already triggered (for triggerOnce)
+  const hasTriggered = useRef(false)
+
+  // Store the observer instance
+  const observerRef = useRef(null)
+
+  // Store the current element
+  const elementRef = useRef(null)
+
+  /**
+   * Callback ref that handles element changes
+   */
+  const ref = useCallback(
+    (node) => {
+      // Clean up previous observer
+      if (observerRef.current) {
+        observerRef.current.disconnect()
+        observerRef.current = null
+      }
+
+      // Store the new element
+      elementRef.current = node
+
+      // Don't observe if:
+      // - No element
+      // - SSR (no IntersectionObserver)
+      // - Already triggered and triggerOnce is true
+      if (!node) return
+      if (typeof IntersectionObserver === 'undefined') return
+      if (triggerOnce && hasTriggered.current) return
+
+      // Create new observer
+      const observer = new IntersectionObserver(
+        ([observerEntry]) => {
+          const isIntersecting = observerEntry.isIntersecting
+
+          setInView(isIntersecting)
+          setEntry(observerEntry)
+
+          // Handle triggerOnce
+          if (isIntersecting && triggerOnce) {
+            hasTriggered.current = true
+            observer.disconnect()
+            observerRef.current = null
+          }
+        },
+        {
+          threshold,
+          rootMargin,
+          root,
+        }
+      )
+
+      observer.observe(node)
+      observerRef.current = observer
+    },
+    [threshold, rootMargin, root, triggerOnce]
+  )
+
+  // Clean up on unmount
+  useEffect(() => {
+    return () => {
+      if (observerRef.current) {
+        observerRef.current.disconnect()
+      }
+    }
+  }, [])
+
+  return { ref, inView, entry }
+}
+
+/**
+ * Simpler hook that just returns inView state for a ref'd element.
+ * Use when you don't need the entry details.
+ *
+ * @example
+ * const ref = useRef()
+ * const inView = useIsInView(ref, { triggerOnce: true })
+ *
+ * @param {React.RefObject} targetRef - Ref to the target element
+ * @param {Object} options - Same options as useInView
+ * @returns {boolean} Whether element is in viewport
+ */
+export function useIsInView(targetRef, options = {}) {
+  const {
+    threshold = DEFAULT_OPTIONS.threshold,
+    rootMargin = DEFAULT_OPTIONS.rootMargin,
+    triggerOnce = DEFAULT_OPTIONS.triggerOnce,
+    root = DEFAULT_OPTIONS.root,
+    initialInView = false,
+  } = options
+
+  const [inView, setInView] = useState(initialInView)
+  const hasTriggered = useRef(false)
+
+  useEffect(() => {
+    const element = targetRef.current
+    if (!element) return
+    if (typeof IntersectionObserver === 'undefined') return
+    if (triggerOnce && hasTriggered.current) return
+
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        const isIntersecting = entry.isIntersecting
+        setInView(isIntersecting)
+
+        if (isIntersecting && triggerOnce) {
+          hasTriggered.current = true
+          observer.disconnect()
+        }
+      },
+      { threshold, rootMargin, root }
+    )
+
+    observer.observe(element)
+
+    return () => observer.disconnect()
+  }, [targetRef, threshold, rootMargin, root, triggerOnce])
+
+  return inView
+}
+
+export default useInView

package/src/hooks/useThemeData.js

@@ -0,0 +1,256 @@
+/**
+ * Theme Data Hooks
+ *
+ * Provides access to runtime theme configuration and appearance settings.
+ * These hooks are for accessing theme data from the Uniweb runtime.
+ *
+ * Note: For component styling classes (light/dark/gray themes), use useTheme() instead.
+ *
+ * @example
+ * function ColorPicker() {
+ *   const theme = useThemeData()
+ *   const colors = theme?.getPaletteNames() || []
+ *   return <div>{colors.join(', ')}</div>
+ * }
+ *
+ * @example
+ * function DarkModeToggle() {
+ *   const { scheme, toggle, canToggle } = useAppearance()
+ *   if (!canToggle) return null
+ *   return <button onClick={toggle}>{scheme === 'dark' ? '☀️' : '🌙'}</button>
+ * }
+ */
+
+import { useState, useEffect, useCallback } from 'react'
+import { getUniweb, Theme } from '@uniweb/core'
+
+// Storage key for appearance preference
+const APPEARANCE_STORAGE_KEY = 'uniweb-appearance'
+
+// CSS class for dark scheme
+const DARK_SCHEME_CLASS = 'scheme-dark'
+
+/**
+ * Get the initial scheme from storage or system preference
+ *
+ * @param {Object} appearance - Theme appearance configuration
+ * @returns {string} 'light' or 'dark'
+ */
+function getInitialScheme(appearance) {
+  // Check localStorage first
+  if (typeof localStorage !== 'undefined') {
+    const stored = localStorage.getItem(APPEARANCE_STORAGE_KEY)
+    if (stored === 'light' || stored === 'dark') {
+      return stored
+    }
+  }
+
+  // Check system preference if respectSystemPreference is enabled
+  if (appearance?.respectSystemPreference && typeof window !== 'undefined') {
+    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches
+    if (prefersDark && appearance.schemes?.includes('dark')) {
+      return 'dark'
+    }
+  }
+
+  // Fall back to default
+  const defaultScheme = appearance?.default || 'light'
+  return defaultScheme === 'system' ? 'light' : defaultScheme
+}
+
+/**
+ * Access the full Theme object from the active website.
+ *
+ * Returns the Theme instance which provides methods like:
+ * - getColor(name, shade) - Get a color value
+ * - getPalette(name) - Get all shades for a color
+ * - getContextToken(context, token) - Get semantic token
+ * - getAppearance() - Get appearance configuration
+ *
+ * @returns {Theme|null} Theme instance or null if not available
+ *
+ * @example
+ * const theme = useThemeData()
+ * const primaryColor = theme?.getColor('primary', 500)
+ */
+export function useThemeData() {
+  const uniweb = getUniweb()
+  const website = uniweb?.activeWebsite
+  const themeData = website?.themeData
+
+  if (!themeData) {
+    return null
+  }
+
+  // Return a Theme instance if we have theme data
+  // The website may already have a Theme instance, or we create one
+  if (website.theme instanceof Theme) {
+    return website.theme
+  }
+
+  // Create a new Theme instance from themeData
+  return new Theme(themeData)
+}
+
+/**
+ * Get the current section's color context.
+ *
+ * Note: This requires the component to receive the block prop.
+ * For components that don't have block access, use a default or pass context explicitly.
+ *
+ * @param {Object} block - Block instance (optional)
+ * @returns {string} Context name ('light', 'medium', or 'dark')
+ *
+ * @example
+ * function MyComponent({ block }) {
+ *   const context = useColorContext(block)
+ *   return <div className={`context-${context}`}>...</div>
+ * }
+ */
+export function useColorContext(block) {
+  // Get context from block's theme property
+  const context = block?.themeName || block?.theme || 'light'
+
+  // Validate context name
+  const validContexts = ['light', 'medium', 'dark']
+  if (validContexts.includes(context)) {
+    return context
+  }
+
+  return 'light'
+}
+
+/**
+ * Check and toggle site-wide appearance scheme (light/dark mode).
+ *
+ * This hook manages the site's color scheme preference and provides
+ * utilities for toggling between light and dark modes.
+ *
+ * @returns {Object} Appearance utilities
+ * @property {string} scheme - Current scheme ('light' or 'dark')
+ * @property {Function} setScheme - Set scheme explicitly
+ * @property {Function} toggle - Toggle between light and dark
+ * @property {boolean} canToggle - Whether toggling is enabled
+ * @property {string[]} schemes - Available schemes
+ *
+ * @example
+ * function DarkModeToggle() {
+ *   const { scheme, toggle, canToggle } = useAppearance()
+ *
+ *   if (!canToggle) return null
+ *
+ *   return (
+ *     <button onClick={toggle}>
+ *       {scheme === 'dark' ? 'Switch to Light' : 'Switch to Dark'}
+ *     </button>
+ *   )
+ * }
+ */
+export function useAppearance() {
+  const theme = useThemeData()
+  const appearance = theme?.getAppearance() || { default: 'light', allowToggle: false }
+
+  const [scheme, setSchemeState] = useState(() => getInitialScheme(appearance))
+
+  // Apply scheme to document
+  const applyScheme = useCallback((newScheme) => {
+    if (typeof document !== 'undefined') {
+      const root = document.documentElement
+      if (newScheme === 'dark') {
+        root.classList.add(DARK_SCHEME_CLASS)
+      } else {
+        root.classList.remove(DARK_SCHEME_CLASS)
+      }
+    }
+  }, [])
+
+  // Set scheme with persistence and DOM update
+  const setScheme = useCallback((newScheme) => {
+    if (newScheme !== 'light' && newScheme !== 'dark') {
+      console.warn(`[useAppearance] Invalid scheme: ${newScheme}. Use 'light' or 'dark'.`)
+      return
+    }
+
+    setSchemeState(newScheme)
+    applyScheme(newScheme)
+
+    // Persist to localStorage
+    if (typeof localStorage !== 'undefined') {
+      localStorage.setItem(APPEARANCE_STORAGE_KEY, newScheme)
+    }
+  }, [applyScheme])
+
+  // Toggle between light and dark
+  const toggle = useCallback(() => {
+    const newScheme = scheme === 'light' ? 'dark' : 'light'
+    setScheme(newScheme)
+  }, [scheme, setScheme])
+
+  // Apply initial scheme on mount
+  useEffect(() => {
+    applyScheme(scheme)
+  }, []) // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Listen for system preference changes
+  useEffect(() => {
+    if (!appearance.respectSystemPreference || typeof window === 'undefined') {
+      return
+    }
+
+    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
+
+    const handleChange = (e) => {
+      // Only auto-switch if user hasn't manually set preference
+      const stored = localStorage.getItem(APPEARANCE_STORAGE_KEY)
+      if (!stored) {
+        const newScheme = e.matches ? 'dark' : 'light'
+        if (appearance.schemes?.includes(newScheme)) {
+          setScheme(newScheme)
+        }
+      }
+    }
+
+    mediaQuery.addEventListener('change', handleChange)
+    return () => mediaQuery.removeEventListener('change', handleChange)
+  }, [appearance.respectSystemPreference, appearance.schemes, setScheme])
+
+  return {
+    scheme,
+    setScheme,
+    toggle,
+    canToggle: appearance.allowToggle === true,
+    schemes: appearance.schemes || ['light'],
+  }
+}
+
+/**
+ * Get a specific color from the theme.
+ * Convenience hook that combines useThemeData with getColor.
+ *
+ * @param {string} name - Color name (e.g., 'primary', 'neutral')
+ * @param {number} shade - Shade level (50-950), defaults to 500
+ * @returns {string|null} Color value or null
+ *
+ * @example
+ * const primaryColor = useThemeColor('primary', 600)
+ */
+export function useThemeColor(name, shade = 500) {
+  const theme = useThemeData()
+  return theme?.getColor(name, shade) || null
+}
+
+/**
+ * Get CSS variable reference for a color.
+ * Useful for inline styles that reference theme colors.
+ *
+ * @param {string} name - Color name
+ * @param {number} shade - Shade level
+ * @returns {string} CSS var() reference
+ *
+ * @example
+ * const style = { color: useThemeColorVar('primary', 600) }
+ * // Returns: 'var(--primary-600)'
+ */
+export function useThemeColorVar(name, shade = 500) {
+  return `var(--${name}-${shade})`
+}

package/src/hooks/useVersion.js

@@ -0,0 +1,128 @@
+/**
+ * useVersion Hook
+ *
+ * Hook for version switching in documentation sites.
+ * Provides access to version information and utilities for building
+ * version switcher components.
+ *
+ * @example
+ * function VersionSwitcher() {
+ *   const { isVersioned, currentVersion, versions, getVersionUrl } = useVersion()
+ *
+ *   if (!isVersioned) return null
+ *
+ *   return (
+ *     <select
+ *       value={currentVersion?.id}
+ *       onChange={(e) => navigate(getVersionUrl(e.target.value))}
+ *     >
+ *       {versions.map(v => (
+ *         <option key={v.id} value={v.id}>
+ *           {v.label} {v.latest ? '(latest)' : ''} {v.deprecated ? '(deprecated)' : ''}
+ *         </option>
+ *       ))}
+ *     </select>
+ *   )
+ * }
+ */
+
+import { useRouting } from './useRouting.js'
+import { useWebsite } from './useWebsite.js'
+
+/**
+ * Hook for version information and switching.
+ * Works both at page level (when page has version context) and
+ * at site level (checking versioned scopes).
+ *
+ * @param {Object} options - Optional configuration
+ * @param {Page} options.page - Specific page to check (default: active page)
+ * @returns {Object} Version utilities
+ */
+export function useVersion(options = {}) {
+  const { useLocation } = useRouting()
+  const { website } = useWebsite()
+  const location = useLocation()
+
+  const currentRoute = location?.pathname || '/'
+  const page = options.page || website.activePage
+
+  // Check if the current page/route is within a versioned section
+  const isVersioned = page?.isVersioned() || website.isVersionedRoute(currentRoute)
+
+  // Get version information from page (preferred) or compute from route
+  const currentVersion = page?.getVersion() || null
+  const versionMeta = page?.versionMeta || website.getVersionMeta(website.getVersionScope(currentRoute))
+  const versions = versionMeta?.versions || []
+  const latestVersionId = versionMeta?.latestId || null
+
+  // Find the version scope for the current route
+  const versionScope = page?.versionScope || website.getVersionScope(currentRoute)
+
+  return {
+    /**
+     * Whether the current page is within a versioned section
+     * @type {boolean}
+     */
+    isVersioned,
+
+    /**
+     * Current version info { id, label, latest, deprecated }
+     * @type {Object|null}
+     */
+    currentVersion,
+
+    /**
+     * All available versions for this scope
+     * @type {Array<{id: string, label: string, latest: boolean, deprecated: boolean}>}
+     */
+    versions,
+
+    /**
+     * The ID of the latest version
+     * @type {string|null}
+     */
+    latestVersionId,
+
+    /**
+     * The route where versioning starts (e.g., '/docs')
+     * @type {string|null}
+     */
+    versionScope,
+
+    /**
+     * Check if current version is the latest
+     * @type {boolean}
+     */
+    isLatestVersion: currentVersion?.latest === true,
+
+    /**
+     * Check if current version is deprecated
+     * @type {boolean}
+     */
+    isDeprecatedVersion: currentVersion?.deprecated === true,
+
+    /**
+     * Get URL for switching to a different version
+     * @param {string} targetVersion - Target version ID (e.g., 'v1')
+     * @returns {string|null} Target URL or null if not versioned
+     */
+    getVersionUrl: (targetVersion) => {
+      if (!isVersioned) return null
+      return website.getVersionUrl(targetVersion, currentRoute)
+    },
+
+    /**
+     * Check if site has any versioned content
+     * @type {boolean}
+     */
+    hasVersionedContent: website.hasVersionedContent(),
+
+    /**
+     * Get all versioned scopes in the site
+     * @type {Object} Map of scope → { versions, latestId }
+     */
+    versionedScopes: website.getVersionedScopes(),
+  }
+}
+
+export default useVersion

package/src/index.js

@@ -62,6 +62,7 @@ export {
   useWebsite,
   useRouting,
   useActiveRoute,
+  useVersion,
   useScrolled,
   useMobileMenu,
   useAccordion,
@@ -70,7 +71,16 @@ export {
   useTheme,
   getThemeClasses,
   THEMES,
-  THEME_NAMES
+  THEME_NAMES,
+  // Viewport detection
+  useInView,
+  useIsInView,
+  // Theme data hooks (runtime theme access)
+  useThemeData,
+  useColorContext,
+  useAppearance,
+  useThemeColor,
+  useThemeColorVar
 } from './hooks/index.js'
 
 // ============================================================================
@@ -84,5 +94,8 @@ export {
   stripTags,
   isExternalUrl,
   isFileUrl,
-  detectMediaType
+  detectMediaType,
+  // Locale utilities
+  LOCALE_DISPLAY_NAMES,
+  getLocaleLabel
 } from './utils/index.js'