@voltro/ui-shadcn 0.1.0

package/src/primitives/sparkles.tsx

@@ -0,0 +1,105 @@
+// Sparkles — restrained particle field for hero / opener backdrops.
+//
+// Design goals:
+//   - Professional, NOT playful. No rainbow, no big glittery stars,
+//     no chaotic motion. Tiny brand-tinted dots that fade in and out
+//     out of phase — reads as "atmosphere", not "Christmas tree".
+//   - SSR-safe: positions / sizes / delays derive deterministically
+//     from the index, so server-rendered HTML matches the first
+//     client render (no hydration mismatch, no re-shuffle on each
+//     render).
+//   - Pointer-events off, aria-hidden — purely decorative.
+//   - Respects prefers-reduced-motion: the `motion-safe:` variant on
+//     the twinkle animation means each dot freezes at opacity 0 when
+//     the user has reduced motion enabled.
+//
+// Drop this absolute-fill inside any container (hero, section, card)
+// and it covers the parent. Tune via `count`, `tone`, `intensity`.
+
+import type { ReactNode } from 'react'
+import { cn } from '../cn'
+
+interface SparklesProps {
+  /** How many dots to render. Default 22. Sweet spot is 16–28 —
+   *  fewer feels accidental, more starts to feel busy. */
+  readonly count?: number
+  /** Brand mode. Cool = violet/cyan accents (default); warm = amber/rose. */
+  readonly tone?: 'cool' | 'warm'
+  /** Density tier. `'subtle'` is the default and what most heros want;
+   *  `'normal'` bumps the max-opacity peak a bit; `'strong'` makes
+   *  the field more obvious. Each tier still respects the
+   *  "professional, not playful" budget. */
+  readonly intensity?: 'subtle' | 'normal' | 'strong'
+  readonly className?: string
+}
+
+// Two prime-ish multipliers per axis. Spreads positions evenly across
+// the container without lining up on a grid. Picked by eye — change
+// only if you want a different distribution.
+const FREQ_X = 137.5
+const FREQ_Y = 73.13
+
+const INTENSITY_OPACITY: Record<NonNullable<SparklesProps['intensity']>, string> = {
+  subtle: 'opacity-50',
+  normal: 'opacity-75',
+  strong: 'opacity-100',
+}
+
+export const Sparkles = ({
+  count = 22, tone = 'cool', intensity = 'subtle', className,
+}: SparklesProps): ReactNode => {
+  // Dot CORE is near-white so it pops against the brand-tinted
+  // MeshBackdrop blobs (those use the same violet/cyan and would
+  // swallow same-coloured dots). The HALO is brand-tinted — that's
+  // what visually anchors the sparkle to the rest of the palette
+  // without coloring the dot itself.
+  const haloColors = tone === 'warm'
+    ? ['oklch(0.78 0.16 60)', 'oklch(0.72 0.18 25)']
+    : ['oklch(0.78 0.18 290)', 'oklch(0.74 0.16 220)']
+
+  return (
+    <div
+      aria-hidden="true"
+      className={cn(
+        'absolute inset-0 overflow-hidden pointer-events-none',
+        INTENSITY_OPACITY[intensity],
+        className,
+      )}
+    >
+      {Array.from({ length: count }, (_, i) => {
+        // Deterministic pseudo-random spread — golden-ratio-ish step
+        // around 0..100% per axis.
+        const x = (i * FREQ_X) % 100
+        const y = (i * FREQ_Y) % 100
+        // 2-4px diameter — small enough to read as a particle, not as
+        // a hit-target.
+        const size = 2 + (i % 3)
+        // Stagger the twinkle so the field never blinks in unison.
+        const delay = (i * 0.42) % 6
+        const halo = haloColors[i % haloColors.length]!
+        return (
+          <span
+            key={i}
+            className="absolute rounded-full motion-safe:animate-twinkle"
+            style={{
+              left: `${x}%`,
+              top: `${y}%`,
+              width: `${size}px`,
+              height: `${size}px`,
+              // Near-white core gives the dot contrast against any
+              // backdrop colour — that's what makes it actually read
+              // as a sparkle and not vanish into the mesh blobs.
+              backgroundColor: 'oklch(0.98 0 0)',
+              // Two-stop halo: tight bright ring at 1× size, soft
+              // brand-tinted bloom at 4× size. The double shadow is
+              // what gives sparkles their characteristic "spark"
+              // glow vs a flat dot with a single blur.
+              boxShadow: `0 0 ${size}px oklch(0.98 0 0), 0 0 ${size * 4}px ${halo}`,
+              animationDelay: `${delay}s`,
+            }}
+          />
+        )
+      })}
+    </div>
+  )
+}

package/src/primitives/steps.tsx

@@ -0,0 +1,55 @@
+// Steps — numbered vertical list for tutorials / install guides.
+// Renders children as a column with a connecting line on the left
+// and an auto-incrementing badge for each direct child.
+//
+// Usage:
+//   <Steps>
+//     <Step title="Install the CLI">
+//       <CodeBlock code="pnpm add -g voltro" />
+//     </Step>
+//     <Step title="Create a project">
+//       …
+//     </Step>
+//   </Steps>
+
+import { Children, isValidElement, type ReactNode } from 'react'
+import { cn } from '../cn'
+
+interface StepsProps {
+  readonly children: ReactNode
+  readonly className?: string
+}
+
+interface StepProps {
+  readonly title?: ReactNode
+  readonly children: ReactNode
+  readonly className?: string
+}
+
+export const Steps = ({ children, className }: StepsProps): ReactNode => {
+  // Inject 1-based index into each <Step> via a positional prop. We
+  // could clone with React.cloneElement, but a CSS counter is simpler
+  // + survives Suspense boundaries.
+  const items = Children.toArray(children).filter(isValidElement)
+  return (
+    <ol className={cn('not-prose my-6 ml-3 space-y-6 border-l border-border', className)}>
+      {items.map((child, i) => (
+        <li key={i} className="relative pl-8">
+          <div className="absolute left-0 top-0 -translate-x-1/2 w-6 h-6 rounded-full bg-card border border-border text-xs font-semibold text-foreground inline-flex items-center justify-center">
+            {i + 1}
+          </div>
+          {child}
+        </li>
+      ))}
+    </ol>
+  )
+}
+
+export const Step = ({ title, children, className }: StepProps): ReactNode => (
+  <div className={cn('-mt-1', className)}>
+    {title ? <h3 className="text-base font-semibold text-foreground mb-2">{title}</h3> : null}
+    <div className="text-sm text-muted-foreground leading-relaxed space-y-2">
+      {children}
+    </div>
+  </div>
+)

package/src/primitives/tabs.tsx

@@ -0,0 +1,102 @@
+// shadcn Tabs — CSS-only with the :target trick OR a tiny client
+// state hook. V1 ships a controlled component using React state;
+// island-eligible. Apps wanting zero-JS tabs use the :target form
+// (anchor-based) which we don't ship as a primitive yet.
+
+import {
+  createContext, useContext, useState,
+  type HTMLAttributes, type ReactNode,
+} from 'react'
+import { cn } from '../cn'
+
+interface TabsContextValue {
+  readonly value: string
+  readonly setValue: (v: string) => void
+}
+const TabsContext = createContext<TabsContextValue | null>(null)
+
+interface TabsProps extends HTMLAttributes<HTMLDivElement> {
+  readonly defaultValue: string
+  readonly value?: string
+  readonly onValueChange?: (v: string) => void
+}
+
+export const Tabs = ({
+  defaultValue, value, onValueChange, className, children, ...props
+}: TabsProps): ReactNode => {
+  const [uncontrolled, setUncontrolled] = useState(defaultValue)
+  const current = value ?? uncontrolled
+  const setValue = (v: string): void => {
+    if (value === undefined) setUncontrolled(v)
+    onValueChange?.(v)
+  }
+  return (
+    <TabsContext.Provider value={{ value: current, setValue }}>
+      <div data-slot="tabs" className={cn('flex flex-col gap-2', className)} {...props}>
+        {children}
+      </div>
+    </TabsContext.Provider>
+  )
+}
+
+export const TabsList = ({ className, ...props }: HTMLAttributes<HTMLDivElement>): ReactNode => (
+  <div
+    data-slot="tabs-list"
+    role="tablist"
+    className={cn(
+      'inline-flex h-9 w-fit items-center justify-center rounded-lg bg-muted text-muted-foreground p-1',
+      className,
+    )}
+    {...props}
+  />
+)
+
+interface TabsTriggerProps extends HTMLAttributes<HTMLButtonElement> {
+  readonly value: string
+}
+
+export const TabsTrigger = ({ value, className, children, ...props }: TabsTriggerProps): ReactNode => {
+  const ctx = useContext(TabsContext)
+  if (!ctx) throw new Error('TabsTrigger must be inside <Tabs>')
+  const active = ctx.value === value
+  return (
+    <button
+      data-slot="tabs-trigger"
+      role="tab"
+      type="button"
+      aria-selected={active}
+      onClick={() => ctx.setValue(value)}
+      className={cn(
+        'inline-flex items-center justify-center whitespace-nowrap rounded-md px-3 py-1 text-sm font-medium transition-all',
+        'focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50',
+        active
+          ? 'bg-background text-foreground shadow-sm'
+          : 'hover:text-foreground',
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </button>
+  )
+}
+
+interface TabsContentProps extends HTMLAttributes<HTMLDivElement> {
+  readonly value: string
+}
+
+export const TabsContent = ({ value, className, children, ...props }: TabsContentProps): ReactNode => {
+  const ctx = useContext(TabsContext)
+  if (!ctx) throw new Error('TabsContent must be inside <Tabs>')
+  if (ctx.value !== value) return null
+  return (
+    <div
+      data-slot="tabs-content"
+      role="tabpanel"
+      className={cn('flex-1 outline-none', className)}
+      {...props}
+    >
+      {children}
+    </div>
+  )
+}

package/src/primitives/textarea.tsx

@@ -0,0 +1,24 @@
+// shadcn-style Textarea — multi-line sibling of <Input>. Used by the
+// data viewer's JSON cell editor (pass `className="font-mono"` for code).
+
+import type { TextareaHTMLAttributes, ReactNode } from 'react'
+import { cn } from '../cn'
+
+export const Textarea = ({ className, ...props }: TextareaHTMLAttributes<HTMLTextAreaElement>): ReactNode => (
+  <textarea
+    data-slot="textarea"
+    className={cn(
+      'flex min-h-16 w-full rounded-md border bg-transparent px-3 py-2 text-base shadow-xs',
+      'transition-[color,box-shadow] outline-none',
+      'placeholder:text-muted-foreground',
+      'selection:bg-primary selection:text-primary-foreground',
+      'dark:bg-input/30',
+      'disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50',
+      'md:text-sm',
+      'focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]',
+      'aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive',
+      className,
+    )}
+    {...props}
+  />
+)

package/src/primitives/toast.tsx

@@ -0,0 +1,44 @@
+// shadcn Toast — minimal CSS-driven; appears bottom-right when the
+// `[data-state="open"]` attribute is on the root. Apps set + clear
+// the attribute via tiny client JS or via form-redirect query
+// params (`?toast=saved`). Sonner is the canonical shadcn dep —
+// drop in when richer behaviour matters.
+
+import type { HTMLAttributes, ReactNode } from 'react'
+import { cn } from '../cn'
+
+interface ToastProps extends HTMLAttributes<HTMLDivElement> {
+  readonly variant?: 'default' | 'destructive' | 'success'
+}
+
+const variantClasses = {
+  default:     'bg-card text-card-foreground border',
+  destructive: 'bg-destructive text-white border-destructive',
+  success:     'bg-emerald-600 text-white border-emerald-600',
+} as const
+
+export const Toast = ({ variant = 'default', className, children, ...props }: ToastProps): ReactNode => (
+  <div
+    data-slot="toast"
+    role="status"
+    aria-live="polite"
+    className={cn(
+      'fixed bottom-4 right-4 z-50 max-w-md rounded-md border shadow-lg p-4',
+      'data-[state=closed]:hidden',
+      'data-[state=open]:animate-in data-[state=open]:slide-in-from-bottom-2 data-[state=open]:fade-in-0',
+      variantClasses[variant],
+      className,
+    )}
+    {...props}
+  >
+    {children}
+  </div>
+)
+
+export const ToastTitle = ({ className, ...props }: HTMLAttributes<HTMLParagraphElement>): ReactNode => (
+  <p data-slot="toast-title" className={cn('text-sm font-semibold', className)} {...props} />
+)
+
+export const ToastDescription = ({ className, ...props }: HTMLAttributes<HTMLParagraphElement>): ReactNode => (
+  <p data-slot="toast-description" className={cn('text-sm opacity-90', className)} {...props} />
+)

package/src/primitives/tocScrollSpy.tsx

@@ -0,0 +1,110 @@
+// TocScrollSpy — small client-side island that highlights the active
+// TOC link as the user scrolls past the corresponding heading.
+//
+// The DocsLayout renders a static TOC; this island runs in the
+// browser, watches the current h2/h3 headings in the page content,
+// and toggles `data-active` on the matching `[data-toc-link]`.
+// Pure side-effect — no UI of its own.
+//
+// Why this lives as a separate primitive: the DocsLayout itself
+// stays SSR-safe and stateless; the scroll spy needs window APIs.
+// Apps render this once near the top of their page tree (inside the
+// layout, but conditionally — only mount when there IS a TOC).
+
+import { useEffect, type ReactNode } from 'react'
+
+interface TocScrollSpyProps {
+  /** CSS selector for the content container holding the headings.
+   *  Defaults to `main` since the layout's content lives there. */
+  readonly contentSelector?: string
+}
+
+export const TocScrollSpy = ({ contentSelector = 'main' }: TocScrollSpyProps): ReactNode => {
+  useEffect(() => {
+    const main = document.querySelector<HTMLElement>(contentSelector)
+    if (!main) return
+
+    let headings: HTMLElement[] = []
+    let frame: number | null = null
+
+    let active: string | null = null
+    const tocLinks = (): HTMLElement[] =>
+      Array.from(document.querySelectorAll<HTMLElement>('[data-toc-link]'))
+
+    const tocLinkFor = (id: string): HTMLElement | null =>
+      tocLinks().find((link) => link.dataset.tocLink === id) ?? null
+
+    const setActive = (id: string | null): void => {
+      if (id === active) return
+
+      for (const prev of tocLinks()) {
+        prev?.removeAttribute('data-active')
+        prev?.removeAttribute('aria-current')
+      }
+
+      active = id
+      if (id) {
+        const next = tocLinkFor(id)
+        next?.setAttribute('data-active', 'true')
+        next?.setAttribute('aria-current', 'location')
+      }
+    }
+
+    const updateActive = (): void => {
+      frame = null
+      if (headings.length === 0) {
+        setActive(null)
+        return
+      }
+
+      // A stable reading line just below the sticky header. Pick the
+      // last heading that has crossed it; before the first heading, keep
+      // the first TOC item active so the sidebar never looks inert.
+      const readingLine = Math.min(180, Math.max(96, window.innerHeight * 0.24))
+      let current = headings[0]?.id ?? null
+
+      for (const heading of headings) {
+        if (heading.getBoundingClientRect().top <= readingLine) {
+          current = heading.id
+        } else {
+          break
+        }
+      }
+
+      const scrollBottom = window.scrollY + window.innerHeight
+      const docBottom = document.documentElement.scrollHeight
+      if (docBottom - scrollBottom < 2) current = headings[headings.length - 1]?.id ?? current
+
+      setActive(current)
+    }
+
+    const scheduleUpdate = (): void => {
+      if (frame !== null) return
+      frame = window.requestAnimationFrame(updateActive)
+    }
+
+    const collectHeadings = (): void => {
+      headings = Array.from(main.querySelectorAll<HTMLElement>('h2[id], h3[id]'))
+      active = null
+      scheduleUpdate()
+    }
+
+    collectHeadings()
+
+    const observer = new MutationObserver(collectHeadings)
+    observer.observe(main, { childList: true, subtree: true })
+    window.addEventListener('scroll', scheduleUpdate, { passive: true })
+    window.addEventListener('resize', scheduleUpdate)
+    window.addEventListener('hashchange', scheduleUpdate)
+
+    return () => {
+      observer.disconnect()
+      window.removeEventListener('scroll', scheduleUpdate)
+      window.removeEventListener('resize', scheduleUpdate)
+      window.removeEventListener('hashchange', scheduleUpdate)
+      if (frame !== null) window.cancelAnimationFrame(frame)
+    }
+  }, [contentSelector])
+
+  return null
+}

package/src/primitives/toggle.tsx

@@ -0,0 +1,50 @@
+// shadcn Toggle — Radix wrapper, token-styled. Building block for
+// <ToggleGroup>; usable standalone as a 2-state press button (e.g.
+// "Bold" / "Italic" formatting toggles).
+
+import {
+  forwardRef,
+  type ComponentPropsWithoutRef,
+  type ComponentRef,
+} from 'react'
+import * as RT from '@radix-ui/react-toggle'
+import { cva, type VariantProps } from 'class-variance-authority'
+import { cn } from '../cn'
+
+export const toggleVariants = cva(
+  // Base shared with shadcn's official toggle: same focus + disabled
+  // + svg sizing tokens as <Button>.
+  "inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium " +
+  "transition-colors hover:bg-muted hover:text-muted-foreground " +
+  "disabled:pointer-events-none disabled:opacity-50 " +
+  "data-[state=on]:bg-accent data-[state=on]:text-accent-foreground " +
+  "[&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 [&_svg]:shrink-0 " +
+  "outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50 focus-visible:border-ring " +
+  "cursor-pointer",
+  {
+    variants: {
+      variant: {
+        default: 'bg-transparent',
+        outline: 'border border-input bg-transparent shadow-xs hover:bg-accent hover:text-accent-foreground',
+      },
+      size: {
+        default: 'h-9 px-2 min-w-9',
+        sm:      'h-8 px-2 min-w-8',
+        lg:      'h-10 px-2.5 min-w-10',
+      },
+    },
+    defaultVariants: { variant: 'default', size: 'default' },
+  },
+)
+
+export const Toggle = forwardRef<
+  ComponentRef<typeof RT.Root>,
+  ComponentPropsWithoutRef<typeof RT.Root> & VariantProps<typeof toggleVariants>
+>(({ className, variant, size, ...props }, ref) => (
+  <RT.Root
+    ref={ref}
+    className={cn(toggleVariants({ variant, size, className }))}
+    {...props}
+  />
+))
+Toggle.displayName = 'Toggle'

package/src/primitives/toggleGroup.tsx

@@ -0,0 +1,62 @@
+// shadcn ToggleGroup — Radix wrapper. Group of <Toggle>s sharing a
+// single (`type="single"`) or multiple-selection (`type="multiple"`)
+// state. Used in ProfileMenu for the inline theme + language chip
+// rows; usable anywhere a small chip-radio is the right primitive.
+//
+// Variants + size flow down via React Context so individual items
+// don't need to re-declare them — mirrors shadcn's reference.
+
+import {
+  createContext, forwardRef, useContext,
+  type ComponentPropsWithoutRef,
+  type ComponentRef,
+} from 'react'
+import * as RTG from '@radix-ui/react-toggle-group'
+import { type VariantProps } from 'class-variance-authority'
+import { cn } from '../cn'
+import { toggleVariants } from './toggle'
+
+type ToggleGroupVariants = VariantProps<typeof toggleVariants>
+
+const ToggleGroupContext = createContext<ToggleGroupVariants>({
+  variant: 'default', size: 'default',
+})
+
+export const ToggleGroup = forwardRef<
+  ComponentRef<typeof RTG.Root>,
+  ComponentPropsWithoutRef<typeof RTG.Root> & ToggleGroupVariants
+>(({ className, variant, size, children, ...props }, ref) => (
+  <RTG.Root
+    ref={ref}
+    className={cn('inline-flex items-center gap-1', className)}
+    {...props}
+  >
+    <ToggleGroupContext.Provider value={{ variant, size }}>
+      {children}
+    </ToggleGroupContext.Provider>
+  </RTG.Root>
+))
+ToggleGroup.displayName = 'ToggleGroup'
+
+export const ToggleGroupItem = forwardRef<
+  ComponentRef<typeof RTG.Item>,
+  ComponentPropsWithoutRef<typeof RTG.Item> & ToggleGroupVariants
+>(({ className, variant, size, children, ...props }, ref) => {
+  const ctx = useContext(ToggleGroupContext)
+  return (
+    <RTG.Item
+      ref={ref}
+      className={cn(
+        toggleVariants({
+          variant: variant ?? ctx.variant,
+          size:    size    ?? ctx.size,
+        }),
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </RTG.Item>
+  )
+})
+ToggleGroupItem.displayName = 'ToggleGroupItem'