@uniweb/kit 0.1.4 → 0.1.6

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/useRouting.js

@@ -0,0 +1,119 @@
+/**
+ * useRouting Hook
+ *
+ * Provides SSG-safe access to routing functionality.
+ *
+ * The runtime registers routing components (Link, useNavigate, useLocation, useParams)
+ * via the bridge pattern. This hook provides safe access that gracefully handles
+ * SSG/SSR contexts where the Router context isn't available.
+ *
+ * @example
+ * function NavItem({ route }) {
+ *   const { useLocation } = useRouting()
+ *   const location = useLocation()
+ *   const isActive = location.pathname === route
+ *   return <Link to={route} className={isActive ? 'active' : ''}>...</Link>
+ * }
+ */
+
+import { getUniweb } from '@uniweb/core'
+
+/**
+ * Default location object for SSG/SSR contexts
+ */
+const DEFAULT_LOCATION = {
+  pathname: '/',
+  search: '',
+  hash: '',
+  state: null,
+  key: 'default'
+}
+
+/**
+ * Default params object for SSG/SSR contexts
+ */
+const DEFAULT_PARAMS = {}
+
+/**
+ * Get routing utilities with SSG-safe fallbacks
+ * @returns {Object} Routing utilities
+ */
+export function useRouting() {
+  const uniweb = getUniweb()
+  const routing = uniweb?.routingComponents || {}
+
+  return {
+    /**
+     * SSG-safe useLocation hook
+     * Returns current location or defaults during SSG
+     * @returns {Object} Location object { pathname, search, hash, state, key }
+     */
+    useLocation: () => {
+      if (!routing.useLocation) {
+        return DEFAULT_LOCATION
+      }
+      try {
+        return routing.useLocation()
+      } catch {
+        // Router context not available (SSG/SSR)
+        return DEFAULT_LOCATION
+      }
+    },
+
+    /**
+     * SSG-safe useParams hook
+     * Returns route params or empty object during SSG
+     * @returns {Object} Params object
+     */
+    useParams: () => {
+      if (!routing.useParams) {
+        return DEFAULT_PARAMS
+      }
+      try {
+        return routing.useParams()
+      } catch {
+        // Router context not available (SSG/SSR)
+        return DEFAULT_PARAMS
+      }
+    },
+
+    /**
+     * SSG-safe useNavigate hook
+     * Returns navigate function or no-op during SSG
+     * @returns {Function} Navigate function
+     */
+    useNavigate: () => {
+      if (!routing.useNavigate) {
+        return () => {} // No-op during SSG
+      }
+      try {
+        return routing.useNavigate()
+      } catch {
+        // Router context not available (SSG/SSR)
+        return () => {}
+      }
+    },
+
+    /**
+     * Router Link component (or fallback to 'a')
+     * Use Kit's Link component instead for most cases
+     */
+    Link: routing.Link || 'a',
+
+    /**
+     * Check if routing is available (browser with Router context)
+     * @returns {boolean}
+     */
+    isRoutingAvailable: () => {
+      if (!routing.useLocation) return false
+      try {
+        routing.useLocation()
+        return true
+      } catch {
+        return false
+      }
+    }
+  }
+}
+
+export default useRouting

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