@uniweb/kit 0.1.9 → 0.1.11

package/package.json

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

package/src/hooks/index.js

@@ -6,3 +6,13 @@ 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/index.js

@@ -70,7 +70,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'
 
 // ============================================================================

package/src/styled/Article/index.jsx

@@ -0,0 +1,79 @@
+/**
+ * Article Component
+ *
+ * Semantic article wrapper with prose typography.
+ * Use for blog posts, news articles, documentation pages, etc.
+ *
+ * @module @uniweb/kit/styled/Article
+ */
+
+import React from 'react'
+import { cn } from '../../utils/index.js'
+import { Render } from '../Section/Render.jsx'
+
+/**
+ * Prose sizes
+ */
+const SIZE_CLASSES = {
+  sm: 'prose-sm',
+  base: 'prose-base',
+  lg: 'prose-lg',
+  xl: 'prose-xl',
+  '2xl': 'prose-2xl'
+}
+
+/**
+ * Article - Semantic article with prose typography
+ *
+ * Renders content inside a semantic <article> tag with prose styling.
+ * Can accept either children or a content prop (ProseMirror JSON).
+ *
+ * @param {Object} props
+ * @param {Object|Array} [props.content] - ProseMirror content to render
+ * @param {string} [props.size='lg'] - Text size: sm, base, lg, xl, 2xl
+ * @param {string} [props.className] - Additional CSS classes
+ * @param {React.ReactNode} [props.children] - Content to render (alternative to content prop)
+ *
+ * @example
+ * // With ProseMirror content
+ * <Article content={articleData.content} />
+ *
+ * @example
+ * // With children
+ * <Article>
+ *   <h1>My Article</h1>
+ *   <p>Article content...</p>
+ * </Article>
+ *
+ * @example
+ * // Composing with Render
+ * <Article size="base" className="dark:prose-invert">
+ *   <Render content={proseMirrorContent} />
+ * </Article>
+ */
+export function Article({
+  content,
+  size = 'lg',
+  className,
+  children,
+  ...props
+}) {
+  const sizeClass = SIZE_CLASSES[size] || SIZE_CLASSES.lg
+
+  // Resolve content - if it's a ProseMirror doc, get the content array
+  let resolvedContent = content
+  if (resolvedContent?.type === 'doc') {
+    resolvedContent = resolvedContent.content
+  }
+
+  return (
+    <article
+      className={cn('prose', sizeClass, 'max-w-none', className)}
+      {...props}
+    >
+      {children || (resolvedContent && <Render content={resolvedContent} />)}
+    </article>
+  )
+}
+
+export default Article

package/src/styled/Asset/Asset.jsx

@@ -8,8 +8,8 @@
 
 import React, { useState, useCallback, forwardRef, useImperativeHandle } from 'react'
 import { cn } from '../../utils/index.js'
-import { FileLogo } from '../FileLogo/index.js'
-import { Image } from '../Image/index.js'
+import { FileLogo } from '../../components/FileLogo/index.js'
+import { Image } from '../../components/Image/index.js'
 import { useWebsite } from '../../hooks/useWebsite.js'
 
 /**

package/src/styled/Prose/index.jsx

@@ -0,0 +1,66 @@
+/**
+ * Prose Component
+ *
+ * Typography wrapper for long-form content.
+ * Applies prose styling for readable text.
+ *
+ * @module @uniweb/kit/styled/Prose
+ */
+
+import React from 'react'
+import { cn } from '../../utils/index.js'
+
+/**
+ * Prose sizes
+ */
+const SIZE_CLASSES = {
+  sm: 'prose-sm',
+  base: 'prose-base',
+  lg: 'prose-lg',
+  xl: 'prose-xl',
+  '2xl': 'prose-2xl'
+}
+
+/**
+ * Prose - Typography wrapper for long-form content
+ *
+ * Applies Tailwind Typography (prose) classes for readable text styling.
+ * Use for article bodies, documentation, or any long-form content.
+ *
+ * @param {Object} props
+ * @param {string} [props.size='lg'] - Text size: sm, base, lg, xl, 2xl
+ * @param {string} [props.as='div'] - HTML element to render as
+ * @param {string} [props.className] - Additional CSS classes
+ * @param {React.ReactNode} props.children - Content to render
+ *
+ * @example
+ * <Prose>
+ *   <h2>Article Title</h2>
+ *   <p>Article content...</p>
+ * </Prose>
+ *
+ * @example
+ * <Prose size="base" className="dark:prose-invert">
+ *   <Render content={proseMirrorContent} />
+ * </Prose>
+ */
+export function Prose({
+  size = 'lg',
+  as: Component = 'div',
+  className,
+  children,
+  ...props
+}) {
+  const sizeClass = SIZE_CLASSES[size] || SIZE_CLASSES.lg
+
+  return (
+    <Component
+      className={cn('prose', sizeClass, 'max-w-none', className)}
+      {...props}
+    >
+      {children}
+    </Component>
+  )
+}
+
+export default Prose

package/src/styled/index.js

@@ -20,9 +20,15 @@ export { SidebarLayout } from './SidebarLayout/index.js'
 // Content Rendering
 // ============================================================================
 
-// Section - Rich content section renderer
+// Section - Rich content section layout container
 export { Section, Render } from './Section/index.js'
 
+// Prose - Typography wrapper for long-form content
+export { Prose } from './Prose/index.jsx'
+
+// Article - Semantic article with prose typography
+export { Article } from './Article/index.jsx'
+
 // Renderers - Individual content type renderers
 export { Code, Alert, Warning, Table, Details, Divider } from './Section/renderers/index.js'