@uniweb/kit 0.1.11 → 0.2.1

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
 

package/package.json

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

package/src/components/Link/Link.jsx

@@ -170,8 +170,10 @@ export function Link({
   // Normalize href
   let linkHref = href || to || ''
 
-  // Handle topic: protocol (internal reference)
-  if (linkHref.startsWith('topic:')) {
+  // Handle internal reference protocols
+  // - topic: legacy internal reference
+  // - page: stable page reference (page:pageId#sectionId)
+  if (linkHref.startsWith('topic:') || linkHref.startsWith('page:')) {
     linkHref = makeHref(linkHref)
   }
 

package/src/hooks/index.js

@@ -1,6 +1,7 @@
 export { useWebsite, default } from './useWebsite.js'
 export { useRouting } from './useRouting.js'
 export { useActiveRoute } from './useActiveRoute.js'
+export { useVersion } from './useVersion.js'
 export { useScrolled } from './useScrolled.js'
 export { useMobileMenu } from './useMobileMenu.js'
 export { useAccordion } from './useAccordion.js'

package/src/hooks/useVersion.js

@@ -0,0 +1,129 @@
+/**
+ * useVersion Hook
+ *
+ * Hook for version switching in documentation sites.
+ * Provides access to version information and utilities for building
+ * version switcher components.
+ *
+ * @example
+ * function VersionSwitcher() {
+ *   const { isVersioned, currentVersion, versions, getVersionUrl } = useVersion()
+ *
+ *   if (!isVersioned) return null
+ *
+ *   return (
+ *     <select
+ *       value={currentVersion?.id}
+ *       onChange={(e) => navigate(getVersionUrl(e.target.value))}
+ *     >
+ *       {versions.map(v => (
+ *         <option key={v.id} value={v.id}>
+ *           {v.label} {v.latest ? '(latest)' : ''} {v.deprecated ? '(deprecated)' : ''}
+ *         </option>
+ *       ))}
+ *     </select>
+ *   )
+ * }
+ */
+
+import { useRouting } from './useRouting.js'
+import { useWebsite } from './useWebsite.js'
+
+/**
+ * Hook for version information and switching.
+ * Works both at page level (when page has version context) and
+ * at site level (checking versioned scopes).
+ *
+ * @param {Object} options - Optional configuration
+ * @param {Page} options.page - Specific page to check (default: active page)
+ * @returns {Object} Version utilities
+ */
+export function useVersion(options = {}) {
+  const { useLocation } = useRouting()
+  const { website } = useWebsite()
+  const location = useLocation()
+
+  const page = options.page || website.activePage
+  // Prefer page route for SSG accuracy, fallback to location pathname
+  const currentRoute = page?.route || location?.pathname || '/'
+
+  // Check if the current page/route is within a versioned section
+  const isVersioned = page?.isVersioned() || website.isVersionedRoute(currentRoute)
+
+  // Get version information from page (preferred) or compute from route
+  const currentVersion = page?.getVersion() || null
+  const versionMeta = page?.versionMeta || website.getVersionMeta(website.getVersionScope(currentRoute))
+  const versions = versionMeta?.versions || []
+  const latestVersionId = versionMeta?.latestId || null
+
+  // Find the version scope for the current route
+  const versionScope = page?.versionScope || website.getVersionScope(currentRoute)
+
+  return {
+    /**
+     * Whether the current page is within a versioned section
+     * @type {boolean}
+     */
+    isVersioned,
+
+    /**
+     * Current version info { id, label, latest, deprecated }
+     * @type {Object|null}
+     */
+    currentVersion,
+
+    /**
+     * All available versions for this scope
+     * @type {Array<{id: string, label: string, latest: boolean, deprecated: boolean}>}
+     */
+    versions,
+
+    /**
+     * The ID of the latest version
+     * @type {string|null}
+     */
+    latestVersionId,
+
+    /**
+     * The route where versioning starts (e.g., '/docs')
+     * @type {string|null}
+     */
+    versionScope,
+
+    /**
+     * Check if current version is the latest
+     * @type {boolean}
+     */
+    isLatestVersion: currentVersion?.latest === true,
+
+    /**
+     * Check if current version is deprecated
+     * @type {boolean}
+     */
+    isDeprecatedVersion: currentVersion?.deprecated === true,
+
+    /**
+     * Get URL for switching to a different version
+     * @param {string} targetVersion - Target version ID (e.g., 'v1')
+     * @returns {string|null} Target URL or null if not versioned
+     */
+    getVersionUrl: (targetVersion) => {
+      if (!isVersioned) return null
+      return website.getVersionUrl(targetVersion, currentRoute)
+    },
+
+    /**
+     * Check if site has any versioned content
+     * @type {boolean}
+     */
+    hasVersionedContent: website.hasVersionedContent(),
+
+    /**
+     * Get all versioned scopes in the site
+     * @type {Object} Map of scope → { versions, latestId }
+     */
+    versionedScopes: website.getVersionedScopes(),
+  }
+}
+
+export default useVersion

package/src/index.js

@@ -62,6 +62,7 @@ export {
   useWebsite,
   useRouting,
   useActiveRoute,
+  useVersion,
   useScrolled,
   useMobileMenu,
   useAccordion,
@@ -93,5 +94,8 @@ export {
   stripTags,
   isExternalUrl,
   isFileUrl,
-  detectMediaType
+  detectMediaType,
+  // Locale utilities
+  LOCALE_DISPLAY_NAMES,
+  getLocaleLabel
 } from './utils/index.js'

package/src/search/hooks.js

@@ -236,4 +236,88 @@ export function useSearchIndex(website, options = {}) {
   }
 }
 
+/**
+ * Hook for Cmd/Ctrl+K keyboard shortcut to open search
+ *
+ * @param {Function|Object} callbacks - Either onOpen function, or { onOpen, onPreload }
+ *
+ * @example
+ * // Simple usage
+ * useSearchShortcut(() => setSearchOpen(true))
+ *
+ * // With preload
+ * useSearchShortcut({
+ *   onOpen: () => setSearchOpen(true),
+ *   onPreload: () => search.preload()
+ * })
+ */
+export function useSearchShortcut(callbacks) {
+  const { onOpen, onPreload } = typeof callbacks === 'function'
+    ? { onOpen: callbacks, onPreload: null }
+    : callbacks
+
+  useEffect(() => {
+    const handleKeyDown = (e) => {
+      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
+        e.preventDefault()
+        onPreload?.()
+        onOpen()
+      }
+    }
+
+    window.addEventListener('keydown', handleKeyDown)
+    return () => window.removeEventListener('keydown', handleKeyDown)
+  }, [onOpen, onPreload])
+}
+
+/**
+ * Hook that wraps useSearch with intent-based preloading
+ *
+ * Provides handlers to trigger preload on user intent (hover, focus, touch)
+ * rather than on component mount. This saves bandwidth for users who never search.
+ *
+ * @param {Object} website - Website instance from @uniweb/core
+ * @param {Object} options - Options passed to useSearch
+ * @returns {Object} Search state, methods, and intent handlers
+ *
+ * @example
+ * function SearchButton({ onClick }) {
+ *   const { intentProps, triggerPreload } = useSearchWithIntent(website)
+ *
+ *   useSearchShortcut({
+ *     onOpen: onClick,
+ *     onPreload: triggerPreload,
+ *   })
+ *
+ *   return (
+ *     <button onClick={onClick} {...intentProps}>
+ *       Search
+ *     </button>
+ *   )
+ * }
+ */
+export function useSearchWithIntent(website, options = {}) {
+  const search = useSearch(website, options)
+  const hasPreloaded = useRef(false)
+
+  const triggerPreload = useCallback(() => {
+    if (hasPreloaded.current) return
+    hasPreloaded.current = true
+    search.preload()
+  }, [search])
+
+  // Intent handlers - spread onto interactive elements
+  const intentProps = useMemo(() => ({
+    onMouseEnter: triggerPreload,
+    onFocus: triggerPreload,
+    onTouchStart: triggerPreload,
+  }), [triggerPreload])
+
+  return {
+    ...search,
+    triggerPreload,
+    intentProps,
+  }
+}
+
 export default useSearch

package/src/search/index.js

@@ -23,4 +23,4 @@
 
 export { createSearchClient, loadSearchIndex, clearSearchCache } from './client.js'
 export { buildSnippet, highlightMatches, escapeHtml } from './snippets.js'
-export { useSearch, useSearchIndex } from './hooks.js'
+export { useSearch, useSearchIndex, useSearchShortcut, useSearchWithIntent } from './hooks.js'

package/src/utils/index.js

@@ -9,6 +9,75 @@ import { twMerge, twJoin } from 'tailwind-merge'
 // Re-export tailwind-merge utilities
 export { twMerge, twJoin }
 
+// ─────────────────────────────────────────────────────────────────
+// Locale Utilities
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Common locale display names (native language names)
+ * Used as fallback when site.yml doesn't specify labels.
+ * Tree-shakeable: only included if foundation uses getLocaleLabel().
+ */
+export const LOCALE_DISPLAY_NAMES = {
+  en: 'English',
+  es: 'Español',
+  fr: 'Français',
+  de: 'Deutsch',
+  it: 'Italiano',
+  pt: 'Português',
+  nl: 'Nederlands',
+  pl: 'Polski',
+  ru: 'Русский',
+  ja: '日本語',
+  ko: '한국어',
+  zh: '中文',
+  'zh-CN': '简体中文',
+  'zh-TW': '繁體中文',
+  ar: 'العربية',
+  he: 'עברית',
+  hi: 'हिन्दी',
+  th: 'ไทย',
+  vi: 'Tiếng Việt',
+  tr: 'Türkçe',
+  uk: 'Українська',
+  cs: 'Čeština',
+  el: 'Ελληνικά',
+  hu: 'Magyar',
+  ro: 'Română',
+  sv: 'Svenska',
+  da: 'Dansk',
+  fi: 'Suomi',
+  no: 'Norsk',
+  id: 'Bahasa Indonesia',
+  ms: 'Bahasa Melayu'
+}
+
+/**
+ * Get display label for a locale
+ * Priority: locale.label (from site config) → LOCALE_DISPLAY_NAMES → code.toUpperCase()
+ *
+ * @param {Object|string} locale - Locale object {code, label?} or locale code string
+ * @returns {string} Display label for the locale
+ *
+ * @example
+ * getLocaleLabel({ code: 'es', label: 'Spanish' }) // 'Spanish'
+ * getLocaleLabel({ code: 'es' })                   // 'Español'
+ * getLocaleLabel('es')                             // 'Español'
+ * getLocaleLabel({ code: 'xx' })                   // 'XX'
+ */
+export function getLocaleLabel(locale) {
+  // Handle string input (just a code)
+  if (typeof locale === 'string') {
+    return LOCALE_DISPLAY_NAMES[locale] || locale.toUpperCase()
+  }
+
+  // Handle object input
+  if (!locale || !locale.code) return ''
+
+  // Priority: explicit label → known display name → uppercase code
+  return locale.label || LOCALE_DISPLAY_NAMES[locale.code] || locale.code.toUpperCase()
+}
+
 /**
  * Merge class names with Tailwind CSS conflict resolution
  * @param {...string} classes - Class names to merge