@uniweb/kit 0.1.10 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @uniweb/kit
 
-Standard component library for Uniweb foundations.
+Standard component library for Uniweb foundations. Tree-shakeable utilities, components, and hooks for building foundation components.
 
 ## Installation
 
@@ -8,53 +8,58 @@ Standard component library for Uniweb foundations.
 npm install @uniweb/kit
 ```
 
+## Tree-Shaking Benefits
+
+Kit is designed to be bundled into your foundation (not externalized like `@uniweb/core`). This means:
+
+- **Only what you use is bundled** — Import 3 components? Only those 3 end up in your foundation
+- **No runtime overhead** — Unused code is eliminated at build time
+- **Customizable** — Override or extend any component without carrying dead code
+- **Small foundations** — A minimal foundation using just `Link` and `useWebsite` stays tiny
+
+```js
+// vite.config.js - Kit is bundled, core is external
+export default {
+  build: {
+    rollupOptions: {
+      external: ['react', 'react-dom', 'react-router-dom', '@uniweb/core']
+      // Note: @uniweb/kit is NOT in external — it gets tree-shaken
+    }
+  }
+}
+```
+
 ## Quick Start
 
 ```jsx
-import { Link, Image, Section, useWebsite } from '@uniweb/kit'
+import { Link, Image, useWebsite } from '@uniweb/kit'
 
-function Hero() {
+function Hero({ content }) {
   const { localize } = useWebsite()
 
   return (
-    <Section width="xl" padding="lg">
-      <Image src="/hero.jpg" alt="Hero" className="rounded-xl" />
-      <h1>{localize({ en: 'Welcome', fr: 'Bienvenue' })}</h1>
+    <div>
+      <Image src={content.imgs[0]?.url} alt="Hero" />
+      <h1>{localize({ en: 'Welcome', es: 'Bienvenido' })}</h1>
       <Link to="/about">Learn More</Link>
-    </Section>
+    </div>
   )
 }
 ```
 
-## Why @uniweb/kit?
-
-Kit provides the standard primitives that make Uniweb foundations work correctly:
-
-1. **Handle Uniweb conventions** — Components like `Link` and `Image` understand topic links, locale prefixes, and asset resolution automatically.
-
-2. **Runtime integration** — The `useWebsite()` hook gives you access to the website instance, localization functions, and routing utilities.
-
-3. **Semantic parser output** — Typography components (`H1`, `P`, `Text`) handle both strings and string arrays correctly, matching the semantic parser's output format.
-
-4. **Portability** — Your foundation works identically in development, static builds, and the Uniweb platform.
+## Exports Overview
 
-### When to use kit vs custom components
+| Import Path | Purpose |
+|-------------|---------|
+| `@uniweb/kit` | Core components, hooks, and utilities |
+| `@uniweb/kit/styled` | Pre-styled components (Section, SidebarLayout, etc.) |
+| `@uniweb/kit/search` | Search client and hooks (requires Fuse.js) |
 
-| Use @uniweb/kit for | Use custom components for |
-|---------------------|---------------------------|
-| Links and navigation | Custom button styles |
-| Images with filters | Specialized image treatments |
-| Text rendering | Domain-specific formatting |
-| Video embeds | Custom media players |
-| Website/locale access | Business logic |
-
-Kit components are designed to be composed and styled, not replaced wholesale. Wrap them, extend them, or use them as building blocks.
+---
 
 ## Components
 
-### Primitives
-
-#### Link
+### Link
 
 Smart link component with routing, downloads, and auto-generated accessible titles.
 
@@ -70,11 +75,11 @@ import { Link } from '@uniweb/kit'
 | Prop | Type | Description |
 |------|------|-------------|
 | `to` / `href` | `string` | Destination URL |
-| `title` | `string` | Tooltip (auto-generated if not provided) |
+| `title` | `string` | Tooltip (auto-generated if omitted) |
 | `target` | `string` | Link target |
 | `download` | `boolean` | Force download behavior |
 
-#### Image
+### Image
 
 Versatile image component with filters and profile integration.
 
@@ -90,13 +95,13 @@ import { Image } from '@uniweb/kit'
 |------|------|-------------|
 | `src` / `url` | `string` | Image URL |
 | `alt` | `string` | Alt text |
-| `size` | `string` | Size preset: xs, sm, md, lg, xl, 2xl, full |
+| `size` | `string` | Preset: xs, sm, md, lg, xl, 2xl, full |
 | `rounded` | `boolean\|string` | Border radius |
 | `filter` | `object` | CSS filters: blur, brightness, contrast, grayscale, saturate, sepia |
 | `profile` | `object` | Profile for avatar/banner images |
 | `type` | `string` | Image type: avatar, banner |
 
-#### SafeHtml
+### SafeHtml
 
 Safely render HTML with topic link resolution.
 
@@ -107,7 +112,7 @@ import { SafeHtml } from '@uniweb/kit'
 <SafeHtml value='<a href="topic:about">About</a>' />
 ```
 
-#### Icon
+### Icon
 
 SVG icon component with built-in icons and URL loading.
 
@@ -119,28 +124,38 @@ import { Icon } from '@uniweb/kit'
 <Icon svg="<svg>...</svg>" />
 ```
 
-Built-in icons: check, alert, user, heart, settings, star, close, menu, chevronDown, chevronRight, externalLink, download, play
+Built-in: check, alert, user, heart, settings, star, close, menu, chevronDown, chevronRight, externalLink, download, play
 
-### Typography
+### SocialIcon
 
-#### Text
+Social media platform icons with automatic detection.
 
-Smart typography component for rendering semantic parser output. Handles strings or arrays with automatic tag selection.
+```jsx
+import { SocialIcon, getSocialPlatform, filterSocialLinks } from '@uniweb/kit'
+
+<SocialIcon platform="twitter" size={24} />
+<SocialIcon url="https://twitter.com/example" />
+
+// Utilities
+getSocialPlatform('https://linkedin.com/in/user')  // 'linkedin'
+filterSocialLinks(links)  // Filter to only social links
+```
+
+Supported: facebook, twitter, x, linkedin, instagram, youtube, github, medium, pinterest, tiktok, discord, mastodon, bluesky, email, phone, orcid, researchgate, googlescholar
+
+### Typography
+
+Smart typography components for rendering semantic parser output.
 
 ```jsx
 import { Text, H1, H2, P, PlainText } from '@uniweb/kit'
 
-// Using semantic aliases (recommended)
 <H1 text="Main Title" />
 <H2 text={["Multi-line", "Subtitle"]} />
 <P text="A paragraph of content" />
 <P text={["First paragraph", "Second paragraph"]} />
 
-// Using Text directly
-<Text text="Hello" as="h1" />
-<Text text={["Line 1", "Line 2"]} as="h2" />
-
-// Plain text (HTML tags shown as text)
+// Plain text (HTML shown as text)
 <PlainText text="Show <strong>tags</strong> as text" />
 ```
 
@@ -150,19 +165,11 @@ import { Text, H1, H2, P, PlainText } from '@uniweb/kit'
 | `as` | `string` | Tag: 'h1'-'h6', 'p', 'div', 'span' |
 | `html` | `boolean` | Render as HTML (default: true) |
 | `lineAs` | `string` | Tag for array items |
-| `className` | `string` | CSS classes |
 
-**Semantic aliases**: `H1`, `H2`, `H3`, `H4`, `H5`, `H6`, `P`, `Span`, `Div`, `PlainText`
-
-**Key behaviors**:
-- Empty strings/arrays return `null` (no empty elements)
-- Headings with arrays: all lines wrapped in single heading tag
-- Paragraphs with arrays: each line gets its own `<p>` tag
+Aliases: `H1`, `H2`, `H3`, `H4`, `H5`, `H6`, `P`, `Span`, `Div`, `PlainText`
 
 ### Media
 
-#### Media
-
 Video player for YouTube, Vimeo, and local videos.
 
 ```jsx
@@ -173,17 +180,7 @@ import { Media } from '@uniweb/kit'
 <Media src="https://youtube.com/..." thumbnail="/poster.jpg" facade />
 ```
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `src` | `string` | Video URL |
-| `thumbnail` | `string` | Poster image URL |
-| `autoplay` | `boolean` | Auto-play video |
-| `muted` | `boolean` | Mute video |
-| `loop` | `boolean` | Loop video |
-| `controls` | `boolean` | Show controls |
-| `facade` | `boolean` | Show thumbnail with play button |
-
-#### FileLogo
+### FileLogo
 
 File type icons based on filename.
 
@@ -191,143 +188,364 @@ File type icons based on filename.
 import { FileLogo } from '@uniweb/kit'
 
 <FileLogo filename="report.pdf" size="32" />
-<FileLogo filename="data.xlsx" />
 ```
 
-#### MediaIcon
+### MediaIcon
 
-Social media platform icons.
+Platform icons (YouTube, Vimeo, etc.).
 
 ```jsx
 import { MediaIcon } from '@uniweb/kit'
 
-<MediaIcon type="twitter" size="24" />
-<MediaIcon type="linkedin" className="text-blue-600" />
+<MediaIcon type="youtube" size="24" />
 ```
 
-Supported: facebook, twitter, x, linkedin, instagram, youtube, github, medium, pinterest, email, phone, orcid, researchgate
+### Asset
 
-### Content
+File preview with download functionality.
 
-#### Section
+```jsx
+import { Asset } from '@uniweb/kit'
+
+<Asset value="document.pdf" profile={profile} />
+```
+
+---
 
-Rich content section with layout options.
+## Hooks
+
+### useWebsite
+
+Access website instance and utilities.
 
 ```jsx
-import { Section } from '@uniweb/kit'
+import { useWebsite } from '@uniweb/kit'
 
-<Section content={blockContent} width="lg" padding="md" />
+function MyComponent() {
+  const {
+    website,      // Website instance
+    localize,     // Localize multilingual values
+    makeHref,     // Transform hrefs (topic:, locale prefixes)
+    getLanguage,  // Current language code
+    getLanguages  // Available languages
+  } = useWebsite()
 
-<Section width="xl" columns="2" className="bg-gray-50">
-  <div>Column 1</div>
-  <div>Column 2</div>
-</Section>
+  return <div>{localize({ en: 'Hello', fr: 'Bonjour' })}</div>
+}
 ```
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `content` | `object\|array` | Content to render |
-| `block` | `object` | Block object from runtime |
-| `width` | `string` | sm, md, lg, xl, 2xl, full |
-| `columns` | `string` | 1, 2, 3, 4 |
-| `padding` | `string` | none, sm, md, lg, xl |
+### useActiveRoute
 
-#### Render
+Detect active navigation state.
 
-Content block renderer (used internally by Section).
+```jsx
+import { useActiveRoute } from '@uniweb/kit'
+
+function NavLink({ page }) {
+  const { isActive, isActiveOrAncestor } = useActiveRoute()
+
+  return (
+    <Link
+      to={page.route}
+      className={isActiveOrAncestor(page) ? 'font-bold' : ''}
+    >
+      {page.title}
+    </Link>
+  )
+}
+```
+
+### useScrolled
+
+Detect scroll position for sticky headers.
 
 ```jsx
-import { Render } from '@uniweb/kit'
+import { useScrolled } from '@uniweb/kit'
 
-<Render content={proseMirrorContent} />
+function Header() {
+  const scrolled = useScrolled(50)  // Threshold in pixels
+
+  return (
+    <header className={scrolled ? 'shadow-md' : ''}>
+      ...
+    </header>
+  )
+}
 ```
 
-#### Content Renderers
+### useMobileMenu
 
-Individual content type renderers:
+Mobile menu state management.
 
 ```jsx
-import { Code, Alert, Table, Details, Divider } from '@uniweb/kit'
+import { useMobileMenu } from '@uniweb/kit'
+
+function Navbar() {
+  const { isOpen, toggle, close } = useMobileMenu()
 
-<Code content="const x = 1" language="javascript" />
-<Alert type="warning" content="Be careful!" />
-<Table content={tableData} />
-<Details summary="Click to expand" content="Hidden content" />
-<Divider type="dots" />
+  return (
+    <>
+      <button onClick={toggle}>Menu</button>
+      {isOpen && <MobileMenu onClose={close} />}
+    </>
+  )
+}
 ```
 
-### Utilities
+### useAccordion
 
-#### Asset
+Accordion/FAQ state management.
 
-File preview with download functionality.
+```jsx
+import { useAccordion } from '@uniweb/kit'
+
+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>
+  ))
+}
+```
+
+### useInView
+
+Viewport intersection detection for lazy loading and animations.
 
 ```jsx
-import { Asset } from '@uniweb/kit'
+import { useInView, useIsInView } from '@uniweb/kit'
 
-<Asset value="document.pdf" profile={profile} />
-<Asset value={{ src: "/files/report.pdf", filename: "report.pdf" }} />
+function AnimatedSection() {
+  const { ref, inView } = useInView({ threshold: 0.2, once: true })
+
+  return (
+    <div ref={ref} className={inView ? 'animate-fade-in' : 'opacity-0'}>
+      Content appears when scrolled into view
+    </div>
+  )
+}
+
+// Simple boolean version
+function LazyImage({ src }) {
+  const [ref, isInView] = useIsInView()
+  return <div ref={ref}>{isInView && <img src={src} />}</div>
+}
 ```
 
-#### Disclaimer
+### useGridLayout
 
-Modal disclaimer dialog.
+Responsive grid utilities.
 
 ```jsx
-import { Disclaimer } from '@uniweb/kit'
+import { useGridLayout, getGridClasses } from '@uniweb/kit'
 
-<Disclaimer
-  title="Terms of Service"
-  content="<p>Please read our terms...</p>"
-  triggerText="View Terms"
-/>
+function Gallery({ items }) {
+  const { columns } = useGridLayout(items.length, { maxColumns: 4 })
+
+  return (
+    <div className={getGridClasses(columns)}>
+      {items.map(item => <Card key={item.id} {...item} />)}
+    </div>
+  )
+}
 ```
 
-## Hooks
+### Theme Hooks
 
-### useWebsite
+Access site theming data at runtime.
 
-Access website instance and utilities.
+```jsx
+import {
+  useThemeData,
+  useThemeColor,
+  useThemeColorVar,
+  useColorContext,
+  useAppearance
+} from '@uniweb/kit'
+
+function ThemedComponent({ block }) {
+  // Full theme access
+  const theme = useThemeData()
+  const palettes = theme?.getPaletteNames()  // ['primary', 'secondary', ...]
+
+  // Get specific color
+  const primaryColor = useThemeColor('primary', 500)  // '#3b82f6'
+  const primaryVar = useThemeColorVar('primary', 600)  // 'var(--primary-600)'
+
+  // Context-aware (light/medium/dark sections)
+  const context = useColorContext(block)  // 'light' | 'medium' | 'dark'
+
+  // Dark mode
+  const { scheme, toggle, canToggle } = useAppearance()
+
+  return (
+    <div style={{ color: primaryColor }}>
+      {canToggle && (
+        <button onClick={toggle}>
+          {scheme === 'dark' ? 'Light' : 'Dark'}
+        </button>
+      )}
+    </div>
+  )
+}
+```
+
+---
+
+## Search (`@uniweb/kit/search`)
+
+Full-text search powered by Fuse.js. Requires `fuse.js` as a peer dependency in your foundation.
+
+```bash
+npm install fuse.js
+```
+
+### useSearch
+
+Main search hook with debouncing and state management.
 
 ```jsx
-import { useWebsite } from '@uniweb/kit'
+import { useSearch } from '@uniweb/kit/search'
 
-function MyComponent() {
-  const {
-    website,      // Website instance
-    localize,     // Localize multilingual values
-    makeHref,     // Transform hrefs
-    getLanguage,  // Current language
-    getLanguages  // Available languages
-  } = useWebsite()
+function SearchComponent() {
+  const { website } = useWebsite()
+  const { query, results, isLoading, isEnabled, preload } = useSearch(website)
 
-  return <div>{localize({ en: 'Hello', fr: 'Bonjour' })}</div>
+  if (!isEnabled) return null
+
+  return (
+    <div>
+      <input onChange={e => query(e.target.value)} placeholder="Search..." />
+      {isLoading && <span>Searching...</span>}
+      {results.map(r => (
+        <a key={r.id} href={r.href}>{r.title}</a>
+      ))}
+    </div>
+  )
+}
+```
+
+### useSearchWithIntent
+
+Intent-based preloading — loads search index on hover/focus instead of page load.
+
+```jsx
+import { useSearchWithIntent, useSearchShortcut } from '@uniweb/kit/search'
+
+function SearchButton({ onClick }) {
+  const { website } = useWebsite()
+  const { triggerPreload, intentProps } = useSearchWithIntent(website)
+
+  // Cmd/Ctrl+K shortcut with preload
+  useSearchShortcut({
+    onOpen: onClick,
+    onPreload: triggerPreload,
+  })
+
+  return (
+    <button onClick={onClick} {...intentProps}>
+      Search
+    </button>
+  )
 }
 ```
 
-## Utility Functions
+This saves bandwidth — the search index only loads when users show intent to search.
+
+### useSearchShortcut
+
+Keyboard shortcut for opening search.
+
+```jsx
+import { useSearchShortcut } from '@uniweb/kit/search'
+
+// Simple
+useSearchShortcut(() => setSearchOpen(true))
+
+// With preload on shortcut
+useSearchShortcut({
+  onOpen: () => setSearchOpen(true),
+  onPreload: () => searchClient.preload()
+})
+```
+
+### createSearchClient
+
+Low-level search client for advanced use.
+
+```jsx
+import { createSearchClient } from '@uniweb/kit/search'
+
+const client = createSearchClient(website, {
+  fuseOptions: { threshold: 0.3 },
+  defaultLimit: 10
+})
+
+// Query
+const results = await client.query('authentication', { limit: 5 })
+
+// Preload index
+await client.preload()
+
+// Check status
+client.isEnabled()
+client.getIndexUrl()
+```
+
+---
+
+## Styled Components (`@uniweb/kit/styled`)
+
+Pre-styled components with Tailwind CSS. Import separately to keep core kit dependency-free.
+
+```jsx
+import { Section, SidebarLayout, Disclaimer } from '@uniweb/kit/styled'
+
+<Section width="lg" padding="md" className="bg-gray-50">
+  <h1>Welcome</h1>
+</Section>
+
+<SidebarLayout sidebar={<Nav />} sidebarPosition="left">
+  <main>Content</main>
+</SidebarLayout>
+
+<Disclaimer
+  title="Terms of Service"
+  content="<p>Please read our terms...</p>"
+  triggerText="View Terms"
+/>
+```
+
+---
+
+## Utilities
 
 ```jsx
 import { cn, stripTags, isExternalUrl, isFileUrl, detectMediaType } from '@uniweb/kit'
 
-// Merge Tailwind classes
+// Merge Tailwind classes (uses tailwind-merge)
 cn('px-4 py-2', 'bg-blue-500', condition && 'opacity-50')
 
 // Strip HTML tags
-stripTags('<p>Hello</p>') // "Hello"
+stripTags('<p>Hello</p>')  // "Hello"
 
 // URL utilities
-isExternalUrl('https://google.com') // true
-isFileUrl('/files/doc.pdf')         // true
-detectMediaType('https://youtube.com/...') // 'youtube'
+isExternalUrl('https://google.com')  // true
+isFileUrl('/files/doc.pdf')          // true
+detectMediaType('https://youtube.com/...')  // 'youtube'
 ```
 
+---
+
 ## Architecture
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │  Foundation (your code)                                     │
-│    ├── imports @uniweb/kit (bundled into foundation)        │
+│    ├── imports @uniweb/kit (bundled, tree-shaken)           │
 │    └── @uniweb/core marked as external                      │
 └─────────────────────────────────────────────────────────────┘
                               │
@@ -340,29 +558,11 @@ detectMediaType('https://youtube.com/...') // 'youtube'
 └─────────────────────────────────────────────────────────────┘
 ```
 
-## For Foundation Creators
-
-1. **Use kit components** for common UI patterns
-2. **Use hooks** like `useWebsite` for localization and routing
-3. **Don't access `globalThis.uniweb`** directly - use kit's abstractions
-4. **Bundle kit, externalize core** - kit gets tree-shaken into your foundation
+### Why bundle kit but externalize core?
 
-```js
-// vite.config.js
-export default {
-  build: {
-    rollupOptions: {
-      // Kit is bundled (tree-shaken), core is external (provided by runtime)
-      external: ['react', 'react-dom', 'react-router-dom', '@uniweb/core']
-    }
-  }
-}
-```
+- **Kit**: Different foundations may use different subsets of kit. Tree-shaking ensures each foundation only includes what it uses.
 
-This approach lets you:
-- Tree-shake unused kit components
-- Override or extend kit components
-- Bring your own alternative components
+- **Core**: Contains the Website, Page, and Block classes that must be singletons. The runtime provides these — foundations reference them via the external import.
 
 ## License