@uniweb/kit 0.1.3 → 0.1.4

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Standard component library for Uniweb foundations",
   "type": "module",
   "exports": {
     ".": "./src/index.js",
-    "./styles": "./src/styles/index.css"
+    "./styles": "./src/styles/index.css",
+    "./search": "./src/search/index.js"
   },
   "files": [
     "src",
@@ -35,11 +36,17 @@
   },
   "dependencies": {
     "tailwind-merge": "^2.6.0",
-    "@uniweb/core": "0.1.5"
+    "@uniweb/core": "0.1.6"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0"
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "fuse.js": "^7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "fuse.js": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "tailwindcss": "^3.4.0"

package/src/search/client.js

@@ -0,0 +1,325 @@
+/**
+ * Search Client
+ *
+ * Manages search index loading, caching, and querying using Fuse.js.
+ */
+
+import { buildSnippet } from './snippets.js'
+
+// Storage versioning for cache invalidation
+const STORAGE_VERSION = 'v1'
+const STORAGE_PREFIX = `uniweb:search:${STORAGE_VERSION}:`
+
+// In-memory caches
+const indexCache = new Map()
+const fuseCache = new Map()
+
+/**
+ * Default Fuse.js options optimized for site search
+ */
+const DEFAULT_FUSE_OPTIONS = {
+  keys: [
+    { name: 'title', weight: 0.6 },
+    { name: 'content', weight: 0.4 },
+    { name: 'excerpt', weight: 0.3 },
+    { name: 'pageTitle', weight: 0.2 }
+  ],
+  threshold: 0.35,
+  includeMatches: true,
+  ignoreLocation: true,
+  minMatchCharLength: 2
+}
+
+/**
+ * Get localStorage safely (handles SSR and access errors)
+ * @returns {Storage|null}
+ */
+function getStorage() {
+  if (typeof window === 'undefined') return null
+  try {
+    return window.localStorage
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Load index from localStorage
+ * @param {string} cacheKey - Cache key
+ * @returns {Object|null}
+ */
+function loadFromStorage(cacheKey) {
+  const storage = getStorage()
+  if (!storage) return null
+
+  const raw = storage.getItem(`${STORAGE_PREFIX}${cacheKey}`)
+  if (!raw) return null
+
+  try {
+    const parsed = JSON.parse(raw)
+    if (Array.isArray(parsed.entries)) {
+      return parsed
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Save index to localStorage
+ * @param {string} cacheKey - Cache key
+ * @param {Object} payload - Index data
+ */
+function saveToStorage(cacheKey, payload) {
+  const storage = getStorage()
+  if (!storage) return
+
+  try {
+    storage.setItem(`${STORAGE_PREFIX}${cacheKey}`, JSON.stringify(payload))
+  } catch {
+    // Ignore quota errors
+  }
+}
+
+/**
+ * Load search index for a locale
+ * @param {string} indexUrl - URL to fetch the index from
+ * @param {Object} options - Options
+ * @param {string} [options.cacheKey] - Cache key (defaults to indexUrl)
+ * @param {boolean} [options.useStorage=true] - Use localStorage caching
+ * @returns {Promise<Object>} Search index
+ */
+export async function loadSearchIndex(indexUrl, options = {}) {
+  const { cacheKey = indexUrl, useStorage = true } = options
+
+  // Check memory cache first
+  if (indexCache.has(cacheKey)) {
+    return indexCache.get(cacheKey)
+  }
+
+  // Check localStorage cache
+  if (useStorage) {
+    const cached = loadFromStorage(cacheKey)
+    if (cached) {
+      indexCache.set(cacheKey, cached)
+      return cached
+    }
+  }
+
+  // Fetch from server
+  const response = await fetch(indexUrl, { cache: 'force-cache' })
+  if (!response.ok) {
+    throw new Error(`Failed to load search index: ${response.status}`)
+  }
+
+  const payload = await response.json()
+
+  // Cache the result
+  indexCache.set(cacheKey, payload)
+  if (useStorage) {
+    saveToStorage(cacheKey, payload)
+  }
+
+  return payload
+}
+
+/**
+ * Clear all search caches
+ * @param {string} [cacheKey] - Specific cache key to clear, or all if omitted
+ */
+export function clearSearchCache(cacheKey) {
+  if (cacheKey) {
+    indexCache.delete(cacheKey)
+    fuseCache.delete(cacheKey)
+    const storage = getStorage()
+    if (storage) {
+      storage.removeItem(`${STORAGE_PREFIX}${cacheKey}`)
+    }
+  } else {
+    indexCache.clear()
+    fuseCache.clear()
+    const storage = getStorage()
+    if (storage) {
+      // Clear all search-related storage
+      const keysToRemove = []
+      for (let i = 0; i < storage.length; i++) {
+        const key = storage.key(i)
+        if (key?.startsWith(STORAGE_PREFIX)) {
+          keysToRemove.push(key)
+        }
+      }
+      keysToRemove.forEach(key => storage.removeItem(key))
+    }
+  }
+}
+
+/**
+ * Create a search client for a Website instance
+ *
+ * @param {Object} website - Website instance from @uniweb/core
+ * @param {Object} options - Configuration options
+ * @param {Object} [options.fuseOptions] - Custom Fuse.js options
+ * @param {boolean} [options.useStorage=true] - Use localStorage caching
+ * @param {number} [options.defaultLimit=10] - Default result limit
+ * @returns {Object} Search client with query method
+ *
+ * @example
+ * const search = createSearchClient(website)
+ * const results = await search.query('authentication')
+ */
+export function createSearchClient(website, options = {}) {
+  const {
+    fuseOptions = {},
+    useStorage = true,
+    defaultLimit = 10
+  } = options
+
+  const mergedFuseOptions = { ...DEFAULT_FUSE_OPTIONS, ...fuseOptions }
+
+  /**
+   * Get or create Fuse instance for the current locale
+   * @returns {Promise<Fuse>}
+   */
+  async function getFuse() {
+    const indexUrl = website.getSearchIndexUrl()
+    const cacheKey = indexUrl
+
+    // Check Fuse cache
+    if (fuseCache.has(cacheKey)) {
+      return fuseCache.get(cacheKey)
+    }
+
+    // Load index and create Fuse instance
+    const index = await loadSearchIndex(indexUrl, { cacheKey, useStorage })
+
+    // Dynamically import Fuse.js (peer dependency)
+    let Fuse
+    try {
+      const fuseMod = await import('fuse.js')
+      Fuse = fuseMod.default || fuseMod
+    } catch (err) {
+      throw new Error(
+        'Fuse.js is required for search functionality. ' +
+        'Install it with: npm install fuse.js'
+      )
+    }
+
+    const fuse = new Fuse(index.entries || [], mergedFuseOptions)
+    fuseCache.set(cacheKey, fuse)
+
+    return fuse
+  }
+
+  return {
+    /**
+     * Check if search is enabled
+     * @returns {boolean}
+     */
+    isEnabled() {
+      return website.isSearchEnabled()
+    },
+
+    /**
+     * Get the search index URL
+     * @returns {string}
+     */
+    getIndexUrl() {
+      return website.getSearchIndexUrl()
+    },
+
+    /**
+     * Get search configuration
+     * @returns {Object}
+     */
+    getConfig() {
+      return website.getSearchConfig()
+    },
+
+    /**
+     * Perform a search query
+     *
+     * @param {string} query - Search query
+     * @param {Object} queryOptions - Query options
+     * @param {number} [queryOptions.limit] - Maximum results
+     * @param {string} [queryOptions.type] - Filter by type ('page' or 'section')
+     * @param {string} [queryOptions.route] - Filter by route prefix
+     * @returns {Promise<Array>} Search results
+     */
+    async query(query, queryOptions = {}) {
+      const { limit = defaultLimit, type, route } = queryOptions
+
+      const trimmed = query?.trim()
+      if (!trimmed) return []
+
+      if (!website.isSearchEnabled()) {
+        console.warn('Search is not enabled for this site')
+        return []
+      }
+
+      const fuse = await getFuse()
+      let results = fuse.search(trimmed)
+
+      // Apply type filter
+      if (type) {
+        results = results.filter(({ item }) => item.type === type)
+      }
+
+      // Apply route filter
+      if (route) {
+        results = results.filter(({ item }) => item.route?.startsWith(route))
+      }
+
+      // Apply limit
+      const limited = results.slice(0, limit)
+
+      // Transform results
+      return limited.map(({ item, matches }) => {
+        const snippet = buildSnippet(item.content, matches, { key: 'content' })
+
+        return {
+          // Identity
+          id: item.id,
+          type: item.type,
+
+          // Navigation
+          route: item.route,
+          sectionId: item.sectionId,
+          anchor: item.anchor,
+          href: item.anchor ? `${item.route}#${item.anchor}` : item.route,
+
+          // Display
+          title: item.title,
+          pageTitle: item.pageTitle,
+          description: item.description,
+          excerpt: item.excerpt,
+          component: item.component,
+
+          // Search result specific
+          snippetText: snippet.text,
+          snippetHtml: snippet.html,
+          matches
+        }
+      })
+    },
+
+    /**
+     * Preload the search index (call this to warm the cache)
+     * @returns {Promise<void>}
+     */
+    async preload() {
+      if (!website.isSearchEnabled()) return
+      await getFuse()
+    },
+
+    /**
+     * Clear the search cache
+     */
+    clearCache() {
+      const indexUrl = website.getSearchIndexUrl()
+      clearSearchCache(indexUrl)
+    }
+  }
+}
+
+export default createSearchClient

package/src/search/hooks.js

@@ -0,0 +1,239 @@
+/**
+ * React Hooks for Search
+ *
+ * Provides hooks for easily integrating search into React components.
+ */
+
+import { useState, useEffect, useCallback, useMemo, useRef } from 'react'
+import { createSearchClient, loadSearchIndex } from './client.js'
+
+/**
+ * Hook to create and use a search client
+ *
+ * @param {Object} website - Website instance from @uniweb/core
+ * @param {Object} options - Options passed to createSearchClient
+ * @returns {Object} Search state and methods
+ *
+ * @example
+ * function SearchComponent() {
+ *   const { query, results, isLoading, error } = useSearch(website)
+ *
+ *   return (
+ *     <div>
+ *       <input onChange={e => query(e.target.value)} />
+ *       {isLoading && <span>Searching...</span>}
+ *       {results.map(r => <SearchResult key={r.id} result={r} />)}
+ *     </div>
+ *   )
+ * }
+ */
+export function useSearch(website, options = {}) {
+  const { debounceMs = 150, ...clientOptions } = options
+
+  const [results, setResults] = useState([])
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState(null)
+  const [lastQuery, setLastQuery] = useState('')
+
+  // Create search client (memoized)
+  const client = useMemo(() => {
+    if (!website) return null
+    return createSearchClient(website, clientOptions)
+  }, [website]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Track pending search for debounce/cancellation
+  const pendingRef = useRef(null)
+  const timeoutRef = useRef(null)
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current)
+      }
+    }
+  }, [])
+
+  /**
+   * Execute a search query
+   */
+  const query = useCallback(async (searchQuery, queryOptions = {}) => {
+    const trimmed = searchQuery?.trim() || ''
+    setLastQuery(trimmed)
+
+    // Clear pending timeout
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current)
+      timeoutRef.current = null
+    }
+
+    // Empty query - clear results immediately
+    if (!trimmed) {
+      setResults([])
+      setIsLoading(false)
+      setError(null)
+      return []
+    }
+
+    // Check if search is enabled
+    if (!client?.isEnabled()) {
+      setError(new Error('Search is not enabled'))
+      return []
+    }
+
+    // Mark this search as pending
+    const searchId = Symbol('search')
+    pendingRef.current = searchId
+
+    // Debounce the actual search
+    return new Promise((resolve) => {
+      timeoutRef.current = setTimeout(async () => {
+        // Skip if a newer search was started
+        if (pendingRef.current !== searchId) {
+          resolve([])
+          return
+        }
+
+        setIsLoading(true)
+        setError(null)
+
+        try {
+          const searchResults = await client.query(trimmed, queryOptions)
+
+          // Skip if a newer search was started
+          if (pendingRef.current !== searchId) {
+            resolve([])
+            return
+          }
+
+          setResults(searchResults)
+          setIsLoading(false)
+          resolve(searchResults)
+        } catch (err) {
+          // Skip if a newer search was started
+          if (pendingRef.current !== searchId) {
+            resolve([])
+            return
+          }
+
+          setError(err)
+          setResults([])
+          setIsLoading(false)
+          resolve([])
+        }
+      }, debounceMs)
+    })
+  }, [client, debounceMs])
+
+  /**
+   * Clear search results
+   */
+  const clear = useCallback(() => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current)
+      timeoutRef.current = null
+    }
+    pendingRef.current = null
+    setResults([])
+    setLastQuery('')
+    setError(null)
+    setIsLoading(false)
+  }, [])
+
+  /**
+   * Preload the search index
+   */
+  const preload = useCallback(async () => {
+    if (!client) return
+    try {
+      await client.preload()
+    } catch (err) {
+      console.warn('Failed to preload search index:', err)
+    }
+  }, [client])
+
+  return {
+    // State
+    results,
+    isLoading,
+    error,
+    lastQuery,
+    isEnabled: client?.isEnabled() ?? false,
+
+    // Actions
+    query,
+    clear,
+    preload,
+
+    // Client access (for advanced use)
+    client
+  }
+}
+
+/**
+ * Hook to load and access the raw search index
+ *
+ * Useful for custom search implementations or displaying index stats.
+ *
+ * @param {Object} website - Website instance
+ * @param {Object} options - Options
+ * @param {boolean} [options.autoLoad=true] - Automatically load on mount
+ * @returns {Object} Index state and methods
+ *
+ * @example
+ * function SearchStats() {
+ *   const { index, isLoading } = useSearchIndex(website)
+ *
+ *   if (isLoading) return <span>Loading...</span>
+ *   return <span>{index?.count || 0} searchable items</span>
+ * }
+ */
+export function useSearchIndex(website, options = {}) {
+  const { autoLoad = true } = options
+
+  const [index, setIndex] = useState(null)
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState(null)
+
+  const load = useCallback(async () => {
+    if (!website?.isSearchEnabled()) {
+      setError(new Error('Search is not enabled'))
+      return null
+    }
+
+    setIsLoading(true)
+    setError(null)
+
+    try {
+      const indexUrl = website.getSearchIndexUrl()
+      const data = await loadSearchIndex(indexUrl)
+      setIndex(data)
+      setIsLoading(false)
+      return data
+    } catch (err) {
+      setError(err)
+      setIsLoading(false)
+      return null
+    }
+  }, [website])
+
+  // Auto-load on mount if enabled
+  useEffect(() => {
+    if (autoLoad && website?.isSearchEnabled()) {
+      load()
+    }
+  }, [autoLoad, website, load])
+
+  return {
+    index,
+    isLoading,
+    error,
+    isEnabled: website?.isSearchEnabled() ?? false,
+    load,
+    entries: index?.entries || [],
+    count: index?.count || 0,
+    locale: index?.locale || null
+  }
+}
+
+export default useSearch

package/src/search/index.js

@@ -0,0 +1,26 @@
+/**
+ * Search Utilities for Uniweb Foundations
+ *
+ * Provides helpers for implementing search functionality in foundations.
+ * Uses Fuse.js for fuzzy search (peer dependency - must be installed by foundation).
+ *
+ * @module @uniweb/kit/search
+ *
+ * @example
+ * import { createSearchClient, buildSnippet } from '@uniweb/kit/search'
+ *
+ * // Create a search client for your site
+ * const search = createSearchClient(website)
+ *
+ * // Perform a search
+ * const results = await search.query('hello world')
+ *
+ * // Results include highlighted snippets
+ * results.forEach(r => {
+ *   console.log(r.title, r.snippetHtml)
+ * })
+ */
+
+export { createSearchClient, loadSearchIndex, clearSearchCache } from './client.js'
+export { buildSnippet, highlightMatches, escapeHtml } from './snippets.js'
+export { useSearch, useSearchIndex } from './hooks.js'

package/src/search/snippets.js

@@ -0,0 +1,191 @@
+/**
+ * Snippet and Highlighting Utilities
+ *
+ * Functions for generating search result snippets with highlighted matches.
+ */
+
+/**
+ * Escape HTML special characters
+ * @param {string} str - String to escape
+ * @returns {string} Escaped string
+ */
+export function escapeHtml(str) {
+  if (!str) return ''
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
+/**
+ * Build a snippet from content with optional match highlighting
+ *
+ * @param {string} text - Full text content
+ * @param {Array} matches - Fuse.js matches array
+ * @param {Object} options - Options
+ * @param {string} [options.key='content'] - Key to find matches for
+ * @param {number} [options.maxLength=160] - Maximum snippet length
+ * @param {number} [options.contextChars=60] - Characters before/after match
+ * @param {string} [options.highlightTag='mark'] - HTML tag for highlights
+ * @returns {{ text: string, html: string }} Plain text and HTML snippets
+ *
+ * @example
+ * const snippet = buildSnippet(
+ *   'This is a long text about authentication and security.',
+ *   matches,
+ *   { key: 'content' }
+ * )
+ * // snippet.html contains '<mark>authentication</mark>' highlighted
+ */
+export function buildSnippet(text, matches, options = {}) {
+  const {
+    key = 'content',
+    maxLength = 160,
+    contextChars = 60,
+    highlightTag = 'mark'
+  } = options
+
+  if (!text) {
+    return { text: '', html: '' }
+  }
+
+  // Find matches for the specified key
+  const keyMatch = matches?.find(match => match.key === key)
+
+  // No matches - return truncated content
+  if (!keyMatch || !keyMatch.indices || keyMatch.indices.length === 0) {
+    const snippet = text.slice(0, maxLength)
+    const suffix = text.length > maxLength ? '…' : ''
+    return {
+      text: snippet + suffix,
+      html: escapeHtml(snippet) + suffix
+    }
+  }
+
+  // Get the first match position
+  const [firstStart, firstEnd] = keyMatch.indices[0]
+
+  // Calculate slice boundaries around the first match
+  const sliceStart = Math.max(0, firstStart - contextChars)
+  const sliceEnd = Math.min(text.length, firstEnd + contextChars + 1)
+
+  // Extract the snippet
+  const snippet = text.slice(sliceStart, sliceEnd)
+
+  // Adjust match indices to be relative to the snippet
+  const adjustedIndices = keyMatch.indices
+    .map(([start, end]) => [start - sliceStart, end - sliceStart])
+    .filter(([start, end]) => end >= 0 && start < snippet.length)
+
+  // Build highlighted HTML
+  const html = highlightMatches(snippet, adjustedIndices, { tag: highlightTag })
+
+  // Add ellipsis indicators
+  const prefix = sliceStart > 0 ? '…' : ''
+  const suffix = sliceEnd < text.length ? '…' : ''
+
+  return {
+    text: `${prefix}${snippet}${suffix}`,
+    html: `${prefix}${html}${suffix}`
+  }
+}
+
+/**
+ * Highlight matches in text using HTML tags
+ *
+ * @param {string} text - Text to highlight
+ * @param {Array<[number, number]>} indices - Array of [start, end] index pairs
+ * @param {Object} options - Options
+ * @param {string} [options.tag='mark'] - HTML tag to use
+ * @param {string} [options.className] - Optional CSS class for the tag
+ * @returns {string} HTML string with highlighted matches
+ *
+ * @example
+ * highlightMatches('hello world', [[0, 4]], { tag: 'mark' })
+ * // Returns: '<mark>hello</mark> world'
+ */
+export function highlightMatches(text, indices, options = {}) {
+  const { tag = 'mark', className } = options
+
+  if (!text || !indices || indices.length === 0) {
+    return escapeHtml(text || '')
+  }
+
+  // Sort indices by start position
+  const sortedIndices = [...indices].sort((a, b) => a[0] - b[0])
+
+  // Build HTML string
+  let cursor = 0
+  let html = ''
+  const openTag = className ? `<${tag} class="${className}">` : `<${tag}>`
+  const closeTag = `</${tag}>`
+
+  for (const [start, end] of sortedIndices) {
+    // Ensure valid bounds
+    const safeStart = Math.max(0, Math.min(start, text.length))
+    const safeEnd = Math.max(0, Math.min(end + 1, text.length))
+
+    // Skip invalid ranges
+    if (safeStart >= safeEnd || safeStart < cursor) continue
+
+    // Add text before the match
+    if (safeStart > cursor) {
+      html += escapeHtml(text.slice(cursor, safeStart))
+    }
+
+    // Add highlighted match
+    html += openTag + escapeHtml(text.slice(safeStart, safeEnd)) + closeTag
+    cursor = safeEnd
+  }
+
+  // Add remaining text
+  if (cursor < text.length) {
+    html += escapeHtml(text.slice(cursor))
+  }
+
+  return html
+}
+
+/**
+ * Extract plain text from a search result for display
+ *
+ * @param {Object} result - Search result object
+ * @param {Object} options - Options
+ * @param {number} [options.maxLength=200] - Maximum text length
+ * @returns {string} Plain text excerpt
+ */
+export function getResultText(result, options = {}) {
+  const { maxLength = 200 } = options
+
+  // Prefer snippet, fall back to excerpt, then content
+  const text = result.snippetText || result.excerpt || result.content || ''
+
+  if (text.length <= maxLength) {
+    return text
+  }
+
+  return text.slice(0, maxLength).trim() + '…'
+}
+
+/**
+ * Format search result for display in a list
+ *
+ * @param {Object} result - Search result from createSearchClient.query()
+ * @returns {Object} Formatted result for UI display
+ */
+export function formatResultForDisplay(result) {
+  return {
+    id: result.id,
+    href: result.href,
+    title: result.title || result.pageTitle || 'Untitled',
+    subtitle: result.type === 'section' ? result.pageTitle : null,
+    text: result.snippetText || result.excerpt || '',
+    html: result.snippetHtml || escapeHtml(result.excerpt || ''),
+    type: result.type,
+    component: result.component
+  }
+}
+
+export default buildSnippet