@uniweb/kit 0.1.5 → 0.1.7

package/src/hooks/useAccordion.js

@@ -0,0 +1,143 @@
+/**
+ * useAccordion Hook
+ *
+ * Manages expand/collapse state for accordion-style UIs.
+ * Used in FAQ components and collapsible navigation (LeftPanel).
+ *
+ * @example
+ * // Single-select accordion (only one item open at a time)
+ * function FAQ({ items }) {
+ *   const { isOpen, toggle } = useAccordion()
+ *
+ *   return items.map((item, i) => (
+ *     <div key={i}>
+ *       <button onClick={() => toggle(i)}>{item.question}</button>
+ *       {isOpen(i) && <p>{item.answer}</p>}
+ *     </div>
+ *   ))
+ * }
+ *
+ * @example
+ * // Multi-select with first item open
+ * const { isOpen, toggle } = useAccordion({
+ *   multiple: true,
+ *   defaultOpen: [0]
+ * })
+ *
+ * @example
+ * // All items open by default
+ * const { isOpen, toggle, openAll, closeAll } = useAccordion({
+ *   multiple: true,
+ *   defaultOpen: 'all',
+ *   items: faqItems  // needed when using 'all'
+ * })
+ */
+
+import { useState, useCallback } from 'react'
+
+/**
+ * Hook to manage accordion expand/collapse state.
+ *
+ * @param {Object} options - Configuration options
+ * @param {boolean} [options.multiple=false] - Allow multiple items open at once
+ * @param {Array|string} [options.defaultOpen=[]] - Initially open items (indices or 'all')
+ * @param {Array} [options.items] - Items array (needed for defaultOpen: 'all')
+ * @returns {Object} Accordion state and controls
+ */
+export function useAccordion(options = {}) {
+  const {
+    multiple = false,
+    defaultOpen = [],
+    items = [],
+  } = options
+
+  // Compute initial open state
+  const getInitialOpen = () => {
+    if (defaultOpen === 'all' && items.length > 0) {
+      return items.map((_, i) => i)
+    }
+    if (Array.isArray(defaultOpen)) {
+      return defaultOpen
+    }
+    return []
+  }
+
+  const [openItems, setOpenItems] = useState(getInitialOpen)
+
+  /**
+   * Check if an item is open
+   * @param {number|string} id - Item identifier (index or key)
+   * @returns {boolean}
+   */
+  const isOpen = useCallback((id) => {
+    return openItems.includes(id)
+  }, [openItems])
+
+  /**
+   * Toggle an item open/closed
+   * @param {number|string} id - Item identifier
+   */
+  const toggle = useCallback((id) => {
+    setOpenItems(prev => {
+      if (prev.includes(id)) {
+        // Close this item
+        return prev.filter(item => item !== id)
+      }
+      if (multiple) {
+        // Add to open items
+        return [...prev, id]
+      }
+      // Single select: replace open item
+      return [id]
+    })
+  }, [multiple])
+
+  /**
+   * Open a specific item
+   * @param {number|string} id - Item identifier
+   */
+  const open = useCallback((id) => {
+    setOpenItems(prev => {
+      if (prev.includes(id)) return prev
+      if (multiple) return [...prev, id]
+      return [id]
+    })
+  }, [multiple])
+
+  /**
+   * Close a specific item
+   * @param {number|string} id - Item identifier
+   */
+  const close = useCallback((id) => {
+    setOpenItems(prev => prev.filter(item => item !== id))
+  }, [])
+
+  /**
+   * Open all items (only works in multiple mode)
+   * @param {Array} allIds - All item identifiers
+   */
+  const openAll = useCallback((allIds) => {
+    if (multiple && Array.isArray(allIds)) {
+      setOpenItems(allIds)
+    }
+  }, [multiple])
+
+  /**
+   * Close all items
+   */
+  const closeAll = useCallback(() => {
+    setOpenItems([])
+  }, [])
+
+  return {
+    openItems,
+    isOpen,
+    toggle,
+    open,
+    close,
+    openAll,
+    closeAll,
+  }
+}
+
+export default useAccordion

package/src/hooks/useActiveRoute.js

@@ -0,0 +1,97 @@
+/**
+ * useActiveRoute Hook
+ *
+ * SSG-safe hook for active route detection in navigation components.
+ * Provides utilities for checking if pages are active or ancestors of the current route.
+ *
+ * @example
+ * function NavItem({ page }) {
+ *   const { isActiveOrAncestor } = useActiveRoute()
+ *
+ *   return (
+ *     <Link
+ *       href={page.getNavigableRoute()}
+ *       className={isActiveOrAncestor(page) ? 'active' : ''}
+ *     >
+ *       {page.label}
+ *     </Link>
+ *   )
+ * }
+ */
+
+import { useRouting } from './useRouting.js'
+
+/**
+ * Normalize a route by removing leading/trailing slashes
+ * @param {string} route
+ * @returns {string}
+ */
+function normalizeRoute(route) {
+  return (route || '').replace(/^\//, '').replace(/\/$/, '')
+}
+
+/**
+ * Hook for active route detection with SSG-safe fallbacks.
+ *
+ * @returns {Object} Route utilities
+ * @property {string} route - Current normalized route (e.g., 'docs/getting-started')
+ * @property {string} rootSegment - First segment of route (e.g., 'docs')
+ * @property {function} isActive - Check if a page is the current page
+ * @property {function} isActiveOrAncestor - Check if a page or its descendants are active
+ */
+export function useActiveRoute() {
+  const { useLocation } = useRouting()
+  const location = useLocation()
+
+  const route = normalizeRoute(location?.pathname)
+  const rootSegment = route.split('/')[0]
+
+  return {
+    /**
+     * Current normalized route (no leading/trailing slashes)
+     * @type {string}
+     */
+    route,
+
+    /**
+     * First segment of the current route
+     * Useful for root-level navigation highlighting
+     * @type {string}
+     */
+    rootSegment,
+
+    /**
+     * Check if a page is the current active page (exact match)
+     *
+     * @param {Object} page - Page object with getNormalizedRoute() or route property
+     * @returns {boolean}
+     */
+    isActive: (page) => {
+      if (typeof page.getNormalizedRoute === 'function') {
+        return page.getNormalizedRoute() === route
+      }
+      // Fallback for page info objects from getPageHierarchy
+      return normalizeRoute(page.route) === route
+    },
+
+    /**
+     * Check if a page or any of its descendants is active
+     * Useful for highlighting parent nav items when child is active
+     *
+     * @param {Object} page - Page object with isActiveOrAncestor() or route property
+     * @returns {boolean}
+     */
+    isActiveOrAncestor: (page) => {
+      if (typeof page.isActiveOrAncestor === 'function') {
+        return page.isActiveOrAncestor(route)
+      }
+      // Fallback for page info objects from getPageHierarchy
+      const pageRoute = normalizeRoute(page.route)
+      if (pageRoute === route) return true
+      if (pageRoute === '') return true // Root is ancestor of all
+      return route.startsWith(pageRoute + '/')
+    },
+  }
+}
+
+export default useActiveRoute

package/src/hooks/useGridLayout.js

@@ -0,0 +1,71 @@
+/**
+ * useGridLayout Hook
+ *
+ * Returns Tailwind CSS classes for responsive grid layouts.
+ * Standardizes the grid column patterns used across components.
+ *
+ * @example
+ * function Features({ items, params }) {
+ *   const gridClass = useGridLayout(params.columns)
+ *
+ *   return (
+ *     <div className={gridClass}>
+ *       {items.map(item => <FeatureCard key={item.id} {...item} />)}
+ *     </div>
+ *   )
+ * }
+ *
+ * @example
+ * // With custom gap
+ * const gridClass = useGridLayout(3, { gap: 12 })
+ * // Returns: "grid gap-12 sm:grid-cols-2 lg:grid-cols-3"
+ */
+
+/**
+ * Standard responsive grid column configurations.
+ * Keys are column counts, values are Tailwind classes.
+ */
+const GRID_CONFIGS = {
+  1: '',
+  2: 'sm:grid-cols-2',
+  3: 'sm:grid-cols-2 lg:grid-cols-3',
+  4: 'sm:grid-cols-2 lg:grid-cols-4',
+  5: 'sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-5',
+  6: 'sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-6',
+}
+
+/**
+ * Hook to generate responsive grid layout classes.
+ *
+ * @param {number} columns - Number of columns (1-6)
+ * @param {Object} options - Configuration options
+ * @param {number} [options.gap=8] - Gap size (Tailwind scale: 4, 6, 8, 10, 12)
+ * @param {string} [options.baseClass='grid'] - Base class to include
+ * @returns {string} Tailwind CSS classes for the grid
+ */
+export function useGridLayout(columns = 3, options = {}) {
+  const {
+    gap = 8,
+    baseClass = 'grid',
+  } = options
+
+  const colConfig = GRID_CONFIGS[columns] || GRID_CONFIGS[3]
+  const gapClass = `gap-${gap}`
+
+  return [baseClass, gapClass, colConfig].filter(Boolean).join(' ')
+}
+
+/**
+ * Get grid classes without the hook (for non-React contexts)
+ * @param {number} columns
+ * @param {Object} options
+ * @returns {string}
+ */
+export function getGridClasses(columns = 3, options = {}) {
+  const { gap = 8, baseClass = 'grid' } = options
+  const colConfig = GRID_CONFIGS[columns] || GRID_CONFIGS[3]
+  const gapClass = `gap-${gap}`
+  return [baseClass, gapClass, colConfig].filter(Boolean).join(' ')
+}
+
+export default useGridLayout

package/src/hooks/useMobileMenu.js

@@ -0,0 +1,58 @@
+/**
+ * useMobileMenu Hook
+ *
+ * Manages mobile menu state with automatic close on route change.
+ * Common pattern in Header/Navbar components across all templates.
+ *
+ * @example
+ * function Header() {
+ *   const { isOpen, toggle, close } = useMobileMenu()
+ *
+ *   return (
+ *     <>
+ *       <button onClick={toggle}>Menu</button>
+ *       {isOpen && (
+ *         <nav>
+ *           <Link href="/about" onClick={close}>About</Link>
+ *         </nav>
+ *       )}
+ *     </>
+ *   )
+ * }
+ */
+
+import { useState, useEffect, useCallback } from 'react'
+import { useActiveRoute } from './useActiveRoute.js'
+
+/**
+ * Hook to manage mobile menu state.
+ * Automatically closes menu on route change.
+ *
+ * @returns {Object} Menu state and controls
+ * @property {boolean} isOpen - Whether menu is open
+ * @property {function} open - Open the menu
+ * @property {function} close - Close the menu
+ * @property {function} toggle - Toggle menu open/closed
+ */
+export function useMobileMenu() {
+  const [isOpen, setIsOpen] = useState(false)
+  const { route } = useActiveRoute()
+
+  // Close menu on route change
+  useEffect(() => {
+    setIsOpen(false)
+  }, [route])
+
+  const open = useCallback(() => setIsOpen(true), [])
+  const close = useCallback(() => setIsOpen(false), [])
+  const toggle = useCallback(() => setIsOpen(prev => !prev), [])
+
+  return {
+    isOpen,
+    open,
+    close,
+    toggle,
+  }
+}
+
+export default useMobileMenu

package/src/hooks/useScrolled.js

@@ -0,0 +1,48 @@
+/**
+ * useScrolled Hook
+ *
+ * Detects scroll position for sticky header effects.
+ * Common pattern in Header components across all templates.
+ *
+ * @example
+ * function Header() {
+ *   const scrolled = useScrolled()
+ *   return (
+ *     <header className={scrolled ? 'bg-white shadow' : 'bg-transparent'}>
+ *       ...
+ *     </header>
+ *   )
+ * }
+ *
+ * @example
+ * // With custom threshold
+ * const scrolled = useScrolled(50) // triggers after 50px scroll
+ */
+
+import { useState, useEffect } from 'react'
+
+/**
+ * Hook to detect if page has scrolled past a threshold.
+ *
+ * @param {number} threshold - Scroll position threshold in pixels (default: 0)
+ * @returns {boolean} Whether scroll position is past threshold
+ */
+export function useScrolled(threshold = 0) {
+  const [scrolled, setScrolled] = useState(false)
+
+  useEffect(() => {
+    const handleScroll = () => {
+      setScrolled(window.scrollY > threshold)
+    }
+
+    // Check initial state
+    handleScroll()
+
+    window.addEventListener('scroll', handleScroll, { passive: true })
+    return () => window.removeEventListener('scroll', handleScroll)
+  }, [threshold])
+
+  return scrolled
+}
+
+export default useScrolled

package/src/hooks/useTheme.js

@@ -0,0 +1,205 @@
+/**
+ * useTheme Hook
+ *
+ * Provides standardized theme classes for components.
+ * Eliminates duplicated theme objects across 25+ components.
+ *
+ * @example
+ * function Hero({ params }) {
+ *   const t = useTheme(params.theme)
+ *
+ *   return (
+ *     <section className={t.section}>
+ *       <h1 className={t.title}>...</h1>
+ *       <p className={t.body}>...</p>
+ *     </section>
+ *   )
+ * }
+ *
+ * @example
+ * // With custom overrides
+ * const t = useTheme('dark', {
+ *   card: 'bg-gray-800 rounded-xl',
+ *   cardHover: 'hover:bg-gray-700'
+ * })
+ */
+
+/**
+ * Standard theme definitions.
+ * Keys are standardized across all components.
+ */
+const THEMES = {
+  light: {
+    // Section backgrounds
+    section: 'bg-white',
+    sectionAlt: 'bg-gray-50',
+
+    // Typography
+    title: 'text-gray-900',
+    subtitle: 'text-gray-700',
+    pretitle: 'text-primary',
+    body: 'text-gray-600',
+    muted: 'text-gray-500',
+
+    // Cards
+    card: 'bg-gray-50',
+    cardHover: 'hover:shadow-lg',
+    cardBorder: 'border border-gray-200',
+
+    // Interactive
+    link: 'text-primary hover:text-primary-dark',
+    linkMuted: 'text-gray-600 hover:text-gray-900',
+
+    // Borders & Dividers
+    border: 'border-gray-200',
+    divider: 'bg-gray-200',
+  },
+
+  gray: {
+    section: 'bg-gray-50',
+    sectionAlt: 'bg-gray-100',
+
+    title: 'text-gray-900',
+    subtitle: 'text-gray-700',
+    pretitle: 'text-primary',
+    body: 'text-gray-600',
+    muted: 'text-gray-500',
+
+    card: 'bg-white shadow-sm',
+    cardHover: 'hover:shadow-lg',
+    cardBorder: 'border border-gray-200',
+
+    link: 'text-primary hover:text-primary-dark',
+    linkMuted: 'text-gray-600 hover:text-gray-900',
+
+    border: 'border-gray-200',
+    divider: 'bg-gray-300',
+  },
+
+  dark: {
+    section: 'bg-gray-900',
+    sectionAlt: 'bg-gray-800',
+
+    title: 'text-white',
+    subtitle: 'text-gray-300',
+    pretitle: 'text-primary',
+    body: 'text-gray-400',
+    muted: 'text-gray-500',
+
+    card: 'bg-gray-800',
+    cardHover: 'hover:bg-gray-750',
+    cardBorder: 'border border-gray-700',
+
+    link: 'text-primary hover:text-primary-light',
+    linkMuted: 'text-gray-400 hover:text-white',
+
+    border: 'border-gray-700',
+    divider: 'bg-gray-700',
+  },
+
+  primary: {
+    section: 'bg-primary',
+    sectionAlt: 'bg-primary-dark',
+
+    title: 'text-white',
+    subtitle: 'text-white/90',
+    pretitle: 'text-white/80',
+    body: 'text-white/80',
+    muted: 'text-white/60',
+
+    card: 'bg-white/10',
+    cardHover: 'hover:bg-white/20',
+    cardBorder: 'border border-white/20',
+
+    link: 'text-white hover:text-white/80',
+    linkMuted: 'text-white/70 hover:text-white',
+
+    border: 'border-white/20',
+    divider: 'bg-white/20',
+  },
+
+  gradient: {
+    section: 'bg-gradient-to-br from-primary to-indigo-600',
+    sectionAlt: 'bg-gradient-to-br from-primary-dark to-indigo-700',
+
+    title: 'text-white',
+    subtitle: 'text-white/90',
+    pretitle: 'text-white/80',
+    body: 'text-white/80',
+    muted: 'text-white/60',
+
+    card: 'bg-white/10 backdrop-blur-sm',
+    cardHover: 'hover:bg-white/20',
+    cardBorder: 'border border-white/20',
+
+    link: 'text-white hover:text-white/80',
+    linkMuted: 'text-white/70 hover:text-white',
+
+    border: 'border-white/20',
+    divider: 'bg-white/20',
+  },
+
+  glass: {
+    section: 'bg-white/10 backdrop-blur-lg',
+    sectionAlt: 'bg-white/5 backdrop-blur-lg',
+
+    title: 'text-white',
+    subtitle: 'text-white/90',
+    pretitle: 'text-primary',
+    body: 'text-white/80',
+    muted: 'text-white/60',
+
+    card: 'bg-white/10 backdrop-blur-sm',
+    cardHover: 'hover:bg-white/20',
+    cardBorder: 'border border-white/20',
+
+    link: 'text-white hover:text-primary',
+    linkMuted: 'text-white/70 hover:text-white',
+
+    border: 'border-white/20',
+    divider: 'bg-white/20',
+  },
+}
+
+/**
+ * Hook to get theme classes by name.
+ *
+ * @param {string} themeName - Theme name (light, gray, dark, primary, gradient, glass)
+ * @param {Object} overrides - Custom class overrides
+ * @returns {Object} Theme classes object
+ */
+export function useTheme(themeName = 'light', overrides = {}) {
+  const baseTheme = THEMES[themeName] || THEMES.light
+
+  if (Object.keys(overrides).length === 0) {
+    return baseTheme
+  }
+
+  return {
+    ...baseTheme,
+    ...overrides,
+  }
+}
+
+/**
+ * Get theme classes without the hook (for non-React contexts)
+ * @param {string} themeName
+ * @param {Object} overrides
+ * @returns {Object}
+ */
+export function getThemeClasses(themeName = 'light', overrides = {}) {
+  const baseTheme = THEMES[themeName] || THEMES.light
+  return { ...baseTheme, ...overrides }
+}
+
+/**
+ * All available theme names
+ */
+export const THEME_NAMES = Object.keys(THEMES)
+
+/**
+ * Export theme definitions for customization
+ */
+export { THEMES }
+
+export default useTheme

package/src/index.js

@@ -3,6 +3,9 @@
  *
  * Standard component library for Uniweb foundations.
  *
+ * For pre-styled components (Section, SidebarLayout, Disclaimer, etc.),
+ * import from '@uniweb/kit/styled'.
+ *
  * @example
  * import { Link, Image, useWebsite } from '@uniweb/kit'
  *
@@ -18,10 +21,10 @@
  */
 
 // ============================================================================
-// Components
+// Components (Primitives - no Tailwind dependency)
 // ============================================================================
 
-// Primitives
+// Navigation
 export { Link } from './components/Link/index.js'
 export { Image } from './components/Image/index.js'
 export { SafeHtml } from './components/SafeHtml/index.js'
@@ -35,24 +38,40 @@ export {
   PlainText
 } from './components/Text/index.js'
 
-// Media
+// Media (plain version - for styled facade, use @uniweb/kit/tailwind)
 export { Media } from './components/Media/index.js'
 export { FileLogo } from './components/FileLogo/index.js'
 export { MediaIcon } from './components/MediaIcon/index.js'
 
-// Content
-export { Section, Render } from './components/Section/index.js'
-export { Code, Alert, Warning, Table, Details, Divider } from './components/Section/renderers/index.js'
-
-// Utilities
+// Files (plain version - for styled card, use @uniweb/kit/tailwind)
 export { Asset } from './components/Asset/index.js'
-export { Disclaimer } from './components/Disclaimer/index.js'
+
+// Social
+export {
+  SocialIcon,
+  getSocialPlatform,
+  isSocialLink,
+  filterSocialLinks
+} from './components/SocialIcon/index.jsx'
 
 // ============================================================================
 // Hooks
 // ============================================================================
 
-export { useWebsite, useRouting } from './hooks/index.js'
+export {
+  useWebsite,
+  useRouting,
+  useActiveRoute,
+  useScrolled,
+  useMobileMenu,
+  useAccordion,
+  useGridLayout,
+  getGridClasses,
+  useTheme,
+  getThemeClasses,
+  THEMES,
+  THEME_NAMES
+} from './hooks/index.js'
 
 // ============================================================================
 // Utilities