@voltro/ui-shadcn 0.1.0

package/src/primitives/localeSwitcher.tsx

@@ -0,0 +1,90 @@
+// LocaleSwitcher — a minimal, SSR-safe language picker. Writes the canonical
+// `voltro:lang` cookie the framework's auto-wired i18n resolver reads, then
+// reloads so the server re-renders in the chosen locale. Same contract as
+// <ProfileMenu>'s language switch, extracted for standalone use in any app that
+// doesn't want the full profile menu (every scaffolded template drops this in).
+//
+// Native <select> on purpose: works everywhere with zero portal/positioning
+// chrome, keyboard-accessible by default, and SSR-safe. Pass `current` (e.g.
+// `useLocale()` from @voltro/i18n) so the server + first client paint agree on
+// the selected option; without it the control hydrates from the cookie after
+// mount (a brief flash from the first option, no hydration mismatch).
+
+import {
+  useEffect,
+  useState,
+  type ChangeEvent,
+  type ReactNode,
+} from 'react'
+import { cn } from '../cn'
+import { LANG_COOKIE, getCookie, setCookie } from '../cookies'
+
+export interface LocaleOption {
+  /** Language code written to the cookie (e.g. 'en', 'de'). */
+  readonly code: string
+  /** Human label shown in the picker (e.g. 'English', 'Deutsch'). */
+  readonly label: string
+}
+
+export interface LocaleSwitcherProps {
+  /** The languages to offer. */
+  readonly locales: ReadonlyArray<LocaleOption>
+  /** Override the active code. When omitted, hydrates from the `voltro:lang`
+   *  cookie on mount (falling back to the first option until then). Pass
+   *  `useLocale()` for a flash-free, mismatch-free control. */
+  readonly current?: string
+  /** Called with the chosen code before the reload. Return `false` to suppress
+   *  the reload (e.g. when the consumer has a hot-swap i18n runtime). */
+  readonly onChange?: (code: string) => boolean | void
+  /** Accessible label for the control. Default `'Language'`. */
+  readonly ariaLabel?: string
+  readonly className?: string
+}
+
+export const LocaleSwitcher = ({
+  locales,
+  current,
+  onChange,
+  ariaLabel = 'Language',
+  className,
+}: LocaleSwitcherProps): ReactNode => {
+  // Hydrate from the cookie on mount; `current` wins when set. The first client
+  // render (before this effect) matches the server (both = first option when no
+  // `current`), so hydration never mismatches — the cookie value lands as a
+  // post-hydration controlled update.
+  const [cookieLang, setCookieLang] = useState<string | undefined>(undefined)
+  useEffect(() => {
+    setCookieLang(getCookie(LANG_COOKIE) ?? undefined)
+  }, [])
+
+  const active = current ?? cookieLang ?? locales[0]?.code ?? ''
+
+  const handle = (event: ChangeEvent<HTMLSelectElement>): void => {
+    const next = event.target.value
+    setCookie(LANG_COOKIE, next)
+    setCookieLang(next)
+    const suppress = onChange?.(next) === false
+    if (!suppress && typeof window !== 'undefined') window.location.reload()
+  }
+
+  return (
+    <select
+      aria-label={ariaLabel}
+      value={active}
+      onChange={handle}
+      className={cn(
+        'h-9 rounded-md border border-input bg-transparent px-2 text-sm shadow-xs ' +
+          'outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50 focus-visible:border-ring ' +
+          'cursor-pointer',
+        className,
+      )}
+    >
+      {locales.map((l) => (
+        <option key={l.code} value={l.code}>
+          {l.label}
+        </option>
+      ))}
+    </select>
+  )
+}
+LocaleSwitcher.displayName = 'LocaleSwitcher'

package/src/primitives/meshBackdrop.tsx

@@ -0,0 +1,62 @@
+// MeshBackdrop — layered radial gradients that drift slowly over a
+// 60-second loop. Builds the cinematic "ambient nebula" feel without
+// shipping a video or a heavy 3D canvas. CSS-only, GPU-composited
+// transforms — no main-thread work after first paint.
+//
+// Composition: drop this once near the top of the page as
+// `position: absolute; inset: 0;` underneath your content. The blobs
+// drift in opposite directions so the composite movement never
+// repeats visibly.
+
+import type { ReactNode } from 'react'
+import { cn } from '../cn'
+
+interface MeshBackdropProps {
+  readonly className?: string
+  /** Brand mode — picks the colour palette. `cool` = violet/cyan
+   *  (default), `warm` = amber/rose. The kit's `--primary` is honoured
+   *  via the `from-primary/*` Tailwind utility callers can pass via
+   *  className. */
+  readonly tone?: 'cool' | 'warm'
+}
+
+export const MeshBackdrop = ({
+  className, tone = 'cool',
+}: MeshBackdropProps): ReactNode => {
+  // OK to read tone here — the blobs themselves are styled via inline
+  // gradients to avoid Tailwind shipping an extra colour class.
+  const blob1 = tone === 'warm'
+    ? 'oklch(0.6 0.2 25 / 0.55)'
+    : 'oklch(0.55 0.25 290 / 0.55)'
+  const blob2 = tone === 'warm'
+    ? 'oklch(0.7 0.18 60 / 0.4)'
+    : 'oklch(0.65 0.2 220 / 0.4)'
+  const blob3 = tone === 'warm'
+    ? 'oklch(0.55 0.25 350 / 0.35)'
+    : 'oklch(0.5 0.25 310 / 0.45)'
+
+  return (
+    <div
+      aria-hidden="true"
+      className={cn(
+        'absolute inset-0 overflow-hidden pointer-events-none',
+        className,
+      )}
+    >
+      {/* Three slow-drifting blobs at offset positions + offset
+       * animation phases. Heavy blur = ambient feel. */}
+      <div
+        className="absolute -top-1/4 -left-1/4 w-[60vw] h-[60vw] rounded-full blur-3xl opacity-70 motion-safe:animate-mesh-drift-a"
+        style={{ background: `radial-gradient(circle, ${blob1}, transparent 60%)` }}
+      />
+      <div
+        className="absolute -bottom-1/3 -right-1/4 w-[55vw] h-[55vw] rounded-full blur-3xl opacity-60 motion-safe:animate-mesh-drift-b"
+        style={{ background: `radial-gradient(circle, ${blob2}, transparent 60%)` }}
+      />
+      <div
+        className="absolute top-1/3 left-1/2 w-[40vw] h-[40vw] -translate-x-1/2 rounded-full blur-3xl opacity-50 motion-safe:animate-mesh-drift-c"
+        style={{ background: `radial-gradient(circle, ${blob3}, transparent 60%)` }}
+      />
+    </div>
+  )
+}

package/src/primitives/scrollReveal.tsx

@@ -0,0 +1,70 @@
+// ScrollReveal — wrap a section to fade + slide it up when it
+// enters the viewport. One-shot (never animates back out). Uses
+// IntersectionObserver, no scroll listeners, no main-thread work.
+//
+// `prefers-reduced-motion: reduce` short-circuits to instantly visible.
+
+import { useEffect, useRef, useState, type ReactNode } from 'react'
+import { cn } from '../cn'
+
+interface ScrollRevealProps {
+  readonly children: ReactNode
+  readonly className?: string
+  /** Pixel distance the element rises from. Default 24. */
+  readonly distance?: number
+  /** Delay before the animation runs, in ms. Default 0. */
+  readonly delay?: number
+  /** Intersection threshold 0…1. Default 0.15 — element starts
+   *  animating when 15% of it is in view. */
+  readonly threshold?: number
+  /** Disable the animation entirely (passthrough). Useful when the
+   *  parent is already a stagger container. */
+  readonly disabled?: boolean
+}
+
+export const ScrollReveal = ({
+  children, className, distance = 24, delay = 0,
+  threshold = 0.15, disabled = false,
+}: ScrollRevealProps): ReactNode => {
+  const ref = useRef<HTMLDivElement>(null)
+  const [shown, setShown] = useState(disabled)
+
+  useEffect(() => {
+    if (disabled) return
+    if (typeof IntersectionObserver === 'undefined') {
+      // Old browser — just show instantly.
+      setShown(true)
+      return
+    }
+    const node = ref.current
+    if (!node) return
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            setShown(true)
+            observer.disconnect()
+            return
+          }
+        }
+      },
+      { threshold, rootMargin: '0px 0px -10% 0px' },
+    )
+    observer.observe(node)
+    return () => observer.disconnect()
+  }, [threshold, disabled])
+
+  return (
+    <div
+      ref={ref}
+      className={cn('motion-safe:transition-all motion-safe:duration-700 motion-safe:ease-out', className)}
+      style={
+        shown
+          ? { opacity: 1, transform: 'translate3d(0, 0, 0)', transitionDelay: `${delay}ms` }
+          : { opacity: 0, transform: `translate3d(0, ${distance}px, 0)` }
+      }
+    >
+      {children}
+    </div>
+  )
+}

package/src/primitives/searchModal.tsx

@@ -0,0 +1,304 @@
+// SearchModal — cmd-k modal with live filter + keyboard navigation.
+//
+// Generic-enough that any app can wire it: pass a `search(query)`
+// function (returns a list of hits in whatever shape you have) and
+// render each hit with the `renderItem` prop. Selecting a hit calls
+// `onSelect(hit)` — typical use: navigate to `hit.href`.
+//
+// Keyboard:
+//   ⌘K / Ctrl+K   toggle open
+//   Esc           close
+//   ↑ / ↓         move highlight
+//   Enter         select highlighted hit
+//
+// Visual: Fumadocs/Linear-style centered modal, dark backdrop, blur,
+// rounded sharp-cornered card, monospaced ⌘K + Esc hints in the
+// header. Uses the kit's tokens so light + dark modes both work.
+//
+// Implementation notes:
+//   - The modal is conditionally mounted (only in the DOM when open)
+//     so we don't pay portal/listener cost on every page.
+//   - The cmd-k global listener is always attached when this component
+//     is in the tree, so the user can hit ⌘K from anywhere.
+
+import {
+  useCallback, useEffect, useId, useMemo, useRef, useState,
+  type KeyboardEvent, type ReactNode,
+} from 'react'
+import { cn } from '../cn'
+import { SearchIcon, ArrowReturnIcon } from './docIcons'
+
+export interface SearchModalProps<TItem> {
+  /** Search function — called on every keystroke. Should return
+   *  results synchronously (the kit doesn't manage async state here;
+   *  if you need async, debounce + useState in the caller). */
+  readonly search: (query: string) => ReadonlyArray<TItem>
+  /** Renders a single hit. Receives the item + whether it's currently
+   *  highlighted (for hover/keyboard focus styles). */
+  readonly renderItem: (item: TItem, isActive: boolean) => ReactNode
+  /** Stable key for an item — used for React keys + the active index
+   *  match across renders. */
+  readonly itemKey: (item: TItem) => string
+  /** Selecting a hit (click OR Enter). Caller typically navigates. */
+  readonly onSelect: (item: TItem) => void
+
+  /** Placeholder for the input. */
+  readonly placeholder?: string
+  /** Label shown when there are no hits + the query has 1+ char. */
+  readonly emptyLabel?: string
+  /** Initial empty state — when the input is empty. Show recent
+   *  searches, sections, whatever fits. */
+  readonly empty?: ReactNode
+
+  /** Open state — controlled. Default uses internal state. */
+  readonly open?: boolean
+  readonly onOpenChange?: (open: boolean) => void
+
+  /** User-facing strings for the modal's own chrome (dialog/backdrop
+   *  aria-labels, footer hint captions, initial-state prompt). Defaults
+   *  are English so the modal works unconfigured. */
+  readonly labels?: SearchModalLabels
+}
+
+export interface SearchModalLabels {
+  /** `aria-label` of the dialog. Default `'Search'`. */
+  readonly dialog?: string
+  /** `aria-label` of the click-to-close backdrop. Default `'Close search'`. */
+  readonly close?: string
+  /** Prompt shown when the input is empty (and no `empty` node given).
+   *  Default `'Start typing to search.'`. */
+  readonly startTyping?: string
+  /** Footer caption next to the ↑↓ keys. Default `'navigate'`. */
+  readonly navigate?: string
+  /** Footer caption next to the return key. Default `'select'`. */
+  readonly select?: string
+  /** Footer caption next to the ⌘K key. Default `'toggle'`. */
+  readonly toggle?: string
+}
+
+const DEFAULT_SEARCH_LABELS: Required<SearchModalLabels> = {
+  dialog: 'Search',
+  close: 'Close search',
+  startTyping: 'Start typing to search.',
+  navigate: 'navigate',
+  select: 'select',
+  toggle: 'toggle',
+}
+
+export const SearchModal = <TItem,>({
+  search, renderItem, itemKey, onSelect,
+  placeholder = 'Search…',
+  emptyLabel = 'No results.',
+  empty,
+  open: controlledOpen,
+  onOpenChange,
+  labels,
+}: SearchModalProps<TItem>): ReactNode => {
+  const t = { ...DEFAULT_SEARCH_LABELS, ...labels }
+  const isControlled = controlledOpen !== undefined
+  const [internalOpen, setInternalOpen] = useState(false)
+  const open = isControlled ? controlledOpen : internalOpen
+  const setOpen = useCallback((next: boolean): void => {
+    if (!isControlled) setInternalOpen(next)
+    onOpenChange?.(next)
+  }, [isControlled, onOpenChange])
+
+  const [query, setQuery] = useState('')
+  const [activeIdx, setActiveIdx] = useState(0)
+  const inputRef = useRef<HTMLInputElement>(null)
+  const listboxId = useId()
+
+  // Re-run search on every query change. Cheap for our doc-sized
+  // catalogues; if the result set grows past 1000 entries, debounce
+  // here.
+  const hits = useMemo(() => (query.trim() ? search(query) : []), [query, search])
+
+  // Reset highlight + scroll position when results change.
+  useEffect(() => { setActiveIdx(0) }, [query])
+
+  // Global ⌘K / Ctrl+K toggle.
+  useEffect(() => {
+    const handler = (e: globalThis.KeyboardEvent): void => {
+      const k = e.key.toLowerCase()
+      if (k === 'k' && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault()
+        setOpen(!open)
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  }, [open, setOpen])
+
+  // Focus the input + reset state on open.
+  useEffect(() => {
+    if (!open) return
+    setQuery('')
+    setActiveIdx(0)
+    // RAF lets the modal mount before we grab focus, so the autofocus
+    // ring doesn't paint twice.
+    const id = requestAnimationFrame(() => inputRef.current?.focus())
+    return () => cancelAnimationFrame(id)
+  }, [open])
+
+  const close = useCallback((): void => setOpen(false), [setOpen])
+
+  const onKeyDown = (e: KeyboardEvent<HTMLInputElement>): void => {
+    if (e.key === 'Escape') { e.preventDefault(); close(); return }
+    if (e.key === 'ArrowDown') {
+      e.preventDefault()
+      setActiveIdx((i) => Math.min(i + 1, Math.max(hits.length - 1, 0)))
+      return
+    }
+    if (e.key === 'ArrowUp') {
+      e.preventDefault()
+      setActiveIdx((i) => Math.max(i - 1, 0))
+      return
+    }
+    if (e.key === 'Enter') {
+      const hit = hits[activeIdx]
+      if (hit) { e.preventDefault(); onSelect(hit); close() }
+    }
+  }
+
+  if (!open) return null
+
+  return (
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-label={t.dialog}
+      className="fixed inset-0 z-50 flex items-start justify-center pt-[15vh] px-4"
+    >
+      {/* Backdrop — click closes */}
+      <button
+        type="button"
+        aria-label={t.close}
+        onClick={close}
+        className="absolute inset-0 bg-background/70 backdrop-blur-sm cursor-default"
+      />
+      {/* Modal card */}
+      <div
+        className={cn(
+          'relative w-full max-w-xl rounded-xl border border-border bg-card shadow-2xl overflow-hidden',
+          'animate-in fade-in slide-in-from-top-4 duration-150',
+        )}
+      >
+        <div className="flex items-center gap-3 px-4 py-3 border-b border-border">
+          <SearchIcon className="w-4 h-4 text-muted-foreground shrink-0" />
+          <input
+            ref={inputRef}
+            type="text"
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            onKeyDown={onKeyDown}
+            placeholder={placeholder}
+            aria-autocomplete="list"
+            aria-controls={listboxId}
+            aria-activedescendant={hits[activeIdx] ? `${listboxId}-${itemKey(hits[activeIdx]!)}` : undefined}
+            className="flex-1 bg-transparent text-sm outline-none placeholder:text-muted-foreground/70"
+          />
+          <kbd className="text-[0.65rem] text-muted-foreground border border-border rounded px-1.5 py-0.5 font-mono">
+            Esc
+          </kbd>
+        </div>
+
+        <div
+          id={listboxId}
+          role="listbox"
+          className="max-h-[60vh] overflow-y-auto py-1.5"
+        >
+          {query.trim() === '' ? (
+            empty ?? (
+              <div className="px-4 py-8 text-center text-sm text-muted-foreground">
+                {t.startTyping}
+              </div>
+            )
+          ) : hits.length === 0 ? (
+            <div className="px-4 py-8 text-center text-sm text-muted-foreground">
+              {emptyLabel}
+            </div>
+          ) : (
+            <ul className="px-1.5">
+              {hits.map((hit, i) => {
+                const isActive = i === activeIdx
+                const key = itemKey(hit)
+                return (
+                  <li
+                    key={key}
+                    id={`${listboxId}-${key}`}
+                    role="option"
+                    aria-selected={isActive}
+                  >
+                    <button
+                      type="button"
+                      onClick={() => { onSelect(hit); close() }}
+                      onMouseMove={() => setActiveIdx(i)}
+                      className={cn(
+                        'w-full text-left rounded-md px-3 py-2 transition-colors',
+                        isActive
+                          ? 'bg-accent text-accent-foreground'
+                          : 'text-foreground hover:bg-accent/50',
+                      )}
+                    >
+                      {renderItem(hit, isActive)}
+                    </button>
+                  </li>
+                )
+              })}
+            </ul>
+          )}
+        </div>
+
+        <div className="flex items-center justify-between gap-4 px-4 py-2 border-t border-border bg-card/40 text-[0.7rem] text-muted-foreground">
+          <div className="inline-flex items-center gap-3">
+            <span className="inline-flex items-center gap-1">
+              <kbd className="border border-border rounded px-1 py-0.5 font-mono">↑</kbd>
+              <kbd className="border border-border rounded px-1 py-0.5 font-mono">↓</kbd>
+              {t.navigate}
+            </span>
+            <span className="inline-flex items-center gap-1">
+              <ArrowReturnIcon className="w-3 h-3" /> {t.select}
+            </span>
+          </div>
+          <span className="inline-flex items-center gap-1">
+            <kbd className="border border-border rounded px-1 py-0.5 font-mono">⌘K</kbd>
+            {t.toggle}
+          </span>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+// ---- SearchTrigger — drop-in button for top bars ----
+//
+// Renders a fake "input" that looks like the search field but is a
+// real button. Click → caller toggles the modal. Keeps the topbar
+// visually consistent across breakpoints while making the modal the
+// single search surface.
+
+interface SearchTriggerProps {
+  readonly onClick: () => void
+  readonly placeholder?: string
+  /** `aria-label` for the trigger button. Default `'Open search'`. */
+  readonly openLabel?: string
+  readonly className?: string
+}
+
+export const SearchTrigger = ({
+  onClick, placeholder = 'Search docs…', openLabel = 'Open search', className,
+}: SearchTriggerProps): ReactNode => (
+  <button
+    type="button"
+    onClick={onClick}
+    aria-label={openLabel}
+    className={cn(
+      'inline-flex items-center gap-2 rounded-md border border-border bg-card/40 px-2.5 py-1.5 text-sm text-muted-foreground hover:text-foreground hover:border-input transition-colors w-56 lg:w-64',
+      className,
+    )}
+  >
+    <SearchIcon className="w-4 h-4 shrink-0" />
+    <span className="flex-1 text-left truncate">{placeholder}</span>
+    <kbd className="text-[0.65rem] border border-border rounded px-1 py-0.5 font-mono hidden lg:inline-block">⌘K</kbd>
+  </button>
+)

package/src/primitives/select.tsx

@@ -0,0 +1,24 @@
+// shadcn Select — native <select> styled with theme tokens.
+// Drops Radix Select's custom menu in V1 for zero JS + native a11y;
+// upgrade to Radix when you need search-within-options or rich
+// option content.
+
+import type { SelectHTMLAttributes, ReactNode } from 'react'
+import { cn } from '../cn'
+
+export const Select = ({ className, children, ...props }: SelectHTMLAttributes<HTMLSelectElement>): ReactNode => (
+  <select
+    data-slot="select"
+    className={cn(
+      'flex h-9 w-full rounded-md border bg-transparent px-3 py-1 text-sm shadow-xs',
+      'transition-[color,box-shadow] outline-none cursor-pointer',
+      'dark:bg-input/30',
+      'disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50',
+      'focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]',
+      className,
+    )}
+    {...props}
+  >
+    {children}
+  </select>
+)

package/src/primitives/separator.tsx

@@ -0,0 +1,24 @@
+// shadcn Separator — horizontal / vertical rule.
+
+import type { HTMLAttributes, ReactNode } from 'react'
+import { cn } from '../cn'
+
+interface SeparatorProps extends HTMLAttributes<HTMLDivElement> {
+  readonly orientation?: 'horizontal' | 'vertical'
+}
+
+export const Separator = ({
+  className, orientation = 'horizontal', ...props
+}: SeparatorProps): ReactNode => (
+  <div
+    data-slot="separator"
+    role="separator"
+    aria-orientation={orientation}
+    className={cn(
+      'bg-border shrink-0',
+      orientation === 'horizontal' ? 'h-px w-full' : 'h-full w-px',
+      className,
+    )}
+    {...props}
+  />
+)

package/src/primitives/skeleton.tsx

@@ -0,0 +1,12 @@
+// shadcn Skeleton — pulsing placeholder block for loading states.
+
+import type { HTMLAttributes, ReactNode } from 'react'
+import { cn } from '../cn'
+
+export const Skeleton = ({ className, ...props }: HTMLAttributes<HTMLDivElement>): ReactNode => (
+  <div
+    data-slot="skeleton"
+    className={cn('animate-pulse rounded-md bg-muted', className)}
+    {...props}
+  />
+)