) } function ConversationScrollButton({ className, ...props }: React.ComponentProps) { const { isAtBottom, scrollToBottom } = useConversation() return ( {!isAtBottom && ( )} ) } function ConversationEmpty({ className, title = "Start a conversation", description, icon, children, ...props }: React.ComponentProps<"div"> & { title?: string; description?: string; icon?: React.ReactNode }) { return (

{icon &&

{icon}

}

{title}

{description &&

{description}

}

{children}

) } export { Conversation, ConversationContent, ConversationScrollButton, ConversationEmpty, useConversation } ``` ### hooks/use-stick-to-bottom.ts ```ts "use client" import * as React from "react" /** * Keeps a scroll container pinned to the bottom while content grows (streaming), * and releases the pin as soon as the user scrolls up. */ export function useStickToBottom(threshold = 48) { const scrollRef = React.useRef(null) const contentRef = React.useRef(null) const pinned = React.useRef(true) const [isAtBottom, setIsAtBottom] = React.useState(true) const scrollToBottom = React.useCallback((behavior: ScrollBehavior = "smooth") => { const el = scrollRef.current if (!el) return pinned.current = true el.scrollTo({ top: el.scrollHeight, behavior }) }, []) React.useEffect(() => { const el = scrollRef.current if (!el) return const onScroll = () => { const atBottom = el.scrollHeight - el.scrollTop - el.clientHeight <= threshold pinned.current = atBottom setIsAtBottom(atBottom) } el.addEventListener("scroll", onScroll, { passive: true }) return () => el.removeEventListener("scroll", onScroll) }, [threshold]) React.useEffect(() => { const content = contentRef.current if (!content) return const observer = new ResizeObserver(() => { if (pinned.current) scrollToBottom("instant") }) observer.observe(content) return () => observer.disconnect() }, [scrollToBottom]) return { scrollRef, contentRef, isAtBottom, scrollToBottom } } ``` --- # Message A single turn from the user or the assistant, with hover-revealed actions. Docs: https://jds-ruddy.vercel.app/docs/components/message ## Installation ```bash npx shadcn@latest add @jds/message ``` npm dependencies: `cn`, `motion` Also installs: `@jds/avatar`, `@jds/button`, `@jds/tooltip`, `@jds/utils` ## Usage ```tsx import { Message, MessageContent } from "@/components/ai/message" Summarize this thread. ``` ## Example ```tsx "use client" import { toast } from "sonner" import { Message, MessageAction, MessageActions, MessageAvatar, MessageContent } from "@/components/ai/message" import { CopyIcon, RegenerateIcon, ThumbsDownIcon, ThumbsUpIcon } from "@/lib/icons" export default function MessageDemo() { return (

Can you shorten this paragraph?

Sure. Shipping is free over €50 and takes two to four working days.

toast("Copied")}>

) } ``` ## API Reference ### Message | Prop | Type | Default | Description | | --- | --- | --- | --- | | `from` | `"user" \| "assistant" \| "system"` | | Sets alignment and bubble style. | ### MessageStyleProvider | Prop | Type | Default | Description | | --- | --- | --- | --- | | `bubbles` | `"user" \| "all" \| "none"` | `"user"` | Who gets a bubble. For messages outside a Conversation. | | `shape` | `"tail" \| "round" \| "square"` | `"tail"` | Bubble corners: a tail toward the speaker, fully round, or squarer. | | `density` | `"comfortable" \| "compact"` | `"comfortable"` | Spacing between and inside messages. Compact suits side panels. | ### MessageAction | Prop | Type | Default | Description | | --- | --- | --- | --- | | `label` | `string` | | Accessible name and tooltip text. | ## Source ### components/ai/message.tsx ```tsx "use client" import * as React from "react" import { motion, type HTMLMotionProps } from "motion/react" import { cn } from "cn" import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar" import { Button } from "@/components/ui/button" import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip" import { rise } from "@/lib/motion" type MessageRole = "user" | "assistant" | "system" /** * How messages look across a conversation. Set it once on (or with * ); every Message inside follows. Defaults are the classic chat look: * the user in a bubble with a tail corner, the assistant as plain text. */ type MessageStyle = { /** Who gets a bubble. */ bubbles?: "user" | "all" | "none" /** Bubble corners: a tail toward the speaker, fully round, or squarer. */ shape?: "tail" | "round" | "square" density?: "comfortable" | "compact" } const MessageStyleContext = React.createContext>({ bubbles: "user", shape: "tail", density: "comfortable", }) function MessageStyleProvider({ children, ...style }: MessageStyle & { children: React.ReactNode }) { const parent = React.useContext(MessageStyleContext) const { bubbles = parent.bubbles, shape = parent.shape, density = parent.density } = style const value = React.useMemo(() => ({ bubbles, shape, density }), [bubbles, shape, density]) return {children} } const useMessageStyle = () => React.useContext(MessageStyleContext) const MessageContext = React.createContext<{ from: MessageRole }>({ from: "assistant" }) const corners = { tail: { user: "rounded-2xl rounded-tr-md", assistant: "rounded-2xl rounded-tl-md" }, round: { user: "rounded-2xl", assistant: "rounded-2xl" }, square: { user: "rounded-lg", assistant: "rounded-lg" }, } function Message({ from, className, ...props }: HTMLMotionProps<"div"> & { from: MessageRole }) { return ( ) } function MessageContent({ className, ...props }: React.ComponentProps<"div">) { const { from } = React.useContext(MessageContext) const { bubbles, shape, density } = useMessageStyle() const user = from === "user" const bubble = bubbles === "all" || (bubbles === "user" && user) return (

) } function MessageAvatar({ src, name, className, ...props }: React.ComponentProps & { src?: string; name: string }) { return ( {src && } {name.slice(0, 2).toUpperCase()} ) } /** Hover-revealed row of actions under a message (copy, regenerate, feedback). */ function MessageActions({ className, ...props }: React.ComponentProps<"div">) { return (

) } function MessageAction({ label, className, ...props }: React.ComponentProps & { label: string }) { return ( } /> {label} ) } export { Message, MessageContent, MessageAvatar, MessageActions, MessageAction, MessageStyleProvider, useMessageStyle, type MessageRole, type MessageStyle, } ``` --- # Command Bar A ⌘K palette that also asks the agent. Typing filters commands; the Ask row turns the same text into a question, and the answer replaces the list until Escape. Choose whether Enter asks or runs a command. Docs: https://jds-ruddy.vercel.app/docs/components/command-bar ## Installation ```bash npx shadcn@latest add @jds/command-bar ``` npm dependencies: `cn` Also installs: `@jds/command`, `@jds/dialog`, `@jds/kbd`, `@jds/utils` ## Usage ```tsx import { CommandBar, CommandBarAnswer, CommandBarAsk, CommandBarDialog, CommandBarFooter, CommandBarInput, CommandBarList, } from "@/components/ai/command-bar" import { CommandGroup, CommandItem } from "@/components/ui/command" sendMessage({ text: question })}> New invoice Continue in chat}> {answer} ``` ## Example ```tsx "use client" import * as React from "react" import { toast } from "sonner" import { CommandBar, CommandBarAnswer, CommandBarAsk, CommandBarFooter, CommandBarInput, CommandBarList, } from "@/components/ai/command-bar" import { Response } from "@/components/ai/response" import { Button } from "@/components/ui/button" import { CommandGroup, CommandItem, CommandShortcut } from "@/components/ui/command" import { AddIcon, ChartIcon, FileIcon, SettingsIcon, SparkleIcon } from "@/lib/icons" const ANSWER = "Revenue is **€48.2k** this month, up 12% on last month. Most of the growth came from annual plans; monthly churn is flat." /** Streams a canned answer word by word, the way a model reply arrives. */ function useFakeAnswer() { const [text, setText] = React.useState("") const run = React.useRef(0) const start = async () => { const id = ++run.current setText("") let out = "" for (const w of ANSWER.split(/(\s+)/)) { await new Promise((r) => setTimeout(r, 25)) if (run.current !== id) return out += w setText(out) } } const cancel = () => { run.current++ setText("") } return { text, start, cancel } } export default function CommandBarDemo() { const answer = useFakeAnswer() return ( toast("Summarizing…")}> Summarize this page toast("Drafting…")}> Draft a reply to the latest email New invoice ⌘N Open revenue report Settings ⌘, } > {answer.text} ) } ``` ## API Reference ### CommandBar | Prop | Type | Default | Description | | --- | --- | --- | --- | | `onAsk` | `(question: string) => void` | | Called when someone asks. Stream the reply into CommandBarAnswer. | | `onBack` | `() => void` | | Called when leaving the answer, e.g. to cancel a stream. | ### CommandBarAsk | Prop | Type | Default | Description | | --- | --- | --- | --- | | `label` | `string` | `"Ask AI"` | Row text before the question. Place the row before your groups to make Enter ask, after them to make Enter run the best-matching command. | ### CommandBarAnswer | Prop | Type | Default | Description | | --- | --- | --- | --- | | `actions` | `ReactNode` | | Buttons under the answer, like Copy or Continue in chat. | ### CommandBarDialog | Prop | Type | Default | Description | | --- | --- | --- | --- | | `hotkey` | `string \| false` | `"k"` | Toggles with ⌘ or Ctrl plus this key. | | `open` | `boolean` | | Controlled open state. Leave out to let the hotkey manage it. | ## Source ### components/ai/command-bar.tsx ```tsx "use client" import * as React from "react" import { cn } from "cn" import { Command, CommandGroup, CommandInput, CommandItem, CommandList, CommandShortcut, } from "@/components/ui/command" import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle } from "@/components/ui/dialog" import { Kbd } from "@/components/ui/kbd" import { SparkleIcon } from "@/lib/icons" type CommandBarContextValue = { query: string setQuery: (query: string) => void /** The question being answered, or null while browsing commands. */ question: string | null ask: (question: string) => void back: () => void } const CommandBarContext = React.createContext(null) function useCommandBar() { const ctx = React.useContext(CommandBarContext) if (!ctx) throw new Error("CommandBar parts must be used inside ") return ctx } /** * A command palette that also asks the agent. Typing filters commands as usual; the * row turns the same text into a question. Place it before your groups and * Enter asks; after them and Enter runs the best-matching command. While answering, * replaces the list and Escape goes back to it. */ function CommandBar({ onAsk, onBack, className, children, onKeyDown, ...props }: React.ComponentProps & { /** Called with the question when someone asks. Stream your answer into . */ onAsk?: (question: string) => void /** Called when leaving the answer to browse commands again. */ onBack?: () => void }) { const [query, setQuery] = React.useState("") const [question, setQuestion] = React.useState(null) const value = React.useMemo( () => ({ query, setQuery, question, ask: (q) => { if (!q.trim()) return setQuestion(q.trim()) onAsk?.(q.trim()) }, back: () => { setQuestion(null) onBack?.() }, }), [query, question, onAsk, onBack], ) return ( { onKeyDown?.(e) // Escape backs out of an answer before it closes anything around the bar. if (e.key === "Escape" && question !== null) { e.preventDefault() e.stopPropagation() value.back() } }} // h-auto: size to content; the base command fills its container, which suits a dialog but not a bar. className={cn("h-auto rounded-xl! border shadow-2xl", className)} {...props} > {children} ) } function CommandBarInput({ placeholder = "Search or ask anything…", ...props }: Omit, "value" | "onValueChange">) { const { query, setQuery, question, back } = useCommandBar() return ( { setQuery(v) // Editing the text after asking returns to the list, so it can become a new search or question. if (question !== null) back() }} placeholder={placeholder} {...props} /> ) } /** The list of commands. Hidden, not unmounted, while an answer shows, so commands stay registered. */ function CommandBarList(props: React.ComponentProps) { const { question } = useCommandBar() return } /** * "Ask AI" row: shows once something is typed and always matches, since its value contains * the query. It sits in its own group, and cmdk keeps groups in the order you write them, so * placing it before your groups makes Enter ask and placing it after makes Enter run the * best-matching command. */ function CommandBarAsk({ label = "Ask AI", className }: { label?: string; className?: string }) { const { query, ask } = useCommandBar() if (!query.trim()) return null return ( ask(query)} className={className}> {label}: “{query.trim()}” ↵ ) } /** The agent's answer, shown in place of the list after asking. `actions` sits under it. */ function CommandBarAnswer({ actions, className, children, }: { actions?: React.ReactNode className?: string children: React.ReactNode }) { const { question } = useCommandBar() if (question === null) return null return (

{question}

{children}

{actions &&

{actions}

}

) } /** Keyboard hints along the bottom. Adapts to answer mode; `children` adds more on the right. */ function CommandBarFooter({ className, children }: { className?: string; children?: React.ReactNode }) { const { question } = useCommandBar() return (

{question === null ? ( <> ↑↓navigate ↵select ) : ( escback to commands )} {children}

) } /** * The bar in a dialog that opens with ⌘K (Ctrl+K elsewhere). Controlled with `open`, or * self-managed when left out. */ function CommandBarDialog({ open: controlled, onOpenChange, hotkey = "k", title = "Command bar", className, children, }: { open?: boolean onOpenChange?: (open: boolean) => void /** The letter that toggles it with ⌘ or Ctrl. Set to false to turn the shortcut off. */ hotkey?: string | false title?: string className?: string children: React.ReactNode }) { const [uncontrolled, setUncontrolled] = React.useState(false) const open = controlled ?? uncontrolled const setOpen = React.useCallback( (next: boolean) => { if (controlled === undefined) setUncontrolled(next) onOpenChange?.(next) }, [controlled, onOpenChange], ) React.useEffect(() => { if (!hotkey) return const onKey = (e: KeyboardEvent) => { if (e.key.toLowerCase() === hotkey && (e.metaKey || e.ctrlKey)) { e.preventDefault() setOpen(!open) } } window.addEventListener("keydown", onKey) return () => window.removeEventListener("keydown", onKey) }, [hotkey, open, setOpen]) return ( ) } export { CommandBar, CommandBarAnswer, CommandBarAsk, CommandBarDialog, CommandBarFooter, CommandBarInput, CommandBarList, useCommandBar, } ``` --- # Prompt Input Composer for chat and agent apps. Enter to send, Shift+Enter for a new line, paste or drop files, stop while streaming. Docs: https://jds-ruddy.vercel.app/docs/components/prompt-input ## Installation ```bash npx shadcn@latest add @jds/prompt-input ``` npm dependencies: `@base-ui/react`, `cn`, `motion` Also installs: `@jds/button`, `@jds/utils` ## Usage ```tsx import { PromptInput, PromptInputSubmit, PromptInputTextarea, PromptInputToolbar, PromptInputTools, PromptInputAttachButton, PromptInputAttachments, } from "@/components/ai/prompt-input" const { status, sendMessage, stop } = useChat() sendMessage({ text, files })}> ``` ## Example ```tsx "use client" import * as React from "react" import { toast } from "sonner" import { PromptInput, PromptInputAttachButton, PromptInputAttachments, PromptInputSubmit, PromptInputTextarea, PromptInputToolbar, PromptInputTools, type ChatStatus, } from "@/components/ai/prompt-input" export default function PromptInputDemo() { const [status, setStatus] = React.useState("ready") const timer = React.useRef>(undefined) return ( { toast(`Sent: ${text || `${files.length} file(s)`}`) setStatus("submitted") timer.current = setTimeout(() => { setStatus("streaming") timer.current = setTimeout(() => setStatus("ready"), 2500) }, 800) }} > { clearTimeout(timer.current) setStatus("ready") }} /> ) } ``` ### With context and options ```tsx "use client" import * as React from "react" import { toast } from "sonner" import { PromptInput, PromptInputAttachButton, PromptInputFooter, PromptInputFrame, PromptInputHeader, PromptInputOption, PromptInputSubmit, PromptInputTextarea, PromptInputToolbar, PromptInputTools, } from "@/components/ai/prompt-input" import { Button } from "@/components/ui/button" import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs" import { InfoIcon, ResearchIcon, SettingsIcon, WebSearchIcon } from "@/lib/icons" const layouts = ["Without", "Top", "Bottom", "Both"] as const type Layout = (typeof layouts)[number] export default function PromptInputFrameDemo() { const [layout, setLayout] = React.useState("Both") const top = layout === "Top" || layout === "Both" const bottom = layout === "Bottom" || layout === "Both" return (

setLayout(v as Layout)}> {layouts.map((l) => ( {l} ))} {top && }>Add context, let the agents manage the rest} toast(`Sent: ${text}`)}> {bottom && ( } defaultPressed> Web search }>Deep research )}

) } ``` ## Dictation Dictation for the prompt input. Speech is transcribed into the textarea as you talk, so it can be reviewed before sending. ```bash npx shadcn@latest add @jds/prompt-input-mic ``` npm dependencies: `cn`, `motion` Also installs: `@jds/button`, `@jds/prompt-input`, `@jds/tooltip`, `@jds/utils`, `@jds/waveform` ```tsx import { PromptInputMic } from "@/components/ai/prompt-input-mic" ``` ### PromptInputMic | Prop | Type | Default | Description | | --- | --- | --- | --- | | `lang` | `string` | `navigator.language` | BCP 47 language for recognition, e.g. "it-IT". | ### useSpeechRecognition | Prop | Type | Default | Description | | --- | --- | --- | --- | | `returns` | `{ supported, listening, transcript, error, start, stop }` | | Web Speech API. Chrome, Edge and Safari. Elsewhere supported is false and the mic disables itself. | ## Mentions Type @ in the composer to mention files, tools or agents. Keyboard first; picks show as chips and are reported for sending. ```bash npx shadcn@latest add @jds/prompt-input-mentions ``` npm dependencies: `cn`, `motion` Also installs: `@jds/prompt-input`, `@jds/utils` ```tsx import { PromptInputMentions } from "@/components/ai/prompt-input-mentions" send({ text, mentions })}> … ``` ### PromptInputMentions | Prop | Type | Default | Description | | --- | --- | --- | --- | | `items` | `{ id, label, type: "file" \| "folder" \| "tool" \| "agent", description? }[]` | | What can be mentioned. Filtered by the text after @. | | `onMentionsChange` | `(mentions) => void` | | Current picks. Cleared after submit. | ## Tools menu Tools like web search or deep research folded into one toolbar menu, so they fit at any width. The trigger shows the active tool, or how many are on. ```bash npx shadcn@latest add @jds/prompt-input-option-menu ``` npm dependencies: `cn` Also installs: `@jds/button`, `@jds/dropdown-menu`, `@jds/utils` ```tsx import { PromptInputOptionMenu } from "@/components/ai/prompt-input-option-menu" ``` ### PromptInputOptionMenu | Prop | Type | Default | Description | | --- | --- | --- | --- | | `options` | `{ id, label, icon?, description? }[]` | | The tools to offer. | | `value` | `string[]` | | Enabled ids. | | `onValueChange` | `(ids: string[]) => void` | | Send it with the message. | | `label` | `string` | `"Tools"` | Trigger text when none are on, and the menu heading. | ## Scope Tell the agent which parts of the product it may work on. A context label and a multi-select of modules in the composer footer; nothing selected means everything. ```bash npx shadcn@latest add @jds/prompt-input-scope ``` npm dependencies: `cn` Also installs: `@jds/button`, `@jds/dropdown-menu`, `@jds/utils` ```tsx import { PromptInputScope } from "@/components/ai/prompt-input-scope" send({ text, scope })}>… } scopes={modules} allLabel="All modules" value={scope} onValueChange={setScope} /> ``` ### PromptInputScope | Prop | Type | Default | Description | | --- | --- | --- | --- | | `scopes` | `{ id, label, description? }[]` | | What the agent can be limited to. | | `value` | `string[]` | | Selected ids. Empty means all; picking every scope also resets to empty. | | `onValueChange` | `(ids: string[]) => void` | | Send it with the message. | | `label` | `ReactNode` | | Context line on the left, e.g. "Workspace context". | | `icon` | `ReactNode` | | Icon before the label. | | `allLabel` | `string` | `"All"` | Shown when nothing is selected. | | `menuLabel` | `string` | | Heading at the top of the menu. | ## API Reference ### PromptInput | Prop | Type | Default | Description | | --- | --- | --- | --- | | `onSubmit` | `({ text, files }) => void` | | Called on the send key or the send button. Input clears after. | | `status` | `"ready" \| "submitted" \| "streaming" \| "error"` | `"ready"` | Matches AI SDK useChat. Drives the submit button. | | `value` | `string` | | Controlled value. | | `onValueChange` | `(value: string) => void` | | Change handler for controlled use. | | `submitOn` | `"enter" \| "mod-enter"` | `"enter"` | Enter sends and Shift+Enter adds a line, or ⌘/Ctrl+Enter sends and Enter adds a line (better for long prompts and code). | | `accept` | `string` | | File types for the picker. | ### PromptInputSubmit | Prop | Type | Default | Description | | --- | --- | --- | --- | | `onStop` | `() => void` | | Called when pressed while streaming. | ### PromptInputFrame | Prop | Type | Default | Description | | --- | --- | --- | --- | | `children` | `ReactNode` | | An optional PromptInputHeader, the PromptInput, and an optional PromptInputFooter. Header and footer animate when added or removed. | ### PromptInputHeader | Prop | Type | Default | Description | | --- | --- | --- | --- | | `icon` | `ReactNode` | | Shown before the context text. | ### PromptInputOption | Prop | Type | Default | Description | | --- | --- | --- | --- | | `icon` | `ReactNode` | | Shown before the label. | | `pressed` | `boolean` | | Controlled state. Or use defaultPressed. | | `onPressedChange` | `(pressed: boolean) => void` | | | ## Source ### components/ai/prompt-input.tsx ```tsx "use client" import * as React from "react" import { Toggle } from "@base-ui/react/toggle" import { AnimatePresence, motion, type HTMLMotionProps } from "motion/react" import { cn } from "cn" import { Button } from "@/components/ui/button" import { AttachIcon, CloseIcon, FileIcon, SendIcon, SpinnerIcon, StopIcon } from "@/lib/icons" import { spring } from "@/lib/motion" /** Mirrors the AI SDK `useChat` status so it can be passed straight through. */ type ChatStatus = "ready" | "submitted" | "streaming" | "error" type PromptInputContextValue = { value: string setValue: (value: string) => void files: File[] addFiles: (files: FileList | File[]) => void removeFile: (index: number) => void status: ChatStatus submitOn: SubmitKey submit: () => void openFilePicker: () => void textareaRef: React.RefObject /** * Lets add-ons (like mentions) claim keys before the composer handles them. * Return true from the handler to consume the key. Returns an unregister function. */ registerKeyHandler: (handler: KeyHandler) => () => void /** Internal: read by the textarea. */ keyHandlers: React.RefObject> } type KeyHandler = (e: React.KeyboardEvent) => boolean /** "enter" sends on Enter (Shift+Enter for a new line); "mod-enter" sends on ⌘/Ctrl+Enter, so Enter adds lines. */ type SubmitKey = "enter" | "mod-enter" const PromptInputContext = React.createContext(null) function usePromptInput() { const ctx = React.useContext(PromptInputContext) if (!ctx) throw new Error("PromptInput parts must be used inside ") return ctx } type PromptInputProps = Omit, "onSubmit"> & { value?: string onValueChange?: (value: string) => void onSubmit: (message: { text: string; files: File[] }) => void status?: ChatStatus submitOn?: SubmitKey accept?: string } function PromptInput({ value: controlledValue, onValueChange, onSubmit, status = "ready", submitOn = "enter", accept, className, children, ...props }: PromptInputProps) { const [uncontrolled, setUncontrolled] = React.useState("") const [files, setFiles] = React.useState([]) const [dragging, setDragging] = React.useState(false) const fileInputRef = React.useRef(null) const textareaRef = React.useRef(null) const keyHandlers = React.useRef(new Set()) const registerKeyHandler = React.useCallback((handler: KeyHandler) => { keyHandlers.current.add(handler) return () => { keyHandlers.current.delete(handler) } }, []) const value = controlledValue ?? uncontrolled const setValue = React.useCallback( (next: string) => { if (controlledValue === undefined) setUncontrolled(next) onValueChange?.(next) }, [controlledValue, onValueChange] ) const addFiles = React.useCallback((list: FileList | File[]) => { setFiles((prev) => [...prev, ...Array.from(list)]) }, []) const removeFile = React.useCallback((index: number) => { setFiles((prev) => prev.filter((_, i) => i !== index)) }, []) const submit = React.useCallback(() => { const text = value.trim() if (!text && files.length === 0) return if (status === "submitted" || status === "streaming") return onSubmit({ text, files }) setValue("") setFiles([]) }, [value, files, status, onSubmit, setValue]) const ctx: PromptInputContextValue = { value, setValue, files, addFiles, removeFile, status, submitOn, submit, openFilePicker: () => fileInputRef.current?.click(), textareaRef, registerKeyHandler, keyHandlers, } return (

{ e.preventDefault() submit() }} onDragOver={(e) => { if (!e.dataTransfer.types.includes("Files")) return e.preventDefault() setDragging(true) }} onDragLeave={() => setDragging(false)} onDrop={(e) => { e.preventDefault() setDragging(false) if (e.dataTransfer.files.length) addFiles(e.dataTransfer.files) }} className={cn( "relative flex w-full flex-col rounded-2xl border border-input bg-card shadow-xs transition-[border-color,box-shadow] duration-200", "focus-within:border-ring/60 focus-within:ring-4 focus-within:ring-ring/10", "data-dragging:border-ring data-dragging:ring-4 data-dragging:ring-ring/20", className )} {...props} > { if (e.target.files) addFiles(e.target.files) e.target.value = "" }} /> {children}

) } function PromptInputTextarea({ className, onKeyDown, placeholder = "Ask anything…", ...props }: React.ComponentProps<"textarea">) { const { value, setValue, submit, submitOn, addFiles, textareaRef, keyHandlers } = usePromptInput() return (

setValue(e.target.value)}
      onPaste={(e) => {
        if (e.clipboardData.files.length) {
          e.preventDefault()
          addFiles(e.clipboardData.files)
        }
      }}
      onKeyDown={(e) => {
        for (const handler of keyHandlers.current) {
          if (handler(e)) {
            e.preventDefault()
            return
          }
        }
        onKeyDown?.(e)
        if (e.defaultPrevented) return
        if (e.key !== "Enter" || e.nativeEvent.isComposing) return
        const send = submitOn === "mod-enter" ? e.metaKey || e.ctrlKey : !e.shiftKey
        if (send) {
          e.preventDefault()
          submit()
        }
      }}
      className={cn(
        "field-sizing-content max-h-60 min-h-12 w-full resize-none bg-transparent px-4 pt-3.5 pb-1 text-sm outline-none placeholder:text-muted-foreground",
        className
      )}
      {...props}
    />
  )
}

function PromptInputAttachments({ className, ...props }: React.ComponentProps<"div">) {
  const { files, removeFile } = usePromptInput()
  if (files.length === 0) return null
  return (
    <div data-slot="prompt-input-attachments" className={cn("flex flex-wrap gap-2 px-3 pt-3", className)} {...props}>
      <AnimatePresence initial={false}>
        {files.map((file, i) => (
          <motion.div
            key={`${file.name}-${i}`}
            layout
            initial={{ opacity: 0, scale: 0.9 }}
            animate={{ opacity: 1, scale: 1 }}
            exit={{ opacity: 0, scale: 0.9 }}
            transition={spring.snappy}
            className="group/file flex h-8 items-center gap-1.5 rounded-lg border bg-muted/50 pr-1 pl-2 text-xs"
          >
            <FileIcon className="size-3.5 text-muted-foreground" />
            <span className="max-w-40 truncate">{file.name}</span>
            <button
              type="button"
              aria-label={`Remove ${file.name}`}
              onClick={() => removeFile(i)}
              className="grid size-5 place-items-center rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
            >
              <CloseIcon className="size-3" />
            </button>
          </motion.div>
        ))}
      </AnimatePresence>
    </div>
  )
}

function PromptInputToolbar({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="prompt-input-toolbar"
      className={cn("flex items-center justify-between gap-2 p-2", className)}
      {...props}
    />
  )
}

function PromptInputTools({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="prompt-input-tools" className={cn("flex min-w-0 items-center gap-1", className)} {...props} />
}

function PromptInputAttachButton(props: React.ComponentProps<typeof Button>) {
  const { openFilePicker } = usePromptInput()
  return (
    <Button
      type="button"
      variant="ghost"
      size="icon-sm"
      aria-label="Attach files"
      className="text-muted-foreground"
      onClick={openFilePicker}
      {...props}
    >
      <AttachIcon />
    </Button>
  )
}

function PromptInputSubmit({
  onStop,
  className,
  ...props
}: React.ComponentProps<typeof Button> & { onStop?: () => void }) {
  const { status, value, files } = usePromptInput()
  const busy = status === "submitted" || status === "streaming"
  const empty = !value.trim() && files.length === 0
  const icon =
    status === "submitted" ? (
      <SpinnerIcon className="animate-spin" />
    ) : status === "streaming" ? (
      <StopIcon className="fill-current" />
    ) : (
      <SendIcon />
    )

return (
    <Button
      type={busy ? "button" : "submit"}
      size="icon-sm"
      aria-label={busy ? "Stop generating" : "Send message"}
      disabled={!busy && empty}
      onClick={busy ? onStop : undefined}
      className={cn("rounded-full", className)}
      {...props}
    >
      <AnimatePresence mode="popLayout" initial={false}>
        <motion.span
          key={status}
          initial={{ opacity: 0, scale: 0.6, rotate: -30 }}
          animate={{ opacity: 1, scale: 1, rotate: 0 }}
          exit={{ opacity: 0, scale: 0.6, rotate: 30 }}
          transition={spring.snappy}
          className="grid place-items-center"
        >
          {icon}
        </motion.span>
      </AnimatePresence>
    </Button>
  )
}

/**
 * Optional outer layer. Wrap <PromptInput> to add a context line on top
 * (<PromptInputHeader>), options below (<PromptInputFooter>), or both.
 * Header and footer animate in and out when conditionally rendered.
 */
function PromptInputFrame({ className, children, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="prompt-input-frame"
      className={cn(
        "flex w-full flex-col rounded-3xl border border-transparent transition-[padding,background-color,border-color] duration-200",
        // The tray only appears when there's a header or footer to hold.
        "has-data-[slot=prompt-input-footer]:border-border has-data-[slot=prompt-input-footer]:bg-muted/70 has-data-[slot=prompt-input-footer]:p-1",
        "has-data-[slot=prompt-input-header]:border-border has-data-[slot=prompt-input-header]:bg-muted/70 has-data-[slot=prompt-input-header]:p-1",
        "has-data-[slot=prompt-input-footer]:[&_[data-slot=prompt-input]]:shadow-none has-data-[slot=prompt-input-header]:[&_[data-slot=prompt-input]]:shadow-none",
        className
      )}
      {...props}
    >
      <AnimatePresence initial={false}>{React.Children.toArray(children)}</AnimatePresence>
    </div>
  )
}

type SlotProps = Omit<HTMLMotionProps<"div">, "children"> & { children?: React.ReactNode }

const collapse = {
  initial: { height: 0, opacity: 0 },
  animate: { height: "auto", opacity: 1 },
  exit: { height: 0, opacity: 0 },
  transition: spring.gentle,
} as const

/** Context line above the input, for guidance, the current scope, or attached context. */
function PromptInputHeader({
  icon,
  className,
  children,
  ...props
}: SlotProps & { icon?: React.ReactNode }) {
  return (
    <motion.div data-slot="prompt-input-header" className="overflow-hidden" {...collapse} {...props}>
      <div
        className={cn(
          "flex items-center gap-2 px-3 pt-1.5 pb-2.5 text-sm text-muted-foreground [&_svg]:size-4 [&_svg]:shrink-0",
          className
        )}
      >
        {icon}
        {children}
      </div>
    </motion.div>
  )
}

/** Options row below the input: toggles, modes, scopes. */
function PromptInputFooter({ className, children, ...props }: SlotProps) {
  return (
    <motion.div data-slot="prompt-input-footer" className="overflow-hidden" {...collapse} {...props}>
      <div className={cn("flex flex-wrap items-center gap-1.5 px-1.5 pt-1.5 pb-0.5", className)}>{children}</div>
    </motion.div>
  )
}

/** A pressable option chip for the footer, e.g. web search or deep research. */
function PromptInputOption({ icon, className, children, ...props }: Toggle.Props & { icon?: React.ReactNode }) {
  return (
    <Toggle
      data-slot="prompt-input-option"
      className={cn(
        "inline-flex h-7 items-center gap-1.5 rounded-full border border-transparent px-2.5 text-xs text-muted-foreground transition-colors outline-none select-none",
        "hover:bg-background/60 hover:text-foreground focus-visible:ring-3 focus-visible:ring-ring/50",
        "data-pressed:border-border data-pressed:bg-background data-pressed:text-foreground data-pressed:shadow-xs",
        "[&_svg]:size-3.5 [&_svg]:shrink-0",
        className
      )}
      {...props}
    >
      {icon}
      {children}
    </Toggle>
  )
}

export {
  PromptInput,
  PromptInputTextarea,
  PromptInputAttachments,
  PromptInputToolbar,
  PromptInputTools,
  PromptInputAttachButton,
  PromptInputSubmit,
  PromptInputFrame,
  PromptInputHeader,
  PromptInputFooter,
  PromptInputOption,
  usePromptInput,
  type ChatStatus,
  type SubmitKey,
}
```

---

# Response

Markdown renderer that is safe to stream. Closes unterminated syntax as it arrives and highlights code with Shiki.

Docs: https://jds-ruddy.vercel.app/docs/components/response

## Installation

```bash
npx shadcn@latest add @jds/response
```

npm dependencies: `@streamdown/code`, `cn`, `streamdown`

## Usage

```tsx
import { Response } from "@/components/ai/response"

<Response isAnimating={status === "streaming"}>{part.text}</Response>
```

## Example

```tsx
"use client"

import * as React from "react"

import { Response } from "@/components/ai/response"
import { Button } from "@/components/ui/button"
import { RegenerateIcon } from "@/lib/icons"

const MARKDOWN = `### Retry with backoff

Wrap the call and **double the delay** after each failure:

\`\`\`ts
async function retry<T>(fn: () => Promise<T>, tries = 3) {
  for (let i = 0; ; i++) {
    try {
      return await fn()
    } catch (e) {
      if (i >= tries - 1) throw e
      await new Promise((r) => setTimeout(r, 2 ** i * 250))
    }
  }
}
\`\`\`

- Cap the delay so users aren't left waiting
- Only retry *idempotent* requests
`

export default function ResponseDemo() {
  const [text, setText] = React.useState(MARKDOWN)
  const [streaming, setStreaming] = React.useState(false)

const replay = () => {
    setStreaming(true)
    let i = 0
    const id = setInterval(() => {
      i += 6
      setText(MARKDOWN.slice(0, i))
      if (i >= MARKDOWN.length) {
        clearInterval(id)
        setStreaming(false)
      }
    }, 24)
  }

return (
    <div className="flex w-full max-w-lg flex-col gap-4">
      <Response isAnimating={streaming}>{text}</Response>
      <Button variant="outline" size="sm" className="self-start" onClick={replay} disabled={streaming}>
        <RegenerateIcon />
        Replay stream
      </Button>
    </div>
  )
}
```

## API Reference

### Response

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `string` |  | Markdown source. |
| `isAnimating` | `boolean` | `false` | Streaming mode: fades in new tokens and repairs partial syntax. |

## Source

### components/ai/response.tsx

```tsx
"use client"

import * as React from "react"
import { code } from "@streamdown/code"
import { cn } from "cn"
import { Streamdown, type StreamdownProps } from "streamdown"
import "streamdown/styles.css"

/**
 * Streaming-safe markdown. Handles unterminated fences, emphasis and links
 * mid-stream, with Shiki highlighting and copy buttons on code blocks.
 */
const Response = React.memo(function Response({
  className,
  isAnimating,
  ...props
}: StreamdownProps) {
  return (
    <Streamdown
      data-slot="response"
      mode={isAnimating ? "streaming" : "static"}
      isAnimating={isAnimating}
      animated={isAnimating}
      plugins={{ code }}
      shikiTheme={["github-light", "vitesse-dark"]}
      className={cn("w-full text-sm leading-relaxed [&>*:first-child]:mt-0 [&>*:last-child]:mb-0", className)}
      {...props}
    />
  )
})

export { Response }
```

---

# Reasoning

Model thinking, open while it streams, then collapsed to a one-line summary with the time it took.

Docs: https://jds-ruddy.vercel.app/docs/components/reasoning

## Installation

```bash
npx shadcn@latest add @jds/reasoning
```

npm dependencies: `cn`, `motion`

Also installs: `@jds/collapsible`, `@jds/shimmer`, `@jds/utils`

## Usage

```tsx
import { Reasoning, ReasoningContent, ReasoningTrigger } from "@/components/ai/reasoning"

<Reasoning isStreaming={isStreaming}>
  <ReasoningTrigger />
  <ReasoningContent>{part.text}</ReasoningContent>
</Reasoning>
```

## Example

```tsx
"use client"

import * as React from "react"

import { Reasoning, ReasoningContent, ReasoningTrigger } from "@/components/ai/reasoning"
import { Button } from "@/components/ui/button"

const THOUGHT =
  "The user wants the cheapest route that still arrives by Friday. Rail is cheaper but takes two days with a change in Lyon. The direct flight is €40 more and same-day. Friday arrival rules nothing out, so rail wins on price."

export default function ReasoningDemo() {
  const [text, setText] = React.useState("")
  const [streaming, setStreaming] = React.useState(false)

const run = () => {
    setText("")
    setStreaming(true)
    const words = THOUGHT.split(" ")
    let i = 0
    const id = setInterval(() => {
      i++
      setText(words.slice(0, i).join(" "))
      if (i >= words.length) {
        clearInterval(id)
        setStreaming(false)
      }
    }, 70)
  }

return (
    <div className="flex w-full max-w-lg flex-col gap-4">
      <Reasoning isStreaming={streaming}>
        <ReasoningTrigger />
        <ReasoningContent>{text || THOUGHT}</ReasoningContent>
      </Reasoning>
      <Button variant="outline" size="sm" className="self-start" onClick={run} disabled={streaming}>
        Think
      </Button>
    </div>
  )
}
```

## API Reference

### Reasoning

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `isStreaming` | `boolean` | `false` | Opens the panel and runs the timer. Collapses once when it turns false. |
| `duration` | `number` |  | Seconds spent thinking. Measured automatically if omitted. |

## Source

### components/ai/reasoning.tsx

```tsx
"use client"

import * as React from "react"
import { AnimatePresence, motion } from "motion/react"
import { cn } from "cn"

import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@/components/ui/collapsible"
import { Shimmer } from "@/components/ai/shimmer"
import { ChevronDownIcon, ReasoningIcon } from "@/lib/icons"

type ReasoningProps = React.ComponentProps<typeof Collapsible> & {
  /** While true the panel opens and the timer runs. It auto-collapses when streaming ends. */
  isStreaming?: boolean
  /** Seconds spent reasoning. Measured automatically if omitted. */
  duration?: number
}

const ReasoningContext = React.createContext<{ isStreaming: boolean; seconds: number }>({
  isStreaming: false,
  seconds: 0,
})

function Reasoning({ isStreaming = false, duration, className, children, ...props }: ReasoningProps) {
  const [open, setOpen] = React.useState(isStreaming)
  const [measured, setMeasured] = React.useState(0)
  const startedAt = React.useRef<number | null>(null)
  const [prevStreaming, setPrevStreaming] = React.useState(isStreaming)

// Open while streaming, close once when it finishes. Manual toggles are respected afterwards.
  if (prevStreaming !== isStreaming) {
    setPrevStreaming(isStreaming)
    setOpen(isStreaming)
  }

React.useEffect(() => {
    if (isStreaming) {
      startedAt.current = Date.now()
    } else if (startedAt.current) {
      const elapsed = Math.max(1, Math.round((Date.now() - startedAt.current) / 1000))
      startedAt.current = null
      queueMicrotask(() => setMeasured(elapsed))
    }
  }, [isStreaming])

return (
    <ReasoningContext.Provider value={{ isStreaming, seconds: duration ?? measured }}>
      <Collapsible
        data-slot="reasoning"
        open={open}
        onOpenChange={setOpen}
        className={className}
        {...props}
      >
        {children}
      </Collapsible>
    </ReasoningContext.Provider>
  )
}

function ReasoningTrigger({ className, children, ...props }: React.ComponentProps<typeof CollapsibleTrigger>) {
  const { isStreaming, seconds } = React.useContext(ReasoningContext)
  return (
    <CollapsibleTrigger
      data-slot="reasoning-trigger"
      className={cn(
        "group/trigger flex items-center gap-1.5 text-sm text-muted-foreground transition-colors hover:text-foreground",
        className
      )}
      {...props}
    >
      <ReasoningIcon className={cn("size-4", isStreaming && "text-foreground")} />
      {children ??
        (isStreaming ? (
          <Shimmer>Thinking…</Shimmer>
        ) : (
          <span>{seconds > 0 ? `Thought for ${seconds}s` : "Reasoning"}</span>
        ))}
      <ChevronDownIcon className="size-3.5 transition-transform duration-200 group-data-panel-open/trigger:rotate-180" />
    </CollapsibleTrigger>
  )
}

function ReasoningContent({ className, children, ...props }: React.ComponentProps<typeof CollapsibleContent>) {
  return (
    <CollapsibleContent
      data-slot="reasoning-content"
      className={cn(
        "h-(--collapsible-panel-height) overflow-hidden transition-[height] duration-300 ease-out-quint data-ending-style:h-0 data-starting-style:h-0",
        className
      )}
      {...props}
    >
      <div className="mt-3 border-l-2 border-border pl-4 text-sm leading-relaxed whitespace-pre-wrap text-muted-foreground">
        <AnimatePresence initial={false}>
          <motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }}>
            {children}
          </motion.div>
        </AnimatePresence>
      </div>
    </CollapsibleContent>
  )
}

export { Reasoning, ReasoningTrigger, ReasoningContent }
```

---

# Tool Call

What the agent called, with what input, and what came back. States match AI SDK tool parts.

Docs: https://jds-ruddy.vercel.app/docs/components/tool-call

## Installation

```bash
npx shadcn@latest add @jds/tool-call
```

npm dependencies: `cn`

Also installs: `@jds/badge`, `@jds/collapsible`, `@jds/utils`

## Usage

```tsx
import { ToolCall, ToolCallContent, ToolCallHeader, ToolCallSection } from "@/components/ai/tool-call"

<ToolCall>
  <ToolCallHeader name="orders.lookup" state={part.state} />
  <ToolCallContent>
    <ToolCallSection label="Input" value={part.input} />
    <ToolCallSection label="Output" value={part.output} error={part.errorText} />
  </ToolCallContent>
</ToolCall>
```

## Example

```tsx
import { ToolCall, ToolCallContent, ToolCallHeader, ToolCallSection } from "@/components/ai/tool-call"

export default function ToolCallDemo() {
  return (
    <div className="flex w-full max-w-lg flex-col gap-3">
      <ToolCall defaultOpen>
        <ToolCallHeader name="weather.forecast" state="output-available" />
        <ToolCallContent>
          <ToolCallSection label="Input" value={{ city: "Lisbon", days: 3 }} />
          <ToolCallSection label="Output" value={{ high: 24, low: 16, conditions: "Sunny" }} />
        </ToolCallContent>
      </ToolCall>
      <ToolCall>
        <ToolCallHeader name="calendar.create_event" state="input-available" />
      </ToolCall>
      <ToolCall>
        <ToolCallHeader name="files.search" state="input-streaming" />
      </ToolCall>
      <ToolCall>
        <ToolCallHeader name="crm.update_contact" state="output-error" />
        <ToolCallContent>
          <ToolCallSection label="Error" error="403: missing scope contacts.write" />
        </ToolCallContent>
      </ToolCall>
    </div>
  )
}
```

## API Reference

### ToolCallHeader

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  | Tool name. |
| `state` | `"input-streaming" \| "input-available" \| "output-available" \| "output-error"` |  | Pending, running, done, failed. |

### ToolCallSection

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` |  | Section heading. |
| `value` | `unknown` |  | Rendered as JSON unless it is a string. |
| `error` | `string` |  | Shown in destructive style instead of value. |

## Source

### components/ai/tool-call.tsx

```tsx
"use client"

import * as React from "react"
import { cn } from "cn"

import { Badge } from "@/components/ui/badge"
import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@/components/ui/collapsible"
import { ChevronDownIcon, ErrorIcon, PendingIcon, SpinnerIcon, SuccessIcon, ToolIcon } from "@/lib/icons"

/** Matches AI SDK tool part states. */
type ToolState = "input-streaming" | "input-available" | "output-available" | "output-error"

const stateMeta: Record<ToolState, { label: string; icon: React.ReactNode; className: string }> = {
  "input-streaming": {
    label: "Pending",
    icon: <PendingIcon />,
    className: "text-muted-foreground",
  },
  "input-available": {
    label: "Running",
    icon: <SpinnerIcon className="animate-spin" />,
    className: "text-foreground",
  },
  "output-available": {
    label: "Done",
    icon: <SuccessIcon />,
    className: "text-success",
  },
  "output-error": {
    label: "Failed",
    icon: <ErrorIcon />,
    className: "text-destructive",
  },
}

function ToolCall({ className, ...props }: React.ComponentProps<typeof Collapsible>) {
  return (
    <Collapsible
      data-slot="tool-call"
      className={cn("w-full overflow-hidden rounded-xl border bg-card", className)}
      {...props}
    />
  )
}

function ToolCallHeader({
  name,
  state,
  className,
  ...props
}: React.ComponentProps<typeof CollapsibleTrigger> & { name: string; state: ToolState }) {
  const meta = stateMeta[state]
  return (
    <CollapsibleTrigger
      data-slot="tool-call-header"
      className={cn(
        "group/trigger flex w-full items-center gap-2.5 px-3 py-2.5 text-left text-sm transition-colors hover:bg-muted/50",
        className
      )}
      {...props}
    >
      <span className="grid size-6 place-items-center rounded-md bg-muted text-muted-foreground">
        <ToolIcon className="size-3.5" />
      </span>
      <span className="flex-1 truncate font-mono text-xs">{name}</span>
      <Badge variant="outline" className={cn("gap-1 [&>svg]:size-3!", meta.className)}>
        {meta.icon}
        {meta.label}
      </Badge>
      <ChevronDownIcon className="size-4 text-muted-foreground transition-transform duration-200 group-data-panel-open/trigger:rotate-180" />
    </CollapsibleTrigger>
  )
}

function ToolCallContent({ className, ...props }: React.ComponentProps<typeof CollapsibleContent>) {
  return (
    <CollapsibleContent
      data-slot="tool-call-content"
      className={cn(
        "h-(--collapsible-panel-height) overflow-hidden border-t transition-[height] duration-300 ease-out-quint data-ending-style:h-0 data-starting-style:h-0",
        className
      )}
      {...props}
    />
  )
}

function ToolCallSection({
  label,
  value,
  error,
  className,
  ...props
}: React.ComponentProps<"div"> & { label: string; value?: unknown; error?: string }) {
  if (value === undefined && !error) return null
  const text = error ?? (typeof value === "string" ? value : JSON.stringify(value, null, 2))
  return (
    <div data-slot="tool-call-section" className={cn("space-y-1.5 p-3", className)} {...props}>
      <div className="text-xs font-medium tracking-wide text-muted-foreground uppercase">{label}</div>
      <pre
        className={cn(
          "overflow-x-auto rounded-lg bg-muted/60 p-3 font-mono text-xs leading-relaxed",
          error && "bg-destructive/10 text-destructive"
        )}
      >
        {text}
      </pre>
    </div>
  )
}

export { ToolCall, ToolCallHeader, ToolCallContent, ToolCallSection, type ToolState }
```

---

# Approval

Human-in-the-loop gate. The agent pauses on an irreversible action until the user approves or denies it.

Docs: https://jds-ruddy.vercel.app/docs/components/approval

## Installation

```bash
npx shadcn@latest add @jds/approval
```

npm dependencies: `cn`, `motion`

Also installs: `@jds/button`, `@jds/utils`

## Usage

```tsx
import { Approval } from "@/components/ai/approval"

<Approval
  title="Refund €68.90 to Maria Rossi"
  description="This can't be undone."
  decision={decision}
  onApprove={() => addToolResult({ approved: true })}
  onDeny={() => addToolResult({ approved: false })}
/>
```

## Example

```tsx
"use client"

import * as React from "react"

import { Approval, type ApprovalDecision } from "@/components/ai/approval"
import { Button } from "@/components/ui/button"

export default function ApprovalDemo() {
  const [decision, setDecision] = React.useState<ApprovalDecision>("pending")
  return (
    <div className="flex w-full max-w-lg flex-col gap-4">
      <Approval
        title="Delete 214 archived invoices"
        description="They'll be removed from storage permanently."
        approveLabel="Delete"
        decision={decision}
        onApprove={() => setDecision("approved")}
        onDeny={() => setDecision("denied")}
      />
      {decision !== "pending" && (
        <Button variant="ghost" size="sm" className="self-start" onClick={() => setDecision("pending")}>
          Reset
        </Button>
      )}
    </div>
  )
}
```

## API Reference

### Approval

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `ReactNode` |  | The action, in plain words. |
| `description` | `ReactNode` |  | Consequences. |
| `decision` | `"pending" \| "approved" \| "denied"` | `"pending"` | Resolved state replaces the buttons. |
| `onApprove` | `() => void` |  |  |
| `onDeny` | `() => void` |  |  |
| `approveLabel` | `string` | `"Approve"` | Use the verb: Refund, Delete, Send. |

## Source

### components/ai/approval.tsx

```tsx
"use client"

import * as React from "react"
import { AnimatePresence, motion } from "motion/react"
import { cn } from "cn"

import { Button } from "@/components/ui/button"
import { ApprovalIcon, CheckIcon, CloseIcon } from "@/lib/icons"
import { spring } from "@/lib/motion"

type ApprovalDecision = "pending" | "approved" | "denied"

/**
 * Human-in-the-loop gate. The agent pauses on a risky action until the user decides.
 * Pass `decision` to render the resolved state after the fact.
 */
function Approval({
  title,
  description,
  decision = "pending",
  onApprove,
  onDeny,
  approveLabel = "Approve",
  denyLabel = "Deny",
  className,
  children,
  ...props
}: Omit<React.ComponentProps<"div">, "title"> & {
  title: React.ReactNode
  description?: React.ReactNode
  decision?: ApprovalDecision
  onApprove?: () => void
  onDeny?: () => void
  approveLabel?: string
  denyLabel?: string
}) {
  return (
    <div
      data-slot="approval"
      data-decision={decision}
      role="group"
      aria-label="Approval required"
      className={cn(
        "overflow-hidden rounded-xl border bg-card transition-colors duration-300",
        decision === "pending" && "border-foreground/20 bg-muted/40",
        className
      )}
      {...props}
    >
      <div className="flex gap-3 p-4">
        <span
          className={cn(
            "grid size-8 shrink-0 place-items-center rounded-lg",
            decision === "pending" ? "bg-muted text-foreground" : "bg-muted text-muted-foreground"
          )}
        >
          <ApprovalIcon className="size-4" />
        </span>
        <div className="min-w-0 flex-1 space-y-1">
          <div className="text-sm font-medium">{title}</div>
          {description && <div className="text-sm text-muted-foreground">{description}</div>}
          {children && <div className="pt-2">{children}</div>}
        </div>
      </div>
      <div className="flex items-center justify-end gap-2 border-t px-4 py-2.5">
        <AnimatePresence mode="wait" initial={false}>
          {decision === "pending" ? (
            <motion.div
              key="actions"
              className="flex gap-2"
              initial={{ opacity: 0 }}
              animate={{ opacity: 1 }}
              exit={{ opacity: 0, y: -4 }}
            >
              <Button variant="ghost" size="sm" onClick={onDeny}>
                {denyLabel}
              </Button>
              <Button size="sm" onClick={onApprove}>
                {approveLabel}
              </Button>
            </motion.div>
          ) : (
            <motion.div
              key="result"
              initial={{ opacity: 0, y: 4 }}
              animate={{ opacity: 1, y: 0 }}
              transition={spring.gentle}
              className={cn(
                "flex items-center gap-1.5 text-xs font-medium",
                decision === "approved" ? "text-success" : "text-muted-foreground"
              )}
            >
              {decision === "approved" ? <CheckIcon className="size-3.5" /> : <CloseIcon className="size-3.5" />}
              {decision === "approved" ? "Approved" : "Denied"}
            </motion.div>
          )}
        </AnimatePresence>
      </div>
    </div>
  )
}

export { Approval, type ApprovalDecision }
```

---

# Agent Steps

Plan and progress for a multi-step run: what's done, what's running, what's next.

Docs: https://jds-ruddy.vercel.app/docs/components/agent-steps

## Installation

```bash
npx shadcn@latest add @jds/agent-steps
```

npm dependencies: `cn`, `motion`

Also installs: `@jds/shimmer`, `@jds/utils`

## Usage

```tsx
import { AgentSteps } from "@/components/ai/agent-steps"

<AgentSteps
  steps={[
    { id: "1", label: "Look up order", status: "complete" },
    { id: "2", label: "Check eligibility", status: "active" },
    { id: "3", label: "Issue refund", status: "pending" },
  ]}
/>
```

## Example

```tsx
"use client"

import * as React from "react"

import { AgentSteps, type AgentStep } from "@/components/ai/agent-steps"

const LABELS = ["Read the brief", "Search competitor pricing", "Draft the comparison table", "Write the summary"]

export default function AgentStepsDemo() {
  const [active, setActive] = React.useState(0)

React.useEffect(() => {
    const id = setInterval(() => setActive((a) => (a > LABELS.length ? 0 : a + 1)), 1400)
    return () => clearInterval(id)
  }, [])

const steps: AgentStep[] = LABELS.map((label, i) => ({
    id: label,
    label,
    status: i < active ? "complete" : i === active ? "active" : "pending",
    detail: i === 1 && active > 1 ? "Found 6 sources" : undefined,
  }))

return <AgentSteps steps={steps} className="w-full max-w-sm" />
}
```

## API Reference

### AgentSteps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` | `{ id, label, detail?, status }[]` |  | status: "pending" \| "active" \| "complete" \| "error" |

## Source

### components/ai/agent-steps.tsx

```tsx
"use client"

import * as React from "react"
import { AnimatePresence, motion } from "motion/react"
import { cn } from "cn"

import { Shimmer } from "@/components/ai/shimmer"
import { CheckIcon, CloseIcon } from "@/lib/icons"
import { spring } from "@/lib/motion"

type StepStatus = "pending" | "active" | "complete" | "error"

type AgentStep = { id: string; label: string; detail?: string; status: StepStatus }

/** Vertical plan/progress list, for multi-step agent runs. */
function AgentSteps({ steps, className, ...props }: React.ComponentProps<"ol"> & { steps: AgentStep[] }) {
  return (
    <ol data-slot="agent-steps" className={cn("relative flex flex-col", className)} {...props}>
      {steps.map((step, i) => (
        <li key={step.id} data-status={step.status} className="relative flex gap-3 pb-4 last:pb-0">
          {i < steps.length - 1 && (
            <span
              aria-hidden
              className={cn(
                "absolute top-5 bottom-0 left-2.25 w-px transition-colors duration-500",
                step.status === "complete" ? "bg-foreground/30" : "bg-border"
              )}
            />
          )}
          <StepMarker status={step.status} />
          <div className="min-w-0 flex-1 pt-px">
            <div
              className={cn(
                "text-sm transition-colors duration-300",
                step.status === "pending" && "text-muted-foreground",
                step.status === "error" && "text-destructive"
              )}
            >
              {step.status === "active" ? <Shimmer>{step.label}</Shimmer> : step.label}
            </div>
            {step.detail && <div className="mt-0.5 text-xs text-muted-foreground">{step.detail}</div>}
          </div>
        </li>
      ))}
    </ol>
  )
}

function StepMarker({ status }: { status: StepStatus }) {
  return (
    <span
      className={cn(
        "relative z-10 grid size-4.5 shrink-0 place-items-center rounded-full border bg-background transition-colors duration-300",
        status === "active" && "border-foreground",
        status === "complete" && "border-foreground bg-foreground text-background",
        status === "error" && "border-destructive bg-destructive text-background"
      )}
    >
      <AnimatePresence mode="wait" initial={false}>
        {status === "active" && (
          <motion.span
            key="active"
            initial={{ scale: 0 }}
            animate={{ scale: 1 }}
            exit={{ scale: 0 }}
            transition={spring.snappy}
            className="size-1.5 animate-pulse-soft rounded-full bg-foreground"
          />
        )}
        {status === "complete" && (
          <motion.span key="complete" initial={{ scale: 0 }} animate={{ scale: 1 }} transition={spring.snappy}>
            <CheckIcon className="size-2.5" strokeWidth={3} />
          </motion.span>
        )}
        {status === "error" && (
          <motion.span key="error" initial={{ scale: 0 }} animate={{ scale: 1 }} transition={spring.snappy}>
            <CloseIcon className="size-2.5" strokeWidth={3} />
          </motion.span>
        )}
      </AnimatePresence>
    </span>
  )
}

export { AgentSteps, type AgentStep, type StepStatus }
```

---

# Sources

Inline numbered citations with hover previews, and a strip of source cards.

Docs: https://jds-ruddy.vercel.app/docs/components/sources

## Installation

```bash
npx shadcn@latest add @jds/sources
```

npm dependencies: `cn`

Also installs: `@jds/popover`, `@jds/utils`

## Usage

```tsx
import { Citation, Sources } from "@/components/ai/sources"

<p>Refunds take 5 to 10 days <Citation index={1} source={sources[0]} />.</p>
<Sources sources={sources} />
```

## Example

```tsx
import { Citation, Sources, type Source } from "@/components/ai/sources"

const sources: Source[] = [
  {
    url: "https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia",
    title: "MediaDevices: getUserMedia() method",
    snippet: "Prompts the user for permission to use a media input which produces a MediaStream.",
  },
  {
    url: "https://www.w3.org/WAI/WCAG22/Understanding/",
    title: "Understanding WCAG 2.2",
    snippet: "Explains the intent of each success criterion and how to meet it.",
  },
]

export default function SourcesDemo() {
  return (
    <div className="flex w-full max-w-lg flex-col gap-4 text-sm leading-relaxed">
      <p>
        Browsers only grant microphone access after a user gesture
        <Citation index={1} source={sources[0]} />, and live captions should be available for any audio content{" "}
        <Citation index={2} source={sources[1]} />.
      </p>
      <Sources sources={sources} />
    </div>
  )
}
```

## API Reference

### Citation

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `index` | `number` |  | Number shown in the marker. |
| `source` | `{ url, title?, snippet? }` |  |  |

## Source

### components/ai/sources.tsx

```tsx
"use client"

import * as React from "react"
import { cn } from "cn"

import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"
import { SourceIcon } from "@/lib/icons"

type Source = { url: string; title?: string; snippet?: string }

function hostname(url: string) {
  try {
    return new URL(url).hostname.replace(/^www\./, "")
  } catch {
    return url
  }
}

/** Inline numbered citation. Hover or tap to preview the source. */
function Citation({ index, source, className }: { index: number; source: Source; className?: string }) {
  return (
    <Popover>
      <PopoverTrigger
        openOnHover
        delay={120}
        data-slot="citation"
        className={cn(
          "mx-0.5 inline-grid h-4 min-w-4 -translate-y-px place-items-center rounded-sm bg-muted px-1 align-middle font-mono text-[10px] text-muted-foreground transition-colors hover:bg-accent hover:text-foreground",
          className
        )}
      >
        {index}
      </PopoverTrigger>
      <PopoverContent className="w-72 gap-1.5 p-3">
        <div className="flex items-center gap-1.5 text-xs text-muted-foreground">
          <SourceIcon className="size-3" />
          {hostname(source.url)}
        </div>
        <a href={source.url} target="_blank" rel="noreferrer" className="text-sm font-medium hover:underline">
          {source.title ?? source.url}
        </a>
        {source.snippet && <p className="line-clamp-3 text-xs text-muted-foreground">{source.snippet}</p>}
      </PopoverContent>
    </Popover>
  )
}

/** Source cards under a response. They wrap into as many columns as fit, so nothing scrolls sideways. */
function Sources({ sources, className, ...props }: React.ComponentProps<"div"> & { sources: Source[] }) {
  return (
    <div
      data-slot="sources"
      className={cn("grid grid-cols-[repeat(auto-fill,minmax(10rem,1fr))] gap-2", className)}
      {...props}
    >
      {sources.map((source, i) => (
        <a
          key={source.url}
          href={source.url}
          target="_blank"
          rel="noreferrer"
          className="flex min-w-0 flex-col gap-1 rounded-lg border bg-card p-2.5 transition-colors hover:border-ring/40 hover:bg-muted/40"
        >
          <span className="line-clamp-2 text-xs font-medium">{source.title ?? source.url}</span>
          <span className="mt-auto flex items-center gap-1.5 text-xs text-muted-foreground">
            <span className="font-mono">{i + 1}</span>
            <span className="truncate">{hostname(source.url)}</span>
          </span>
        </a>
      ))}
    </div>
  )
}

export { Citation, Sources, type Source }
```

---

# Suggestions

Follow-up prompts as a row of chips.

Docs: https://jds-ruddy.vercel.app/docs/components/suggestions

## Installation

```bash
npx shadcn@latest add @jds/suggestions
```

npm dependencies: `cn`, `motion`

Also installs: `@jds/button`, `@jds/utils`

## Usage

```tsx
import { Suggestion, Suggestions } from "@/components/ai/suggestions"

<Suggestions>
  <Suggestion suggestion="Draft a reply" onSelect={send} />
</Suggestions>
```

## Example

```tsx
"use client"

import { toast } from "sonner"

import { Suggestion, Suggestions } from "@/components/ai/suggestions"

const items = ["Summarize this page", "Find related tickets", "Draft a reply", "Translate to Italian"]

export default function SuggestionsDemo() {
  return (
    <Suggestions className="max-w-lg justify-center">
      {items.map((s) => (
        <Suggestion key={s} suggestion={s} onSelect={(v) => toast(v)} />
      ))}
    </Suggestions>
  )
}
```

## Source

### components/ai/suggestions.tsx

```tsx
"use client"

import * as React from "react"
import { motion } from "motion/react"
import { cn } from "cn"

import { Button } from "@/components/ui/button"
import { rise, stagger } from "@/lib/motion"

function Suggestions({ className, children, ...props }: React.ComponentProps<"div">) {
  return (
    <motion.div
      data-slot="suggestions"
      variants={stagger(0.05)}
      initial="hidden"
      animate="visible"
      className={cn("flex flex-wrap gap-2", className)}
      {...(props as React.ComponentProps<typeof motion.div>)}
    >
      {children}
    </motion.div>
  )
}

function Suggestion({
  suggestion,
  onSelect,
  className,
  children,
  ...props
}: Omit<React.ComponentProps<typeof Button>, "onSelect"> & {
  suggestion: string
  onSelect?: (suggestion: string) => void
}) {
  return (
    <motion.div variants={rise}>
      <Button
        variant="outline"
        size="sm"
        className={cn("rounded-full font-normal text-muted-foreground hover:text-foreground", className)}
        onClick={() => onSelect?.(suggestion)}
        {...props}
      >
        {children ?? suggestion}
      </Button>
    </motion.div>
  )
}

export { Suggestions, Suggestion }
```

---

# Shimmer

In-progress text and a typing indicator for the gap before the first token.

Docs: https://jds-ruddy.vercel.app/docs/components/shimmer

## Installation

```bash
npx shadcn@latest add @jds/shimmer
```

npm dependencies: `cn`

## Usage

```tsx
import { Shimmer, TypingIndicator } from "@/components/ai/shimmer"

<Shimmer>Searching the web…</Shimmer>
<TypingIndicator />
```

## Example

```tsx
import { Shimmer, TypingIndicator } from "@/components/ai/shimmer"

export default function ShimmerDemo() {
  return (
    <div className="flex flex-col items-center gap-4 text-sm">
      <Shimmer>Searching 14 sources…</Shimmer>
      <TypingIndicator />
    </div>
  )
}
```

## Source

### components/ai/shimmer.tsx

```tsx
import * as React from "react"
import { cn } from "cn"

/** Text with a light sweep, for "Thinking…" and other in-progress labels. */
function Shimmer({ className, ...props }: React.ComponentProps<"span">) {
  return (
    <span
      data-slot="shimmer"
      className={cn(
        "inline-block animate-shimmer bg-[linear-gradient(90deg,var(--muted-foreground)_0%,var(--muted-foreground)_40%,var(--foreground)_50%,var(--muted-foreground)_60%,var(--muted-foreground)_100%)] bg-size-[200%_100%] bg-clip-text text-transparent motion-reduce:animate-none",
        className
      )}
      {...props}
    />
  )
}

/** Three softly pulsing dots, for the gap before the first token. */
function TypingIndicator({ className, ...props }: React.ComponentProps<"span">) {
  return (
    <span
      data-slot="typing-indicator"
      role="status"
      aria-label="Assistant is typing"
      className={cn("inline-flex items-center gap-1 py-2", className)}
      {...props}
    >
      <span className="size-1.5 animate-pulse-soft rounded-full bg-foreground motion-reduce:animate-none" />
      <span className="size-1.5 animate-pulse-soft rounded-full bg-foreground [animation-delay:150ms] motion-reduce:animate-none" />
      <span className="size-1.5 animate-pulse-soft rounded-full bg-foreground [animation-delay:300ms] motion-reduce:animate-none" />
    </span>
  )
}

export { Shimmer, TypingIndicator }
```

---

# Model Picker

Choose the model for the next message. A quiet trigger for the prompt toolbar; the menu says what each model is for.

Docs: https://jds-ruddy.vercel.app/docs/components/model-picker

## Installation

```bash
npx shadcn@latest add @jds/model-picker
```

npm dependencies: `cn`

Also installs: `@jds/button`, `@jds/dropdown-menu`, `@jds/utils`

## Usage

```tsx
import { ModelPicker } from "@/components/ai/model-picker"

<ModelPicker
  models={[
    { id: "sonnet", name: "Claude Sonnet 5.5", description: "Balanced", capabilities: ["reasoning", "vision"], meta: "$$" },
    { id: "haiku", name: "Claude Haiku 4.5", description: "Quick answers", capabilities: ["fast"], meta: "$" },
  ]}
  value={model}
  onValueChange={setModel}
/>
```

## Example

```tsx
"use client"

import { toast } from "sonner"

import { ModelPicker, type Model } from "@/components/ai/model-picker"
import {
  PromptInput,
  PromptInputAttachButton,
  PromptInputSubmit,
  PromptInputTextarea,
  PromptInputToolbar,
  PromptInputTools,
} from "@/components/ai/prompt-input"

const models: Model[] = [
  {
    id: "opus",
    name: "Claude Opus 5.5",
    description: "Hardest problems, long agentic work",
    capabilities: ["reasoning", "vision", "web"],
    meta: "$$$",
  },
  {
    id: "sonnet",
    name: "Claude Sonnet 5.5",
    description: "Balanced for everyday tasks",
    capabilities: ["reasoning", "vision"],
    meta: "$$",
  },
  {
    id: "haiku",
    name: "Claude Haiku 4.5",
    description: "Quick answers, high volume",
    capabilities: ["fast"],
    meta: "$",
  },
]

export default function ModelPickerDemo() {
  return (
    <PromptInput className="max-w-lg" onSubmit={({ text }) => toast(`Sent: ${text}`)}>
      <PromptInputTextarea />
      <PromptInputToolbar>
        <PromptInputTools>
          <PromptInputAttachButton />
        </PromptInputTools>
        <div className="flex items-center gap-1">
          <ModelPicker models={models} defaultValue="sonnet" />
          <PromptInputSubmit />
        </div>
      </PromptInputToolbar>
    </PromptInput>
  )
}
```

## API Reference

### ModelPicker

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `models` | `{ id, name, description?, capabilities?, meta? }[]` |  | capabilities show as small icons after the name: "reasoning" \| "vision" \| "fast" \| "web". meta is appended to the description, like "$$" or "200k". |
| `value` | `string` |  | Controlled model id. Or use defaultValue. |
| `onValueChange` | `(id: string) => void` |  |  |
| `label` | `string` |  | Optional menu heading. |

## Source

### components/ai/model-picker.tsx

```tsx
"use client"

import * as React from "react"
import { cn } from "cn"

import { Button } from "@/components/ui/button"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuLabel,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
import { FastIcon, ReasoningIcon, SelectIcon, VisionIcon, WebSearchIcon } from "@/lib/icons"

type ModelCapability = "reasoning" | "vision" | "fast" | "web"

type Model = {
  id: string
  name: string
  /** One line: what it's good for. */
  description?: string
  capabilities?: ModelCapability[]
  /** Short note after the description, like a relative cost ("$$") or context size ("200k"). */
  meta?: string
}

const capabilityMeta: Record<ModelCapability, { label: string; icon: React.ReactNode }> = {
  reasoning: { label: "Reasoning", icon: <ReasoningIcon /> },
  vision: { label: "Vision", icon: <VisionIcon /> },
  fast: { label: "Fast", icon: <FastIcon /> },
  web: { label: "Web", icon: <WebSearchIcon /> },
}

/**
 * Choose the model for the next message. The trigger is a quiet ghost button that
 * fits a prompt toolbar; the menu shows what each model is for.
 */
function ModelPicker({
  models,
  value: controlled,
  defaultValue,
  onValueChange,
  label,
  className,
}: {
  models: Model[]
  value?: string
  defaultValue?: string
  onValueChange?: (id: string) => void
  /** Optional heading at the top of the menu. */
  label?: string
  className?: string
}) {
  const [uncontrolled, setUncontrolled] = React.useState(defaultValue ?? models[0]?.id)
  const value = controlled ?? uncontrolled
  const current = models.find((m) => m.id === value)

const select = (id: string) => {
    if (controlled === undefined) setUncontrolled(id)
    onValueChange?.(id)
  }

return (
    <DropdownMenu>
      <DropdownMenuTrigger
        render={
          <Button
            type="button"
            variant="ghost"
            size="sm"
            data-slot="model-picker"
            // Shrinks and truncates in a tight toolbar so the send button never gets pushed out.
            className={cn("min-w-0 shrink gap-1 text-muted-foreground", className)}
          />
        }
      >
        <span className="truncate">{current?.name ?? "Select model"}</span>
        <SelectIcon className="size-3 opacity-50" />
      </DropdownMenuTrigger>
      <DropdownMenuContent align="end" className="w-72">
        <DropdownMenuRadioGroup value={value} onValueChange={(v) => select(v as string)}>
          {label && <DropdownMenuLabel>{label}</DropdownMenuLabel>}
          {models.map((m) => (
            <DropdownMenuRadioItem
              key={m.id}
              value={m.id}
              className="items-start py-1.5 **:data-[slot=dropdown-menu-radio-item-indicator]:top-2"
            >
              <div className="flex min-w-0 flex-1 flex-col gap-0.5">
                <div className="flex items-center gap-1.5">
                  <span className="truncate">{m.name}</span>
                  {m.capabilities?.map((c) => (
                    <span
                      key={c}
                      title={capabilityMeta[c].label}
                      className="text-muted-foreground/70! [&_svg]:size-3.5"
                    >
                      {capabilityMeta[c].icon}
                      <span className="sr-only">{capabilityMeta[c].label}</span>
                    </span>
                  ))}
                </div>
                {(m.description || m.meta) && (
                  <span className="truncate text-xs text-muted-foreground!">
                    {[m.description, m.meta].filter(Boolean).join(" · ")}
                  </span>
                )}
              </div>
            </DropdownMenuRadioItem>
          ))}
        </DropdownMenuRadioGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}

export { ModelPicker, type Model, type ModelCapability }
```

---

# Branch

Step through versions of a response after regenerating. New versions are selected as they arrive.

Docs: https://jds-ruddy.vercel.app/docs/components/branch

## Installation

```bash
npx shadcn@latest add @jds/branch
```

npm dependencies: `cn`, `motion`

Also installs: `@jds/button`, `@jds/utils`

## Usage

```tsx
import { Branch, BranchContent, BranchSelector } from "@/components/ai/branch"

<Branch count={versions.length}>
  <BranchContent>
    {versions.map((v) => <Response key={v.id}>{v.text}</Response>)}
  </BranchContent>
  <BranchSelector />
</Branch>
```

## Example

```tsx
"use client"

import * as React from "react"

import { Branch, BranchContent, BranchSelector } from "@/components/ai/branch"
import { Message, MessageAction, MessageActions, MessageContent } from "@/components/ai/message"
import { RegenerateIcon } from "@/lib/icons"

const drafts = [
  "Thanks for your patience. Your refund is on its way and should arrive in 3 to 5 business days.",
  "Good news: we've issued your refund. Expect it within 3 to 5 business days.",
  "Your refund is done. It usually lands in 3 to 5 business days, depending on your bank.",
  "Refund issued. You'll see it in 3 to 5 business days. Anything else I can help with?",
]

export default function BranchDemo() {
  const [count, setCount] = React.useState(2)

return (
    <div className="flex w-full max-w-lg flex-col gap-6">
      <Message from="user">
        <MessageContent>Write a short reply confirming the refund.</MessageContent>
      </Message>
      <Message from="assistant">
        <MessageContent>
          <Branch count={count}>
            <BranchContent>
              {drafts.slice(0, count).map((d) => (
                <p key={d}>{d}</p>
              ))}
            </BranchContent>
            <div className="flex items-center gap-1">
              <BranchSelector />
              <MessageActions className="opacity-100">
                <MessageAction
                  label="Regenerate"
                  disabled={count >= drafts.length}
                  onClick={() => setCount((c) => Math.min(drafts.length, c + 1))}
                >
                  <RegenerateIcon />
                </MessageAction>
              </MessageActions>
            </div>
          </Branch>
        </MessageContent>
      </Message>
    </div>
  )
}
```

## API Reference

### Branch

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `count` | `number` |  | Number of versions. Growing it selects the newest. |
| `index` | `number` |  | Controlled active version. |
| `onIndexChange` | `(index: number) => void` |  |  |

## Source

### components/ai/branch.tsx

```tsx
"use client"

import * as React from "react"
import { AnimatePresence, motion } from "motion/react"
import { cn } from "cn"

import { Button } from "@/components/ui/button"
import { ChevronLeftIcon, ChevronRightIcon } from "@/lib/icons"
import { duration, ease } from "@/lib/motion"

type BranchContextValue = {
  index: number
  count: number
  setIndex: (i: number) => void
  direction: 1 | -1
}

const BranchContext = React.createContext<BranchContextValue | null>(null)

function useBranch() {
  const ctx = React.useContext(BranchContext)
  if (!ctx) throw new Error("Branch parts must be used inside <Branch>")
  return ctx
}

/**
 * Versions of one response, e.g. after regenerating. Holds which version is showing.
 * Put the versions in <BranchContent> and the arrows in <BranchSelector>.
 * New versions appended to `count` are selected automatically.
 */
function Branch({
  count,
  index: controlled,
  onIndexChange,
  className,
  ...props
}: React.ComponentProps<"div"> & {
  /** Number of versions. */
  count: number
  index?: number
  onIndexChange?: (index: number) => void
}) {
  const [uncontrolled, setUncontrolled] = React.useState(count - 1)
  const [prevCount, setPrevCount] = React.useState(count)
  const [direction, setDirection] = React.useState<1 | -1>(1)
  const index = controlled ?? uncontrolled

// Jump to a newly added version, as chat apps do after "Regenerate".
  if (count !== prevCount) {
    setPrevCount(count)
    if (count > prevCount && controlled === undefined) {
      setDirection(1)
      setUncontrolled(count - 1)
    }
  }

const setIndex = React.useCallback(
    (i: number) => {
      const next = Math.max(0, Math.min(count - 1, i))
      setDirection(next >= index ? 1 : -1)
      if (controlled === undefined) setUncontrolled(next)
      onIndexChange?.(next)
    },
    [count, index, controlled, onIndexChange]
  )

return (
    <BranchContext.Provider value={{ index, count, setIndex, direction }}>
      <div data-slot="branch" className={cn("flex flex-col gap-2", className)} {...props} />
    </BranchContext.Provider>
  )
}

/** Renders only the active version. Children are the versions, in order. */
function BranchContent({ children, className }: { children: React.ReactNode; className?: string }) {
  const { index, direction } = useBranch()
  const versions = React.Children.toArray(children)
  return (
    <div data-slot="branch-content" className={cn("relative", className)}>
      <AnimatePresence mode="popLayout" initial={false} custom={direction}>
        <motion.div
          key={index}
          custom={direction}
          initial={{ opacity: 0, x: direction * 12 }}
          animate={{ opacity: 1, x: 0 }}
          exit={{ opacity: 0, x: direction * -12 }}
          transition={{ duration: duration.base, ease: ease.out }}
        >
          {versions[index]}
        </motion.div>
      </AnimatePresence>
    </div>
  )
}

/** "‹ 2 / 3 ›". Hidden when there's only one version. */
function BranchSelector({ className, ...props }: React.ComponentProps<"div">) {
  const { index, count, setIndex } = useBranch()
  if (count < 2) return null
  return (
    <div
      data-slot="branch-selector"
      role="group"
      aria-label="Response versions"
      className={cn("flex items-center gap-0.5 text-xs text-muted-foreground", className)}
      {...props}
    >
      <Button
        variant="ghost"
        size="icon-xs"
        aria-label="Previous version"
        disabled={index === 0}
        onClick={() => setIndex(index - 1)}
      >
        <ChevronLeftIcon />
      </Button>
      <span className="min-w-8 text-center font-mono tabular-nums" aria-live="polite">
        {index + 1} / {count}
      </span>
      <Button
        variant="ghost"
        size="icon-xs"
        aria-label="Next version"
        disabled={index === count - 1}
        onClick={() => setIndex(index + 1)}
      >
        <ChevronRightIcon />
      </Button>
    </div>
  )
}

export { Branch, BranchContent, BranchSelector, useBranch }
```

---

# Context Meter

How full the context window is. A small ring for the toolbar that shifts to warning at 80% and destructive at 95%, with a breakdown on hover.

Docs: https://jds-ruddy.vercel.app/docs/components/context-meter

## Installation

```bash
npx shadcn@latest add @jds/context-meter
```

npm dependencies: `cn`, `motion`

Also installs: `@jds/popover`, `@jds/utils`

## Usage

```tsx
import { ContextMeter } from "@/components/ai/context-meter"

<ContextMeter
  used={usage.totalTokens}
  max={200_000}
  breakdown={[
    { label: "System and tools", tokens: 12_400 },
    { label: "Messages", tokens: 48_000 },
  ]}
/>
```

## Example

```tsx
import { ContextMeter } from "@/components/ai/context-meter"

const breakdown = (used: number) => [
  { label: "System and tools", tokens: 12_400 },
  { label: "Files", tokens: Math.round(used * 0.45) },
  { label: "Messages", tokens: Math.round(used * 0.55) - 12_400 },
]

export default function ContextMeterDemo() {
  return (
    <div className="flex items-center gap-6">
      <ContextMeter used={62_000} max={200_000} breakdown={breakdown(62_000)} />
      <ContextMeter used={168_000} max={200_000} breakdown={breakdown(168_000)} />
      <ContextMeter used={194_000} max={200_000} breakdown={breakdown(194_000)} />
    </div>
  )
}
```

## API Reference

### ContextMeter

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `used` | `number` |  | Tokens currently in context. |
| `max` | `number` |  | Context window size. |
| `breakdown` | `{ label, tokens }[]` |  | Shown in the hover card. |
| `showLabel` | `boolean` | `true` | Percentage next to the ring. |

## Source

### components/ai/context-meter.tsx

```tsx
"use client"

import * as React from "react"
import { motion } from "motion/react"
import { cn } from "cn"

import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"
import { spring } from "@/lib/motion"

type ContextUsage = {
  /** Tokens in the context window right now. */
  used: number
  /** Context window size. */
  max: number
  /** Optional split of `used`, shown on hover. */
  breakdown?: { label: string; tokens: number }[]
}

const format = (n: number) =>
  n >= 1_000_000 ? `${(n / 1_000_000).toFixed(1)}M` : n >= 1000 ? `${Math.round(n / 1000)}k` : `${n}`

/** Neutral until 80%, warning to 95%, then destructive. */
function level(ratio: number) {
  return ratio >= 0.95 ? "critical" : ratio >= 0.8 ? "warning" : "ok"
}

/**
 * How full the context window is, as a small ring that fits a toolbar.
 * Hover or focus for the exact numbers and what's using the space.
 */
function ContextMeter({
  used,
  max,
  breakdown,
  className,
  showLabel = true,
}: ContextUsage & { className?: string; showLabel?: boolean }) {
  const ratio = Math.min(1, used / max)
  const state = level(ratio)
  const r = 7
  const circumference = 2 * Math.PI * r

return (
    <Popover>
      <PopoverTrigger
        openOnHover
        delay={150}
        data-slot="context-meter"
        data-state={state}
        aria-label={`Context ${Math.round(ratio * 100)}% used`}
        className={cn(
          "group inline-flex h-7 items-center gap-1.5 rounded-md px-1.5 font-mono text-xs text-muted-foreground tabular-nums transition-colors outline-none hover:bg-accent focus-visible:ring-3 focus-visible:ring-ring/50",
          "data-[state=warning]:text-warning-foreground data-[state=critical]:text-destructive-foreground",
          className
        )}
      >
        <svg viewBox="0 0 18 18" className="size-4 -rotate-90">
          <circle cx="9" cy="9" r={r} fill="none" stroke="currentColor" strokeOpacity="0.2" strokeWidth="2.5" />
          <motion.circle
            cx="9"
            cy="9"
            r={r}
            fill="none"
            stroke="currentColor"
            strokeWidth="2.5"
            strokeLinecap="round"
            strokeDasharray={circumference}
            initial={false}
            animate={{ strokeDashoffset: circumference * (1 - ratio) }}
            transition={spring.gentle}
          />
        </svg>
        {showLabel && <span>{Math.round(ratio * 100)}%</span>}
      </PopoverTrigger>
      <PopoverContent align="end" className="w-64 gap-3 p-3">
        <div className="flex items-baseline justify-between text-sm">
          <span className="font-medium">Context</span>
          <span className="font-mono text-xs text-muted-foreground tabular-nums">
            {format(used)} / {format(max)}
          </span>
        </div>
        <div className="h-1.5 overflow-hidden rounded-full bg-muted">
          <motion.div
            className={cn(
              "h-full rounded-full bg-foreground",
              state === "warning" && "bg-warning",
              state === "critical" && "bg-destructive"
            )}
            initial={false}
            animate={{ width: `${ratio * 100}%` }}
            transition={spring.gentle}
          />
        </div>
        {breakdown && breakdown.length > 0 && (
          <dl className="flex flex-col gap-1.5 text-xs">
            {breakdown.map((b) => (
              <div key={b.label} className="flex justify-between gap-4">
                <dt className="text-muted-foreground">{b.label}</dt>
                <dd className="font-mono tabular-nums">{format(b.tokens)}</dd>
              </div>
            ))}
          </dl>
        )}
        {state !== "ok" && (
          <p className="text-xs text-muted-foreground">
            {state === "critical"
              ? "Nearly full. Older messages will be summarized or dropped."
              : "Getting full. Long threads may lose early detail."}
          </p>
        )}
      </PopoverContent>
    </Popover>
  )
}

export { ContextMeter, type ContextUsage }
```

---

# Artifact

A generated document or file in its own panel beside the chat, opened from a card in the message.

Docs: https://jds-ruddy.vercel.app/docs/components/artifact

## Installation

```bash
npx shadcn@latest add @jds/artifact
```

npm dependencies: `cn`

Also installs: `@jds/button`, `@jds/tooltip`, `@jds/utils`

## Usage

```tsx
import {
  Artifact,
  ArtifactAction,
  ArtifactActions,
  ArtifactCard,
  ArtifactContent,
  ArtifactHeader,
} from "@/components/ai/artifact"

<ArtifactCard title="Q3 pricing update" description="Document · v1" onOpen={() => setOpen(true)} />

<Artifact>
  <ArtifactHeader title="Q3 pricing update" description="Document · v1">
    <ArtifactActions>
      <ArtifactAction label="Copy"><CopyIcon /></ArtifactAction>
    </ArtifactActions>
  </ArtifactHeader>
  <ArtifactContent>…</ArtifactContent>
</Artifact>
```

## Example

```tsx
"use client"

import * as React from "react"
import { AnimatePresence, motion } from "motion/react"
import { toast } from "sonner"

import {
  Artifact,
  ArtifactAction,
  ArtifactActions,
  ArtifactCard,
  ArtifactContent,
  ArtifactHeader,
} from "@/components/ai/artifact"
import { Message, MessageContent } from "@/components/ai/message"
import { Response } from "@/components/ai/response"
import { CloseIcon, CodeIcon, CopyIcon, DownloadIcon, PreviewIcon } from "@/lib/icons"
import { spring } from "@/lib/motion"

const DOC = `# Q3 pricing update

We're moving the Team plan from **€12 to €14** per seat per month, starting 1 October.

## What stays the same
- Annual customers keep their current price until renewal
- Free and Enterprise plans are unchanged

## Why
Usage of agent features tripled this year. The new price funds more capacity.
`

export default function ArtifactDemo() {
  const [open, setOpen] = React.useState(true)
  const [source, setSource] = React.useState(false)

return (
    <div className="flex h-112 w-full gap-3">
      <div className="flex min-w-0 flex-1 flex-col gap-5 p-2">
        <Message from="user">
          <MessageContent>Draft the pricing announcement.</MessageContent>
        </Message>
        <Message from="assistant">
          <MessageContent>
            <p>Here's a first draft. I led with what stays the same.</p>
            <ArtifactCard
              title="Q3 pricing update"
              description="Document · v1"
              active={open}
              onOpen={() => setOpen(true)}
            />
          </MessageContent>
        </Message>
      </div>

<AnimatePresence initial={false}>
        {open && (
          <motion.div
            initial={{ width: 0, opacity: 0 }}
            animate={{ width: "55%", opacity: 1 }}
            exit={{ width: 0, opacity: 0 }}
            transition={spring.gentle}
            className="min-w-0 shrink-0 overflow-hidden"
          >
            <Artifact className="min-w-80">
              <ArtifactHeader title="Q3 pricing update" description="Document · v1">
                <ArtifactActions>
                  <ArtifactAction label={source ? "Show preview" : "Show source"} onClick={() => setSource((v) => !v)}>
                    {source ? <PreviewIcon /> : <CodeIcon />}
                  </ArtifactAction>
                  <ArtifactAction label="Copy" onClick={() => toast("Copied")}>
                    <CopyIcon />
                  </ArtifactAction>
                  <ArtifactAction label="Download" onClick={() => toast("Downloaded")}>
                    <DownloadIcon />
                  </ArtifactAction>
                  <ArtifactAction label="Close" onClick={() => setOpen(false)}>
                    <CloseIcon />
                  </ArtifactAction>
                </ArtifactActions>
              </ArtifactHeader>
              <ArtifactContent>
                {source ? (
                  <pre className="font-mono text-xs leading-relaxed whitespace-pre-wrap text-muted-foreground">
                    {DOC}
                  </pre>
                ) : (
                  <Response>{DOC}</Response>
                )}
              </ArtifactContent>
            </Artifact>
          </motion.div>
        )}
      </AnimatePresence>
    </div>
  )
}
```

## API Reference

### ArtifactCard

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` |  |  |
| `description` | `string` |  | Kind and version. |
| `kind` | `"document" \| "code"` | `"document"` | Sets the icon. |
| `active` | `boolean` |  | Highlights the card while its panel is open. |
| `onOpen` | `() => void` |  |  |

## Source

### components/ai/artifact.tsx

```tsx
"use client"

import * as React from "react"
import { cn } from "cn"

import { Button } from "@/components/ui/button"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"
import { ChevronRightIcon, CodeIcon, FileIcon } from "@/lib/icons"

/**
 * A generated document, page or file, shown in its own panel next to the chat.
 * Compose: <Artifact> > <ArtifactHeader> (with <ArtifactActions>) + <ArtifactContent>.
 */
function Artifact({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="artifact"
      className={cn("flex h-full min-h-0 flex-col overflow-hidden rounded-xl border bg-card", className)}
      {...props}
    />
  )
}

function ArtifactHeader({
  title,
  description,
  className,
  children,
  ...props
}: Omit<React.ComponentProps<"div">, "title"> & { title: React.ReactNode; description?: React.ReactNode }) {
  return (
    <div
      data-slot="artifact-header"
      className={cn("flex min-h-12 shrink-0 items-center gap-3 border-b px-4 py-2", className)}
      {...props}
    >
      <div className="min-w-0 flex-1">
        <div className="truncate text-sm font-medium">{title}</div>
        {description && <div className="truncate text-xs text-muted-foreground">{description}</div>}
      </div>
      {children}
    </div>
  )
}

function ArtifactActions({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="artifact-actions" className={cn("flex items-center gap-0.5", className)} {...props} />
}

function ArtifactAction({ label, className, ...props }: React.ComponentProps<typeof Button> & { label: string }) {
  return (
    <Tooltip>
      <TooltipTrigger
        render={
          <Button
            variant="ghost"
            size="icon-sm"
            aria-label={label}
            className={cn("text-muted-foreground", className)}
            {...props}
          />
        }
      />
      <TooltipContent>{label}</TooltipContent>
    </Tooltip>
  )
}

function ArtifactContent({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="artifact-content" className={cn("min-h-0 flex-1 overflow-auto p-4", className)} {...props} />
}

/** Inline card in a message that opens the artifact. */
function ArtifactCard({
  title,
  description,
  kind = "document",
  active,
  onOpen,
  className,
}: {
  title: string
  description?: string
  kind?: "document" | "code"
  /** True while this artifact is open in the panel. */
  active?: boolean
  onOpen?: () => void
  className?: string
}) {
  return (
    <button
      type="button"
      data-slot="artifact-card"
      data-active={active || undefined}
      onClick={onOpen}
      className={cn(
        "group flex w-full max-w-sm items-center gap-3 rounded-xl border bg-card p-3 text-left transition-colors outline-none hover:bg-accent/50 focus-visible:ring-3 focus-visible:ring-ring/50 data-active:border-foreground/30",
        className
      )}
    >
      <span className="grid size-9 shrink-0 place-items-center rounded-lg bg-muted text-muted-foreground [&_svg]:size-4">
        {kind === "code" ? <CodeIcon /> : <FileIcon />}
      </span>
      <span className="min-w-0 flex-1">
        <span className="block truncate text-sm font-medium">{title}</span>
        {description && <span className="block truncate text-xs text-muted-foreground">{description}</span>}
      </span>
      <ChevronRightIcon className="size-4 text-muted-foreground transition-transform group-hover:translate-x-0.5" />
    </button>
  )
}

export { Artifact, ArtifactHeader, ArtifactActions, ArtifactAction, ArtifactContent, ArtifactCard }
```

---

# Agent Panel

A configurable agent side panel: docked or floating, left or right, card, page or glass surface, three entrance motions, and chat/voice modes.

Docs: https://jds-ruddy.vercel.app/docs/components/agent-panel

## Installation

```bash
npx shadcn@latest add @jds/agent-panel
```

npm dependencies: `cn`, `motion`

Also installs: `@jds/button`, `@jds/tooltip`, `@jds/utils`, `@jds/voice-orb`

## Usage

```tsx
import {
  AgentPanel,
  AgentPanelBody,
  AgentPanelFooter,
  AgentPanelHeader,
  AgentPanelVoiceButton,
  AgentPanelVoiceExit,
} from "@/components/ai/agent-panel"

<AgentPanel open={open} onOpenChange={setOpen} variant="floating" surface="glass">
  <AgentPanelHeader title="Agent" icon="orb" />
  <AgentPanelBody
    chat={<Conversation>…</Conversation>}
    voice={<><VoiceOrb … /><AgentPanelVoiceExit /></>}
  />
  <AgentPanelFooter>
    <PromptInput>
      <PromptInputTextarea />
      <PromptInputToolbar>
        <PromptInputTools />
        <AgentPanelVoiceButton />
        <PromptInputSubmit />
      </PromptInputToolbar>
    </PromptInput>
  </AgentPanelFooter>
</AgentPanel>
```

## Example

```tsx
"use client"

import * as React from "react"

import {
  AgentPanel,
  AgentPanelBody,
  AgentPanelFooter,
  AgentPanelHeader,
  AgentPanelVoiceButton,
  AgentPanelVoiceExit,
} from "@/components/ai/agent-panel"
import { ConversationEmpty } from "@/components/ai/conversation"
import {
  PromptInput,
  PromptInputSubmit,
  PromptInputTextarea,
  PromptInputToolbar,
  PromptInputTools,
} from "@/components/ai/prompt-input"
import { Button } from "@/components/ui/button"
import { VoiceOrb } from "@/components/voice/voice-orb"

export default function AgentPanelDemo() {
  const [open, setOpen] = React.useState(true)
  return (
    <div className="relative h-112 w-full overflow-hidden rounded-xl border bg-background">
      {!open && (
        <Button size="sm" className="absolute top-3 right-3" onClick={() => setOpen(true)}>
          Open agent
        </Button>
      )}
      <AgentPanel open={open} onOpenChange={setOpen} variant="floating" width={340} contained>
        <AgentPanelHeader title="Agent" />
        <AgentPanelBody
          chat={<ConversationEmpty title="Ask about this page" />}
          voice={
            <div className="flex flex-1 flex-col items-center justify-center gap-6">
              <VoiceOrb state="idle" size={160} />
              <AgentPanelVoiceExit />
            </div>
          }
        />
        <AgentPanelFooter>
          <PromptInput onSubmit={() => {}}>
            <PromptInputTextarea />
            <PromptInputToolbar>
              <PromptInputTools />
              <div className="flex items-center gap-1">
                <AgentPanelVoiceButton />
                <PromptInputSubmit />
              </div>
            </PromptInputToolbar>
          </PromptInput>
        </AgentPanelFooter>
      </AgentPanel>
    </div>
  )
}
```

## API Reference

### AgentPanel

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` |  |  |
| `onOpenChange` | `(open: boolean) => void` |  | Enables the close button. |
| `side` | `"left" \| "right"` | `"right"` |  |
| `variant` | `"docked" \| "floating"` | `"docked"` | Docked runs full height on an edge; floating is inset and rounded. |
| `surface` | `"card" \| "background" \| "glass"` | `"card"` | Glass blurs what is behind it. |
| `width` | `number` | `400` | In px, capped to the available space. |
| `inset` | `number` | `12` | Edge gap when floating, in px. |
| `motion` | `"slide" \| "fade" \| "spring"` | `"spring"` | Entrance and exit. |
| `contained` | `boolean` | `false` | Position inside the nearest positioned ancestor instead of the viewport. |
| `mode` | `"chat" \| "voice"` |  | Controlled mode. Or defaultMode with onModeChange. |

### AgentPanelHeader

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `"Agent"` |  |
| `icon` | `"sparkle" \| "orb" \| "none"` | `"sparkle"` | "orb" shows a small live Voice Orb. |
| `modes` | `("chat" \| "voice")[]` |  | Shows a chat/voice switch when there is more than one. |
| `showClose` | `boolean` | `true` |  |

### AgentPanelVoiceButton

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `…Button props` | `ButtonProps` |  | Enters voice mode. Put it in the composer toolbar, next to send: the usual place, since people choose voice when they'd otherwise type. |

### AgentPanelVoiceExit

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | `"End voice"` | Returns to chat. Put it in the voice view. |

### AgentPanelBody

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `chat` | `ReactNode` |  | Shown in chat mode. |
| `voice` | `ReactNode` |  | Shown in voice mode. The footer hides in voice mode. |

## Source

### components/ai/agent-panel.tsx

```tsx
"use client"

import * as React from "react"
import { AnimatePresence, motion, type TargetAndTransition, type Transition } from "motion/react"
import { cn } from "cn"

import { Button } from "@/components/ui/button"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"
import { VoiceOrb } from "@/components/voice/voice-orb"
import { CloseIcon, SparkleIcon, VoiceIcon } from "@/lib/icons"
import { spring } from "@/lib/motion"

type AgentPanelContextValue = {
  mode: PanelMode
  setMode: (mode: PanelMode) => void
  onClose?: () => void
}

const AgentPanelContext = React.createContext<AgentPanelContextValue | null>(null)

function useAgentPanel() {
  const ctx = React.useContext(AgentPanelContext)
  if (!ctx) throw new Error("AgentPanel parts must be used inside <AgentPanel>")
  return ctx
}

const motionPresets: Record<PanelMotion, { offset: (side: PanelSide) => TargetAndTransition; transition: Transition }> =
  {
    slide: {
      offset: (side) => ({ x: side === "right" ? "100%" : "-100%" }),
      transition: { type: "tween", duration: 0.32, ease: [0.22, 1, 0.36, 1] },
    },
    fade: { offset: () => ({ opacity: 0 }), transition: { duration: 0.2 } },
    spring: {
      offset: (side) => ({ x: side === "right" ? 48 : -48, opacity: 0, scale: 0.97 }),
      transition: spring.gentle,
    },
  }

const surfaces: Record<PanelSurface, string> = {
  card: "bg-card",
  background: "bg-background",
  glass: "bg-background/70 backdrop-blur-xl backdrop-saturate-150",
}

/**
 * An agent side panel. Docked panels run full height against an edge; floating panels
 * sit inset with rounded corners and a shadow. `contained` positions it inside the
 * nearest positioned ancestor instead of the viewport.
 */
function AgentPanel({
  open,
  onOpenChange,
  side = "right",
  variant = "docked",
  surface = "card",
  width = 400,
  inset = 12,
  motion: motionPreset = "spring",
  contained = false,
  mode: controlledMode,
  defaultMode = "chat",
  onModeChange,
  className,
  children,
}: {
  open: boolean
  onOpenChange?: (open: boolean) => void
  side?: PanelSide
  variant?: PanelVariant
  surface?: PanelSurface
  /** Width in px. Capped to the available space. */
  width?: number
  /** Gap from the edges when floating, in px. */
  inset?: number
  motion?: PanelMotion
  /** Position inside the nearest positioned ancestor instead of the viewport. */
  contained?: boolean
  mode?: PanelMode
  defaultMode?: PanelMode
  onModeChange?: (mode: PanelMode) => void
  className?: string
  children: React.ReactNode
}) {
  const [uncontrolledMode, setUncontrolledMode] = React.useState(defaultMode)
  const mode = controlledMode ?? uncontrolledMode
  const setMode = React.useCallback(
    (m: PanelMode) => {
      if (controlledMode === undefined) setUncontrolledMode(m)
      onModeChange?.(m)
    },
    [controlledMode, onModeChange],
  )
  const preset = motionPresets[motionPreset]
  const floating = variant === "floating"

return (
    <AgentPanelContext.Provider value={{ mode, setMode, onClose: onOpenChange && (() => onOpenChange(false)) }}>
      <AnimatePresence>
        {open && (
          <motion.aside
            key="agent-panel"
            data-slot="agent-panel"
            data-side={side}
            data-variant={variant}
            aria-label="Agent"
            initial={preset.offset(side)}
            animate={{ x: 0, opacity: 1, scale: 1 }}
            exit={preset.offset(side)}
            transition={preset.transition}
            className={cn(
              contained ? "absolute" : "fixed",
              "z-40 flex w-(--panel-w) max-w-[calc(100%-var(--panel-inset)*2)] flex-col overflow-hidden text-sm",
              surfaces[surface],
              floating
                ? "inset-y-(--panel-inset) rounded-2xl border shadow-2xl"
                : "inset-y-0 data-[side=left]:border-r data-[side=right]:border-l",
              side === "right"
                ? floating
                  ? "right-(--panel-inset)"
                  : "right-0"
                : floating
                  ? "left-(--panel-inset)"
                  : "left-0",
              className,
            )}
            style={{ "--panel-w": `${width}px`, "--panel-inset": `${floating ? inset : 0}px` } as React.CSSProperties}
          >
            {children}
          </motion.aside>
        )}
      </AnimatePresence>
    </AgentPanelContext.Provider>
  )
}

/** Title row: an icon or live orb, the title, an optional chat/voice switch and close. */
function AgentPanelHeader({
  title = "Agent",
  icon = "sparkle",
  modes,
  showClose = true,
  className,
  children,
}: {
  title?: string
  /** "orb" shows a small live Voice Orb. */
  icon?: "sparkle" | "orb" | "none"
  /** Show a chat/voice switch when more than one mode is listed. */
  modes?: PanelMode[]
  showClose?: boolean
  className?: string
  /** Extra controls, placed before the close button. */
  children?: React.ReactNode
}) {
  const { mode, setMode, onClose } = useAgentPanel()
  return (
    <div
      data-slot="agent-panel-header"
      className={cn("flex h-12 shrink-0 items-center gap-2 border-b px-3", className)}
    >
      {icon === "sparkle" && <SparkleIcon className="size-4 shrink-0" />}
      {icon === "orb" && <VoiceOrb variant="aura" size={22} state={mode === "voice" ? "listening" : "idle"} />}
      <span className="truncate font-medium">{title}</span>
      <div className="ml-auto flex items-center gap-1">
        {modes && modes.length > 1 && (
          <div role="tablist" aria-label="Mode" className="flex rounded-lg bg-muted p-0.5">
            {modes.map((m) => (
              <button
                key={m}
                type="button"
                role="tab"
                aria-selected={mode === m}
                onClick={() => setMode(m)}
                className="relative flex h-6 items-center gap-1 rounded-md px-2 text-xs text-muted-foreground transition-colors aria-selected:text-foreground [&_svg]:size-3.5"
              >
                {mode === m && (
                  <motion.span
                    layoutId="agent-panel-mode"
                    className="absolute inset-0 rounded-md bg-background shadow-xs"
                    transition={spring.snappy}
                  />
                )}
                <span className="relative flex items-center gap-1">
                  {m === "voice" ? <VoiceIcon /> : <SparkleIcon />}
                  {m === "voice" ? "Voice" : "Chat"}
                </span>
              </button>
            ))}
          </div>
        )}
        {children}
        {showClose && onClose && (
          <Button variant="ghost" size="icon-sm" aria-label="Close agent" onClick={onClose}>
            <CloseIcon />
          </Button>
        )}
      </div>
    </div>
  )
}

/** Main area. Renders `chat` or `voice` content for the current mode. */
function AgentPanelBody({
  chat,
  voice,
  className,
}: {
  chat: React.ReactNode
  voice?: React.ReactNode
  className?: string
}) {
  const { mode } = useAgentPanel()
  const showVoice = mode === "voice" && voice
  return (
    <div data-slot="agent-panel-body" className={cn("relative flex min-h-0 flex-1 flex-col", className)}>
      <AnimatePresence mode="wait" initial={false}>
        <motion.div
          key={showVoice ? "voice" : "chat"}
          initial={{ opacity: 0, y: 8 }}
          animate={{ opacity: 1, y: 0 }}
          exit={{ opacity: 0, y: -8 }}
          transition={spring.gentle}
          className="flex min-h-0 flex-1 flex-col"
        >
          {showVoice ? voice : chat}
        </motion.div>
      </AnimatePresence>
    </div>
  )
}

/**
 * Enters voice mode from the composer, next to send. The usual place for it:
 * people choose voice at the moment they would otherwise type.
 */
function AgentPanelVoiceButton({ className, ...props }: React.ComponentProps<typeof Button>) {
  const { setMode } = useAgentPanel()
  return (
    <Tooltip>
      <TooltipTrigger
        render={
          <Button
            type="button"
            variant="ghost"
            size="icon-sm"
            aria-label="Voice mode"
            data-slot="agent-panel-voice-button"
            className={cn("text-muted-foreground", className)}
            onClick={() => setMode("voice")}
            {...props}
          />
        }
      >
        <VoiceIcon />
      </TooltipTrigger>
      <TooltipContent>Voice mode</TooltipContent>
    </Tooltip>
  )
}

/** Leaves voice mode and returns to chat. Place it in the voice view. */
function AgentPanelVoiceExit({ className, children = "End voice", ...props }: React.ComponentProps<typeof Button>) {
  const { setMode } = useAgentPanel()
  return (
    <Button
      type="button"
      variant="outline"
      size="sm"
      data-slot="agent-panel-voice-exit"
      className={className}
      onClick={() => setMode("chat")}
      {...props}
    >
      <CloseIcon />
      {children}
    </Button>
  )
}

function AgentPanelFooter({ className, ...props }: React.ComponentProps<"div">) {
  const { mode } = useAgentPanel()
  if (mode === "voice") return null
  return <div data-slot="agent-panel-footer" className={cn("shrink-0 p-3 pt-0", className)} {...props} />
}

export {
  AgentPanel,
  AgentPanelHeader,
  AgentPanelBody,
  AgentPanelFooter,
  AgentPanelVoiceButton,
  AgentPanelVoiceExit,
  useAgentPanel,
  type PanelSide,
  type PanelVariant,
  type PanelSurface,
  type PanelMotion,
  type PanelMode,
}
```

---

# Voice Orb

Presence for a voice agent, drawn in the primary color. Ten variants: particle mesh, glowing ring, twisting ribbons, soft aura, circular bars, halftone dots, three WebGL shaders (plasma, liquid and glass), and a minimal dot for small spots. All share the same states, speed, glow and sensitivity, and react to voice level. Tune one in the Studio.

Docs: https://jds-ruddy.vercel.app/docs/components/voice-orb

## Installation

```bash
npx shadcn@latest add @jds/voice-orb
```

npm dependencies: `cn`

## Usage

```tsx
import { VoiceOrb, VoiceOrbProvider } from "@/components/voice/voice-orb"

// Or style every orb in the app once, at the root
<VoiceOrbProvider variant="glass" palette="iris" glow={0.3}>{children}</VoiceOrbProvider>
```

## Example

```tsx
"use client"

import * as React from "react"

import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs"
import { VoiceOrb, type VoiceState } from "@/components/voice/voice-orb"
import { useSimulatedSpectrum } from "@/hooks/use-simulated-spectrum"

const states: VoiceState[] = ["idle", "listening", "thinking", "speaking"]

export default function VoiceOrbDemo() {
  const [state, setState] = React.useState<VoiceState>("idle")
  const { level } = useSimulatedSpectrum(state === "listening" || state === "speaking")

return (
    <div className="flex flex-col items-center gap-8">
      <VoiceOrb state={state} level={level} size={260} />
      <Tabs value={state} onValueChange={(v) => setState(v as VoiceState)}>
        <TabsList>
          {states.map((s) => (
            <TabsTrigger key={s} value={s}>
              {s[0].toUpperCase() + s.slice(1)}
            </TabsTrigger>
          ))}
        </TabsList>
      </Tabs>
    </div>
  )
}
```

### Variants

```tsx
"use client"

import * as React from "react"

import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs"
import { VoiceOrb, type VoiceOrbVariant, type VoiceState } from "@/components/voice/voice-orb"
import { useSimulatedSpectrum } from "@/hooks/use-simulated-spectrum"

const states: VoiceState[] = ["idle", "listening", "thinking", "speaking"]
const variants: VoiceOrbVariant[] = ["particles", "ring", "aura", "plasma", "liquid", "glass", "bars", "halftone", "wave", "dot"]

export default function VoiceOrbVariantsDemo() {
  const [state, setState] = React.useState<VoiceState>("listening")
  const { level } = useSimulatedSpectrum(state === "listening" || state === "speaking")

return (
    <div className="flex w-full flex-col items-center gap-8">
      <div className="grid w-full grid-cols-2 gap-8 sm:grid-cols-4">
        {variants.map((v) => (
          <div key={v} className="flex flex-col items-center justify-end gap-3">
            <VoiceOrb variant={v} state={state} level={level} size={v === "wave" ? 70 : v === "dot" ? 40 : 130} />
            <code className="font-mono text-xs text-muted-foreground">{v}</code>
          </div>
        ))}
      </div>
      <Tabs value={state} onValueChange={(v) => setState(v as VoiceState)}>
        <TabsList>
          {states.map((s) => (
            <TabsTrigger key={s} value={s}>
              {s[0].toUpperCase() + s.slice(1)}
            </TabsTrigger>
          ))}
        </TabsList>
      </Tabs>
    </div>
  )
}
```

### Aura palettes

```tsx
"use client"

import * as React from "react"

import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs"
import { VoiceOrb, type OrbPalette, type VoiceState } from "@/components/voice/voice-orb"
import { useSimulatedSpectrum } from "@/hooks/use-simulated-spectrum"

const palettes: OrbPalette[] = ["mist", "iris", "ember", "cocoa", "primary"]
const states: VoiceState[] = ["idle", "listening", "thinking", "speaking"]

export default function VoiceOrbAuraDemo() {
  const [state, setState] = React.useState<VoiceState>("idle")
  const { level } = useSimulatedSpectrum(state === "listening" || state === "speaking")
  return (
    <div className="flex w-full flex-col items-center gap-8">
      <div className="flex flex-wrap items-end justify-center gap-6">
        {palettes.map((p) => (
          <div key={p} className="flex flex-col items-center gap-3">
            <VoiceOrb variant="aura" palette={p} state={state} level={level} size={p === "ember" ? 150 : 110} />
            <code className="font-mono text-xs text-muted-foreground">{p}</code>
          </div>
        ))}
      </div>
      <Tabs value={state} onValueChange={(v) => setState(v as VoiceState)}>
        <TabsList>
          {states.map((s) => (
            <TabsTrigger key={s} value={s}>
              {s[0].toUpperCase() + s.slice(1)}
            </TabsTrigger>
          ))}
        </TabsList>
      </Tabs>
    </div>
  )
}
```

## API Reference

### VoiceOrb

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"particles" \| "ring" \| "wave" \| "aura" \| "bars" \| "halftone" \| "plasma" \| "liquid" \| "glass" \| "dot"` | `provider, else "particles"` | Visual style. Omit to use the nearest VoiceOrbProvider. |
| `state` | `"idle" \| "connecting" \| "listening" \| "thinking" \| "speaking" \| "error"` | `"idle"` | Same meaning on every variant. Connecting breathes; error turns destructive and nearly still. |
| `level` | `number` | `0` | Loudness 0 to 1. Smoothed with a spring. |
| `sensitivity` | `number` | `1` | Multiplies level before it moves the orb, capped at 1. Raise it for quiet sources. |
| `speed` | `number` | `1` | Animation speed multiplier. |
| `glow` | `number` | `0` | Soft light around the orb, 0 to 1. Named aura palettes glow in their own color. |
| `size` | `number` | `160` | Size in px. Wave renders 2x wide and 0.6x tall, capped to its container. Dot is built for 16 to 48px. Color follows --primary; override with a text-* class. |
| `palette` | `"primary" \| "iris" \| "ember" \| "cocoa" \| "mist" \| string[]` | `"primary"` | Aura, plasma, liquid and glass. A named palette, or four colors: base, then three fields. Primary builds shades of --primary. |
| `particles` | `number` | `size² × 0.07` | Particles variant only. Approximate count, capped at 6000. |
| `thickness` | `number` | `1` | Ring: stroke weight. Glass: how strongly it bends and tints the light. |
| `gloss` | `number` | `1` | Liquid and glass: highlight strength. |
| `blobs` | `number` | `5` | Liquid: number of blobs, 1 to 8. |
| `turbulence` | `number` | `1` | Plasma: how strongly the noise warps. |
| `filaments` | `number` | `1` | Plasma: brightness of the flaring streaks. |
| `grain` | `number` | `1` | Aura: film grain strength, 0 to 2. |
| `bars` | `number` | `56` | Bars: number of bars. |
| `density` | `number` | `1` | Halftone: dot grid density multiplier. |

### VoiceOrbProvider

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"particles" \| "ring" \| "wave" \| "aura" \| "bars" \| "halftone" \| "plasma" \| "liquid" \| "glass" \| "dot"` |  | Default variant for every VoiceOrb inside. |
| `palette, glow, speed, sensitivity, …` | `same as VoiceOrb` |  | Any style prop except size becomes the default for every orb inside, so one provider at the root styles the whole app. Props on a VoiceOrb win; classes combine. |

## Source

### components/voice/voice-orb.tsx

```tsx
"use client"

import * as React from "react"
import { cn } from "cn"

/**
 * Semantic states every orb supports. Connecting breathes while a session opens;
 * error turns destructive and nearly still, so it reads without relying on color.
 */
type VoiceState = "idle" | "connecting" | "listening" | "thinking" | "speaking" | "error"

/** A point on the sphere in latitude/longitude, so the surface can wave along its lines. */
type Particle = { lat: number; lon: number; size: number; phase: number }

/** Per-state motion targets. Values are eased toward, so state changes never jump. */
const targets: Record<VoiceState, { spin: number; swell: number; wave: number; speed: number; scale: number }> = {
  idle: { spin: 0.1, swell: 0, wave: 0.025, speed: 0.6, scale: 1 },
  connecting: { spin: 0.35, swell: 0, wave: 0.035, speed: 1.4, scale: 0.9 },
  listening: { spin: 0.16, swell: 1, wave: 0.03, speed: 1.2, scale: 1 },
  thinking: { spin: 0.7, swell: 0, wave: 0.06, speed: 2.4, scale: 0.95 },
  speaking: { spin: 0.2, swell: 0.7, wave: 0.045, speed: 1.6, scale: 1 },
  error: { spin: 0.02, swell: 0, wave: 0.012, speed: 0.3, scale: 0.94 },
}

/**
 * Rings of latitude with points spaced along each ring. Slight jitter keeps the
 * mesh organic; the ring structure shows up as fine wavy lines once displaced.
 */
function createParticles(target: number): Particle[] {
  const rings = Math.max(12, Math.round(Math.sqrt((target * Math.PI) / 4)))
  const points: Particle[] = []
  for (let i = 0; i < rings; i++) {
    const lat = -Math.PI / 2 + ((i + 0.5) / rings) * Math.PI
    const perRing = Math.max(6, Math.round(rings * 2 * Math.cos(lat)))
    const offset = Math.random() * Math.PI * 2
    for (let j = 0; j < perRing; j++) {
      points.push({
        lat: lat + (Math.random() - 0.5) * (Math.PI / rings) * 0.35,
        lon: offset + (j / perRing) * Math.PI * 2,
        size: 0.8 + Math.random() ** 3 * 0.9,
        phase: Math.random() * Math.PI * 2,
      })
    }
  }
  return points
}

type OrbProps = React.ComponentProps<"div"> & {
  state?: VoiceState
  /** Input or output loudness, 0 to 1. */
  level?: number
  /** Rendered size in px. */
  size?: number
  /** Animation speed multiplier. 1 is the designed pace. */
  speed?: number
  /** Soft light around the orb in its own color, 0 to 1. */
  glow?: number
}

/**
 * Rotating mesh of particles. Undulates gently when idle, swells with `level` while
 * listening, spins faster while thinking, and pulses while speaking. Edges glow
 * brighter than the center, like light catching the rim of a sphere.
 */
function ParticleOrb({
  state = "idle",
  level = 0,
  size = 160,
  speed = 1,
  glow = 0,
  particles,
  className,
  ...props
}: OrbProps & {
  /** Approximate particle count. Defaults to scale with size. */
  particles?: number
}) {
  const canvasRef = React.useRef<HTMLCanvasElement>(null)
  const input = React.useRef({ state, level, speed })
  const redraw = React.useRef<(() => void) | null>(null)
  const count = particles ?? Math.round(Math.min(6000, size * size * 0.07))

React.useEffect(() => {
    input.current = { state, level, speed }
    redraw.current?.()
  }, [state, level, speed])

React.useEffect(() => {
    const canvas = canvasRef.current
    const ctx = canvas?.getContext("2d")
    if (!canvas || !ctx) return

const reduced = window.matchMedia("(prefers-reduced-motion: reduce)").matches
    const dpr = Math.min(window.devicePixelRatio || 1, 2)
    const px = size * dpr
    canvas.width = px
    canvas.height = px

const points = createParticles(count)
    const cur = { ...targets.idle, level: 0, angle: 0, time: 0 }
    let last = performance.now()
    let raf = 0

const draw = (now: number) => {
      const dt = reduced ? 0 : Math.max(0, Math.min(0.05, (now - last) / 1000))
      last = now
      const { state, level, speed } = input.current
      const target = targets[state]
      const k = reduced ? 1 : 1 - Math.exp(-dt * 5)
      cur.spin += (target.spin - cur.spin) * k
      cur.swell += (target.swell - cur.swell) * k
      cur.wave += (target.wave - cur.wave) * k
      cur.speed += (target.speed - cur.speed) * k
      cur.scale += (target.scale - cur.scale) * k
      const targetLevel = state === "listening" || state === "speaking" ? level : 0
      cur.level += (targetLevel - cur.level) * (reduced ? 1 : 1 - Math.exp(-dt * 12))
      cur.angle += cur.spin * dt * speed
      cur.time += cur.speed * dt * speed
      const t = cur.time

const radius = px * 0.4 * cur.scale
      const c = px / 2
      const tilt = 0.3
      const cosT = Math.cos(tilt)
      const sinT = Math.sin(tilt)
      const amp = cur.wave + cur.swell * cur.level * 0.16

ctx.clearRect(0, 0, px, px)
      ctx.fillStyle = getComputedStyle(canvas).color

for (const p of points) {
        // Longitude snakes a little, turning rings of dots into wavy lines.
        const lon = p.lon + cur.angle + Math.sin(p.lat * 7 + t * 0.9) * 0.05
        const cosLat = Math.cos(p.lat)
        const x = cosLat * Math.cos(lon)
        const y = Math.sin(p.lat)
        const z = cosLat * Math.sin(lon)

// Tilt toward the viewer so the rotation axis reads as 3D.
        const y2 = y * cosT - z * sinT
        const z2 = y * sinT + z * cosT

const bump =
          Math.sin(lon * 3 + p.lat * 4 + t) * Math.sin(p.lat * 5 - t * 0.7) +
          0.5 * Math.sin(lon * 7 - t * 1.3 + p.phase * 0.2)
        const r = radius * (1 + amp * bump)

// Front faces are brighter, and the silhouette glows.
        const facing = (z2 + 1) / 2
        const rim = 1 - Math.abs(z2)
        ctx.globalAlpha = Math.min(1, 0.12 + facing * 0.5 + rim ** 3 * 0.5)
        const s = p.size * dpr * (0.7 + facing * 0.4)
        ctx.fillRect(c + x * r - s / 2, c + y2 * r - s / 2, s, s)
      }
      ctx.globalAlpha = 1
      if (!reduced) raf = requestAnimationFrame(draw)
    }

redraw.current = reduced ? () => draw(performance.now()) : null
    raf = requestAnimationFrame(draw)
    return () => {
      cancelAnimationFrame(raf)
      redraw.current = null
    }
  }, [size, count])

return orbFrame("particles", state, size, glow, className, props, <canvas ref={canvasRef} className="size-full" />)
}

/** Per-state targets for the ring. */
const ringTargets: Record<VoiceState, { wobble: number; spin: number; scale: number; width: number }> = {
  idle: { wobble: 0.018, spin: 0.15, scale: 1, width: 1 },
  connecting: { wobble: 0.02, spin: 0.9, scale: 0.9, width: 0.8 },
  listening: { wobble: 0.03, spin: 0.25, scale: 1, width: 1.2 },
  thinking: { wobble: 0.035, spin: 1.6, scale: 0.94, width: 0.9 },
  speaking: { wobble: 0.03, spin: 0.35, scale: 1, width: 1.3 },
  error: { wobble: 0.008, spin: 0.05, scale: 0.95, width: 0.9 },
}

const RING_POINTS = 120

/**
 * A soft glowing ring. Its outline wobbles like a membrane, stretching with `level`
 * while listening or speaking; the light sweeps around it faster while thinking.
 * Brightest along the bottom edge. Drawn as SVG, so it stays sharp at any size.
 */
function RingOrb({
  state = "idle",
  level = 0,
  size = 160,
  speed = 1,
  glow = 0,
  thickness = 1,
  className,
  ...props
}: OrbProps & { thickness?: number }) {
  const thick = React.useRef(thickness)
  React.useEffect(() => {
    thick.current = thickness
  })
  const id = React.useId().replace(/:/g, "")
  const coreRef = React.useRef<SVGPathElement>(null)
  const glowRef = React.useRef<SVGPathElement>(null)
  const haloRef = React.useRef<SVGPathElement>(null)
  const gradientRef = React.useRef<SVGLinearGradientElement>(null)
  const input = React.useRef({ state, level, speed })
  const redraw = React.useRef<(() => void) | null>(null)

React.useEffect(() => {
    input.current = { state, level, speed }
    redraw.current?.()
  }, [state, level, speed])

React.useEffect(() => {
    const reduced = window.matchMedia("(prefers-reduced-motion: reduce)").matches
    const cur = { ...ringTargets.idle, level: 0, time: 0, angle: 0 }
    let last = performance.now()
    let raf = 0

const draw = (now: number) => {
      const dt = reduced ? 0 : Math.max(0, Math.min(0.05, (now - last) / 1000))
      last = now
      const { state, level, speed } = input.current
      const target = ringTargets[state]
      const k = reduced ? 1 : 1 - Math.exp(-dt * 5)
      cur.wobble += (target.wobble - cur.wobble) * k
      cur.spin += (target.spin - cur.spin) * k
      cur.scale += (target.scale - cur.scale) * k
      cur.width += (target.width - cur.width) * k
      const targetLevel = state === "listening" || state === "speaking" ? level : 0
      cur.level += (targetLevel - cur.level) * (reduced ? 1 : 1 - Math.exp(-dt * 12))
      cur.time += dt * speed
      cur.angle += cur.spin * dt * speed
      const t = cur.time

const amp = cur.wobble + cur.level * 0.045
      const radius = 38 * cur.scale * (1 + cur.level * 0.06 + Math.sin(t * 1.2) * 0.008)
      let d = ""
      for (let i = 0; i <= RING_POINTS; i++) {
        const a = (i / RING_POINTS) * Math.PI * 2
        const r =
          radius *
          (1 +
            amp * Math.sin(a * 2 + t * 0.9) +
            amp * 0.6 * Math.sin(a * 3 - t * 1.3 + 1.7) +
            cur.level * 0.02 * Math.sin(a * 6 + t * 5))
        const x = 50 + Math.cos(a) * r
        const y = 50 + Math.sin(a) * r
        d += `${i === 0 ? "M" : "L"}${x.toFixed(2)} ${y.toFixed(2)}`
      }
      d += "Z"
      coreRef.current?.setAttribute("d", d)
      glowRef.current?.setAttribute("d", d)
      haloRef.current?.setAttribute("d", d)
      coreRef.current?.setAttribute("stroke-width", (1.8 * cur.width * thick.current).toFixed(2))
      glowRef.current?.setAttribute("stroke-width", ((5 * cur.width + cur.level * 3) * thick.current).toFixed(2))
      haloRef.current?.setAttribute("stroke-width", (10 + cur.level * 6).toFixed(2))
      gradientRef.current?.setAttribute(
        "gradientTransform",
        `rotate(${((cur.angle * 180) / Math.PI).toFixed(1)} 0.5 0.5)`,
      )
      if (!reduced) raf = requestAnimationFrame(draw)
    }

redraw.current = reduced ? () => draw(performance.now()) : null
    raf = requestAnimationFrame(draw)
    return () => {
      cancelAnimationFrame(raf)
      redraw.current = null
    }
  }, [])

return orbFrame(
    "ring",
    state,
    size,
    glow,
    className,
    props,
    <svg viewBox="0 0 100 100" className="size-full overflow-visible">
        <defs>
          {/* Dim at the top, full strength at the bottom; rotated to sweep the light around. */}
          <linearGradient ref={gradientRef} id={`${id}-g`} x1="0" y1="0" x2="0" y2="1">
            <stop offset="0" stopColor="currentColor" stopOpacity="0.25" />
            <stop offset="0.6" stopColor="currentColor" stopOpacity="0.7" />
            <stop offset="1" stopColor="currentColor" stopOpacity="1" />
          </linearGradient>
          <filter id={`${id}-blur`} x="-50%" y="-50%" width="200%" height="200%">
            <feGaussianBlur stdDeviation="2.2" />
          </filter>
          <filter id={`${id}-halo`} x="-50%" y="-50%" width="200%" height="200%">
            <feGaussianBlur stdDeviation="6" />
          </filter>
        </defs>
        <path ref={haloRef} fill="none" stroke={`url(#${id}-g)`} filter={`url(#${id}-halo)`} opacity="0.35" />
        <path ref={glowRef} fill="none" stroke={`url(#${id}-g)`} filter={`url(#${id}-blur)`} opacity="0.85" />
        <path ref={coreRef} fill="none" stroke={`url(#${id}-g)`} strokeLinejoin="round" />
    </svg>,
  )
}

/** Per-state targets for the wave. `amp` is ribbon height; `speed` is how fast they travel. */
const waveTargets: Record<VoiceState, { amp: number; speed: number; twist: number }> = {
  idle: { amp: 0.14, speed: 0.6, twist: 0.8 },
  connecting: { amp: 0.08, speed: 2, twist: 1.2 },
  listening: { amp: 0.22, speed: 1.2, twist: 1 },
  thinking: { amp: 0.1, speed: 3.2, twist: 1.6 },
  speaking: { amp: 0.26, speed: 1.8, twist: 1.1 },
  error: { amp: 0.04, speed: 0.3, twist: 0.4 },
}

/** Each ribbon: frequency, phase offset, travel direction, and fill strength. */
const RIBBONS = [
  { k: 2.1, phase: 0, dir: 1, fill: 0.22 },
  { k: 2.6, phase: 1.9, dir: -1, fill: 0.16 },
  { k: 1.7, phase: 3.4, dir: 1, fill: 0.12 },
  { k: 3.1, phase: 4.6, dir: -1, fill: 0.1 },
  { k: 2.3, phase: 5.8, dir: 1, fill: 0.08 },
]
const WAVE_SAMPLES = 90

/**
 * Glowing ribbons that twist around a centre line and taper to a flat line at both
 * ends. They rise with `level` while listening or speaking and race while thinking.
 * Wider than it is tall: 2x `size` wide and 0.6x tall, capped to its container's width.
 */
function WaveOrb({ state = "idle", level = 0, size = 160, speed = 1, glow = 0, className, ...props }: OrbProps) {
  const id = React.useId().replace(/:/g, "")
  const fillRefs = React.useRef<(SVGPathElement | null)[]>([])
  const edgeRefs = React.useRef<(SVGPathElement | null)[]>([])
  const input = React.useRef({ state, level, speed })
  const redraw = React.useRef<(() => void) | null>(null)

React.useEffect(() => {
    input.current = { state, level, speed }
    redraw.current?.()
  }, [state, level, speed])

React.useEffect(() => {
    const reduced = window.matchMedia("(prefers-reduced-motion: reduce)").matches
    const cur = { ...waveTargets.idle, level: 0, time: 0 }
    let last = performance.now()
    let raf = 0
    const W = 200
    const C = 50

const draw = (now: number) => {
      const dt = reduced ? 0 : Math.max(0, Math.min(0.05, (now - last) / 1000))
      last = now
      const { state, level, speed } = input.current
      const target = waveTargets[state]
      const k = reduced ? 1 : 1 - Math.exp(-dt * 4)
      cur.amp += (target.amp - cur.amp) * k
      cur.speed += (target.speed - cur.speed) * k
      cur.twist += (target.twist - cur.twist) * k
      const targetLevel = state === "listening" || state === "speaking" ? level : 0
      cur.level += (targetLevel - cur.level) * (reduced ? 1 : 1 - Math.exp(-dt * 10))
      cur.time += cur.speed * dt * speed
      const t = cur.time
      const height = Math.min(44, (cur.amp + cur.level * 0.3) * 100)

RIBBONS.forEach((r, i) => {
        let top = ""
        let bottom = ""
        let edge = ""
        for (let j = 0; j <= WAVE_SAMPLES; j++) {
          const u = j / WAVE_SAMPLES
          const x = u * W
          // Gaussian envelope pins both ends to the centre line.
          const env = Math.exp(-(((u - 0.5) / 0.24) ** 2))
          const a = u * Math.PI * 2 * r.k + r.phase + t * r.dir
          const y1 = C + Math.sin(a) * height * env
          const y2 = C + Math.sin(a + cur.twist) * height * env * 0.8
          top += `${j === 0 ? "M" : "L"}${x.toFixed(1)} ${y1.toFixed(2)}`
          bottom = `L${x.toFixed(1)} ${y2.toFixed(2)}` + bottom
          edge += `${j === 0 ? "M" : "L"}${x.toFixed(1)} ${y1.toFixed(2)}`
        }
        fillRefs.current[i]?.setAttribute("d", top + bottom + "Z")
        edgeRefs.current[i]?.setAttribute("d", edge)
      })
      if (!reduced) raf = requestAnimationFrame(draw)
    }

redraw.current = reduced ? () => draw(performance.now()) : null
    raf = requestAnimationFrame(draw)
    return () => {
      cancelAnimationFrame(raf)
      redraw.current = null
    }
  }, [])

return orbFrame(
    "wave",
    state,
    size,
    glow,
    cn("h-[calc(var(--orb-size)*0.6)] w-[calc(var(--orb-size)*2)] max-w-full", className),
    props,
    <svg viewBox="0 0 200 100" preserveAspectRatio="none" className="size-full overflow-visible">
        <defs>
          {/* Fade the ends into the flat centre line. */}
          <linearGradient id={`${id}-fade`} x1="0" y1="0" x2="1" y2="0">
            <stop offset="0" stopColor="currentColor" stopOpacity="0" />
            <stop offset="0.25" stopColor="currentColor" stopOpacity="1" />
            <stop offset="0.75" stopColor="currentColor" stopOpacity="1" />
            <stop offset="1" stopColor="currentColor" stopOpacity="0" />
          </linearGradient>
          <filter id={`${id}-glow`} x="-20%" y="-50%" width="140%" height="200%">
            <feGaussianBlur stdDeviation="1.6" result="b" />
            <feMerge>
              <feMergeNode in="b" />
              <feMergeNode in="SourceGraphic" />
            </feMerge>
          </filter>
        </defs>
        <g filter={`url(#${id}-glow)`}>
          <line x1="0" y1="50" x2="200" y2="50" stroke={`url(#${id}-fade)`} strokeWidth="0.8" opacity="0.8" />
          {RIBBONS.map((r, i) => (
            <g key={i}>
              <path
                ref={(el) => {
                  fillRefs.current[i] = el
                }}
                fill={`url(#${id}-fade)`}
                fillOpacity={r.fill}
              />
              <path
                ref={(el) => {
                  edgeRefs.current[i] = el
                }}
                fill="none"
                stroke={`url(#${id}-fade)`}
                strokeWidth={i === 0 ? 0.9 : 0.5}
                strokeOpacity={i === 0 ? 0.95 : 0.6}
                vectorEffect="non-scaling-stroke"
              />
            </g>
          ))}
        </g>
    </svg>,
  )
}

/**
 * Shared animation loop for orbs: eases numeric targets per state (k per second),
 * smooths `level`, advances time, and calls `draw` each frame. With reduced motion
 * it jumps to targets and draws once per change.
 */
function useOrbLoop<T extends Record<string, number>>(
  state: VoiceState,
  level: number,
  speed: number,
  targets: Record<VoiceState, T>,
  draw: (cur: T & { level: number; time: number; dt: number }, reduced: boolean) => void,
) {
  const input = React.useRef({ state, level, speed })
  const drawRef = React.useRef(draw)
  const redraw = React.useRef<(() => void) | null>(null)

React.useEffect(() => {
    drawRef.current = draw
  })

React.useEffect(() => {
    input.current = { state, level, speed }
    redraw.current?.()
  }, [state, level, speed])

React.useEffect(() => {
    const reduced = window.matchMedia("(prefers-reduced-motion: reduce)").matches
    const cur = { ...targets.idle, level: 0, time: 0, dt: 0 } as T & { level: number; time: number; dt: number }
    let last = performance.now()
    let raf = 0
    const frame = (now: number) => {
      const dt = reduced ? 0 : Math.max(0, Math.min(0.05, (now - last) / 1000))
      last = now
      const { state, level, speed } = input.current
      const target = targets[state]
      const k = reduced ? 1 : 1 - Math.exp(-dt * 5)
      for (const key of Object.keys(target) as (keyof T)[]) {
        ;(cur[key] as number) += ((target[key] as number) - (cur[key] as number)) * k
      }
      const targetLevel = state === "listening" || state === "speaking" ? level : 0
      cur.level += (targetLevel - cur.level) * (reduced ? 1 : 1 - Math.exp(-dt * 12))
      // Time runs at `speed`; easing between states keeps its own pace.
      cur.dt = dt * speed
      cur.time += cur.dt
      drawRef.current(cur, reduced)
      if (!reduced) raf = requestAnimationFrame(frame)
    }
    redraw.current = reduced ? () => frame(performance.now()) : null
    raf = requestAnimationFrame(frame)
    return () => {
      cancelAnimationFrame(raf)
      redraw.current = null
    }
  }, [targets])
}

/**
 * Shared wrapper: sizing, state attributes, glow, and the cross-variant state cues
 * (connecting breathes, error turns destructive).
 */
function orbFrame(
  variant: string,
  state: VoiceState,
  size: number,
  glow: number,
  className: string | undefined,
  { style, ...props }: React.ComponentProps<"div">,
  children: React.ReactNode,
  /** Glow color when it shouldn't follow the text color, e.g. a named aura palette. */
  glowColor = "currentColor",
) {
  return (
    <div
      data-slot="voice-orb"
      data-variant={variant}
      data-state={state}
      role="img"
      aria-label={`Voice assistant ${state}`}
      className={cn(
        "relative size-(--orb-size) text-primary data-[state=connecting]:animate-pulse data-[state=error]:text-destructive motion-reduce:animate-none",
        glow > 0 && "drop-shadow-(--orb-glow)",
        className,
      )}
      style={
        {
          "--orb-size": `${size}px`,
          "--orb-glow": `0 0 ${Math.round(size * 0.12 * glow)}px ${glowColor}`,
          ...style,
        } as React.CSSProperties
      }
      {...props}
    >
      {children}
    </div>
  )
}

/* ---------- Aura: grainy colored sphere ---------- */

/** Named aura palettes: base, then three drifting color fields. */
const auraPalettes = {
  iris: ["#6d5bd0", "#f48fe8", "#7aa2ff", "#b27bff"],
  ember: ["#e8552a", "#ffb86b", "#f47a3d", "#c93d1c"],
  cocoa: ["#4a3530", "#8a5a4c", "#c98a7a", "#2c2220"],
  mist: ["#d9ded6", "#f4efe2", "#b9cfc4", "#eef3ea"],
} as const

type OrbPalette = keyof typeof auraPalettes | "primary"

const auraTargets: Record<VoiceState, { speed: number; spread: number; swirl: number; swell: number }> = {
  idle: { speed: 0.25, spread: 0.5, swirl: 0, swell: 0 },
  connecting: { speed: 0.5, spread: 0.4, swirl: 0.5, swell: 0 },
  listening: { speed: 0.6, spread: 0.58, swirl: 0, swell: 1 },
  thinking: { speed: 0.9, spread: 0.46, swirl: 1, swell: 0 },
  speaking: { speed: 0.8, spread: 0.55, swirl: 0.2, swell: 0.8 },
  error: { speed: 0.1, spread: 0.45, swirl: 0, swell: 0 },
}

const AURA_FIELDS = [
  { w: 0.7, phase: 0, r: 1.15 },
  { w: -0.9, phase: 2.1, r: 1.05 },
  { w: 1.2, phase: 4.2, r: 0.9 },
]

/** Film grain, generated once per size: gray noise with transparent gaps, blended over the sphere. */
function makeGrain(px: number) {
  const grain = document.createElement("canvas")
  grain.width = px
  grain.height = px
  const g = grain.getContext("2d")!
  const img = g.createImageData(px, px)
  for (let i = 0; i < img.data.length; i += 4) {
    const v = Math.random() * 255
    img.data[i] = img.data[i + 1] = img.data[i + 2] = v
    img.data[i + 3] = 255
  }
  g.putImageData(img, 0, 0)
  return grain
}

/**
 * Resolves CSS colors (including color-mix and oklch) to [r, g, b] by painting each
 * into a 1×1 canvas. Gradients need explicit channels: fading to "transparent" means
 * transparent black, which drags every field through gray at its edges.
 */
function resolveColors(el: HTMLElement, colors: string[]): [number, number, number][] {
  const probe = document.createElement("span")
  probe.style.display = "none"
  el.appendChild(probe)
  const pixel = document.createElement("canvas").getContext("2d", { willReadFrequently: true })!
  const out = colors.map((c) => {
    probe.style.color = ""
    probe.style.color = c
    pixel.clearRect(0, 0, 1, 1)
    pixel.fillStyle = getComputedStyle(probe).color
    pixel.fillRect(0, 0, 1, 1)
    const [r, g, b] = pixel.getImageData(0, 0, 1, 1).data
    return [r, g, b] as [number, number, number]
  })
  probe.remove()
  return out
}

const rgba = ([r, g, b]: [number, number, number], a = 1) => `rgba(${r},${g},${b},${a})`

type Palette = OrbPalette | string[]

/**
 * Resolves a palette to four RGB colors (base + three fields), again on theme changes.
 * "primary" builds shades from the text color. Error swaps any palette for shades of the
 * destructive color, so the state reads the same on every orb.
 */
function usePaletteColors(ref: React.RefObject<HTMLElement | null>, palette: Palette, error: boolean) {
  const colorsRef = React.useRef<[number, number, number][]>([])
  // Re-resolve when the palette's value changes, not its array identity.
  const key = Array.isArray(palette) ? palette.join(",") : palette
  const paletteRef = React.useRef(palette)
  React.useEffect(() => {
    paletteRef.current = palette
  })

React.useEffect(() => {
    const el = ref.current
    if (!el) return
    const read = () => {
      const palette = paletteRef.current
      const list =
        palette === "primary" || error
          ? [
              "color-mix(in oklch, currentColor 90%, black)",
              "color-mix(in oklch, currentColor 55%, white)",
              "currentColor",
              "color-mix(in oklch, currentColor 80%, white)",
            ]
          : Array.isArray(palette)
            ? palette
            : [...auraPalettes[palette]]
      colorsRef.current = resolveColors(el, list)
    }
    read()
    const observer = new MutationObserver(read)
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-color", "data-base"],
    })
    return () => observer.disconnect()
  }, [ref, key, error])

return colorsRef
}

/** Named and custom palettes glow in their main field color; primary and error follow the text color. */
function paletteGlow(palette: Palette, error: boolean) {
  if (error || palette === "primary") return undefined
  return Array.isArray(palette) ? palette[2] : auraPalettes[palette][2]
}

/**
 * A grainy sphere of drifting color fields with a soft highlight and darker rim.
 * Fields drift slowly when idle, move and swell with `level` while listening or
 * speaking, and swirl while thinking. `palette` picks the colors.
 */
function AuraOrb({
  state = "idle",
  level = 0,
  size = 160,
  speed = 1,
  glow = 0,
  palette = "primary",
  grain = 1,
  className,
  ...props
}: OrbProps & { palette?: Palette; grain?: number }) {
  const canvasRef = React.useRef<HTMLCanvasElement>(null)
  const grainRef = React.useRef<HTMLCanvasElement | null>(null)
  const colorsRef = usePaletteColors(canvasRef, palette, state === "error")

useOrbLoop(state, level, speed, auraTargets, (c) => {
    const canvas = canvasRef.current
    const ctx = canvas?.getContext("2d")
    const colors = colorsRef.current
    if (!canvas || !ctx || colors.length < 4) return
    const dpr = Math.min(window.devicePixelRatio || 1, 2)
    const px = Math.round(size * dpr)
    // Compare both sides: a fresh canvas is 300×150, so width alone can match by accident.
    if (canvas.width !== px || canvas.height !== px) {
      canvas.width = px
      canvas.height = px
      grainRef.current = makeGrain(px)
    }
    const r = px / 2
    const t = c.time * c.speed
    const swell = 1 + c.swell * c.level * 0.06

ctx.clearRect(0, 0, px, px)
    ctx.save()
    ctx.translate(r, r)
    ctx.scale(swell, swell)
    ctx.translate(-r, -r)
    ctx.beginPath()
    ctx.arc(r, r, r * 0.96, 0, Math.PI * 2)
    ctx.clip()

// Base, then three soft color fields orbiting inside.
    ctx.fillStyle = rgba(colors[0])
    ctx.fillRect(0, 0, px, px)
    AURA_FIELDS.forEach((f, i) => {
      const a = t * f.w + f.phase + c.swirl * c.time * 1.5
      const orbit = r * c.spread * (1 + c.level * c.swell * 0.5)
      const x = r + Math.cos(a) * orbit
      const y = r + Math.sin(a * 0.8) * orbit
      const rad = r * f.r * (1 + c.level * c.swell * 0.25)
      const g = ctx.createRadialGradient(x, y, 0, x, y, rad)
      // Solid core, long soft falloff: fields read as distinct color areas, not spots.
      g.addColorStop(0, rgba(colors[i + 1]))
      g.addColorStop(0.45, rgba(colors[i + 1]))
      g.addColorStop(1, rgba(colors[i + 1], 0))
      ctx.fillStyle = g
      ctx.fillRect(0, 0, px, px)
    })

// Sphere shading: soft highlight upper left, darker rim.
    const hl = ctx.createRadialGradient(r * 0.65, r * 0.55, 0, r * 0.65, r * 0.55, r * 1.1)
    hl.addColorStop(0, "rgba(255,255,255,0.28)")
    hl.addColorStop(1, "rgba(255,255,255,0)")
    ctx.fillStyle = hl
    ctx.fillRect(0, 0, px, px)
    // A light touch: the rim only deepens the last third, so edges stay blended.
    const rim = ctx.createRadialGradient(r, r, r * 0.7, r, r, r)
    rim.addColorStop(0, "rgba(0,0,0,0)")
    rim.addColorStop(1, "rgba(0,0,0,0.12)")
    ctx.fillStyle = rim
    ctx.fillRect(0, 0, px, px)

// Grain.
    if (grainRef.current && grain > 0) {
      ctx.globalCompositeOperation = "overlay"
      ctx.globalAlpha = 0.22 * grain
      ctx.drawImage(grainRef.current, 0, 0)
      ctx.globalAlpha = 1
      ctx.globalCompositeOperation = "source-over"
    }
    ctx.restore()
  })

return orbFrame(
    "aura",
    state,
    size,
    glow,
    className,
    props,
    <canvas ref={canvasRef} className="size-full" />,
    paletteGlow(palette, state === "error"),
  )
}

/* ---------- Bars: circular equalizer ---------- */

const barsTargets: Record<VoiceState, { base: number; speed: number; sweep: number; spin: number }> = {
  idle: { base: 0.08, speed: 1, sweep: 0, spin: 0.1 },
  connecting: { base: 0.06, speed: 0.8, sweep: 0.6, spin: 0.6 },
  listening: { base: 0.1, speed: 2.4, sweep: 0, spin: 0.15 },
  thinking: { base: 0.12, speed: 1.5, sweep: 1, spin: 1.4 },
  speaking: { base: 0.12, speed: 3, sweep: 0, spin: 0.2 },
  error: { base: 0.05, speed: 0.3, sweep: 0, spin: 0.02 },
}

/**
 * Bars around a ring, like a circular equalizer. Bar length follows `level` while
 * listening or speaking; a bright arc sweeps around it while thinking.
 */
function BarsOrb({
  state = "idle",
  level = 0,
  size = 160,
  speed = 1,
  glow = 0,
  bars: count = 56,
  className,
  ...props
}: OrbProps & { bars?: number }) {
  const bars = React.useRef<(SVGLineElement | null)[]>([])
  const angle = React.useRef(0)

useOrbLoop(state, level, speed, barsTargets, (c) => {
    angle.current += c.spin * c.dt
    const t = c.time * c.speed
    for (let i = 0; i < count; i++) {
      const el = bars.current[i]
      if (!el) continue
      const a = (i / count) * Math.PI * 2 + angle.current
      const noise = 0.5 + 0.5 * Math.sin(i * 1.7 + t) * Math.sin(i * 0.6 - t * 1.3)
      const len = 30 * (c.base + (0.15 + c.level * 0.85) * noise * (0.3 + c.level))
      const r0 = 26
      el.setAttribute("x1", (50 + Math.cos(a) * r0).toFixed(2))
      el.setAttribute("y1", (50 + Math.sin(a) * r0).toFixed(2))
      el.setAttribute("x2", (50 + Math.cos(a) * (r0 + 1.5 + len)).toFixed(2))
      el.setAttribute("y2", (50 + Math.sin(a) * (r0 + 1.5 + len)).toFixed(2))
      // While thinking, a highlight travels around the ring.
      const head = ((c.time * 0.9) % 1) * count
      const dist = Math.min(Math.abs(i - head), count - Math.abs(i - head))
      const lit = c.sweep * Math.max(0, 1 - dist / 10)
      el.setAttribute("opacity", Math.min(1, 0.35 + noise * 0.35 + c.level * 0.3 + lit).toFixed(2))
    }
  })

return orbFrame(
    "bars",
    state,
    size,
    glow,
    className,
    props,
    <svg viewBox="0 0 100 100" className="size-full overflow-visible">
      {Array.from({ length: count }, (_, i) => (
        <line
          key={i}
          ref={(el) => {
            bars.current[i] = el
          }}
          stroke="currentColor"
          strokeWidth="1.6"
          strokeLinecap="round"
        />
      ))}
    </svg>,
  )
}

/* ---------- Halftone: dot matrix disc ---------- */

const halftoneTargets: Record<VoiceState, { speed: number; freq: number; swirl: number; amp: number }> = {
  idle: { speed: 0.8, freq: 0.35, swirl: 0, amp: 0.35 },
  connecting: { speed: 1, freq: 0.3, swirl: 0.5, amp: 0.25 },
  listening: { speed: 2.2, freq: 0.45, swirl: 0, amp: 0.55 },
  thinking: { speed: 1.4, freq: 0.3, swirl: 1, amp: 0.5 },
  speaking: { speed: 2.8, freq: 0.5, swirl: 0, amp: 0.6 },
  error: { speed: 0.2, freq: 0.3, swirl: 0, amp: 0.2 },
}

/**
 * A disc of dots whose sizes ripple outward like a printed halftone wave. The
 * ripple speeds up with `level`; while thinking the pattern twists into a spiral.
 */
function HalftoneOrb({
  state = "idle",
  level = 0,
  size = 160,
  speed = 1,
  glow = 0,
  density = 1,
  className,
  ...props
}: OrbProps & { density?: number }) {
  const canvasRef = React.useRef<HTMLCanvasElement>(null)
  const grid = Math.max(6, Math.round(Math.max(14, Math.min(28, size / 7)) * density))

useOrbLoop(state, level, speed, halftoneTargets, (c) => {
    const canvas = canvasRef.current
    const ctx = canvas?.getContext("2d")
    if (!canvas || !ctx) return
    const dpr = Math.min(window.devicePixelRatio || 1, 2)
    const px = size * dpr
    // Compare both sides: a fresh canvas is 300×150, so width alone can match by accident.
    if (canvas.width !== px || canvas.height !== px) {
      canvas.width = px
      canvas.height = px
    }
    ctx.clearRect(0, 0, px, px)
    ctx.fillStyle = getComputedStyle(canvas).color
    const cell = px / grid
    const center = (grid - 1) / 2
    const radius = grid / 2 - 0.5
    const t = c.time * c.speed
    for (let y = 0; y < grid; y++) {
      for (let x = 0; x < grid; x++) {
        const dx = x - center
        const dy = y - center
        const d = Math.hypot(dx, dy)
        if (d > radius) continue
        const a = Math.atan2(dy, dx)
        const wave = 0.5 + 0.5 * Math.sin(d * c.freq * 3 - t * 2 + c.swirl * a * 2)
        const edge = 1 - Math.pow(d / radius, 3)
        const r = (cell / 2) * (0.12 + (c.amp + c.level * 0.5) * wave * edge)
        ctx.globalAlpha = 0.35 + 0.65 * edge
        ctx.beginPath()
        ctx.arc((x + 0.5) * cell, (y + 0.5) * cell, Math.max(0.4, Math.min(cell / 2, r)), 0, Math.PI * 2)
        ctx.fill()
      }
    }
    ctx.globalAlpha = 1
  })

return orbFrame("halftone", state, size, glow, className, props, <canvas ref={canvasRef} className="size-full" />)
}

/* ---------- Dot: minimal presence for tight spots ---------- */

const dotTargets: Record<VoiceState, { breathe: number; react: number; arc: number; spin: number }> = {
  idle: { breathe: 1, react: 0, arc: 0, spin: 0.5 },
  connecting: { breathe: 0, react: 0, arc: 0.6, spin: 2 },
  listening: { breathe: 0.3, react: 1, arc: 0, spin: 0.5 },
  thinking: { breathe: 0, react: 0, arc: 1, spin: 4 },
  speaking: { breathe: 0.3, react: 1.2, arc: 0, spin: 0.5 },
  error: { breathe: 0, react: 0, arc: 0, spin: 0 },
}

/** Circumference of the arc track (r = 42 in a 100 box). */
const DOT_TRACK = 2 * Math.PI * 42

/**
 * A single dot for composer buttons, headers and call pills, legible down to 16px.
 * Breathes when idle, swells with a halo on `level` while listening or speaking, and
 * an arc circles it while connecting or thinking.
 */
function DotOrb({ state = "idle", level = 0, size = 160, speed = 1, glow = 0, className, ...props }: OrbProps) {
  const core = React.useRef<SVGCircleElement>(null)
  const halo = React.useRef<SVGCircleElement>(null)
  const arc = React.useRef<SVGCircleElement>(null)
  const angle = React.useRef(0)

useOrbLoop(state, level, speed, dotTargets, (c) => {
    angle.current += c.spin * c.dt
    const swell = c.react * c.level
    core.current?.setAttribute("r", (24 * (1 + c.breathe * 0.05 * Math.sin(c.time * 2) + swell * 0.3)).toFixed(2))
    halo.current?.setAttribute("r", (30 + swell * 14).toFixed(2))
    halo.current?.setAttribute("opacity", Math.min(0.45, swell * 0.6).toFixed(2))
    arc.current?.setAttribute("opacity", c.arc.toFixed(2))
    arc.current?.setAttribute("transform", `rotate(${((angle.current * 180) / Math.PI).toFixed(1)} 50 50)`)
  })

return orbFrame(
    "dot",
    state,
    size,
    glow,
    className,
    props,
    <svg viewBox="0 0 100 100" className="size-full overflow-visible">
      <circle ref={halo} cx="50" cy="50" r="30" fill="currentColor" opacity="0" />
      <circle
        ref={arc}
        cx="50"
        cy="50"
        r="42"
        fill="none"
        stroke="currentColor"
        strokeWidth="7"
        strokeLinecap="round"
        strokeDasharray={`${DOT_TRACK * 0.28} ${DOT_TRACK}`}
        opacity="0"
      />
      <circle ref={core} cx="50" cy="50" r="24" fill="currentColor" />
    </svg>,
  )
}

/* ---------- Shader orbs: plasma, liquid and glass ---------- */

const VERTEX = "attribute vec2 p;void main(){gl_Position=vec4(p,0.,1.);}"

/** Shared GLSL: canvas size, palette, level, and value noise with fbm. */
const GLSL_COMMON = `precision mediump float;
uniform vec2 u_res;
uniform float u_level;
uniform vec3 u_c0;
uniform vec3 u_c1;
uniform vec3 u_c2;
uniform vec3 u_c3;
float hash(vec2 p){return fract(sin(dot(p,vec2(127.1,311.7)))*43758.5453);}
float noise(vec2 p){
  vec2 i=floor(p);vec2 f=fract(p);vec2 u=f*f*(3.-2.*f);
  return mix(mix(hash(i),hash(i+vec2(1.,0.)),u.x),mix(hash(i+vec2(0.,1.)),hash(i+vec2(1.,1.)),u.x),u.y);
}
float fbm(vec2 p){float v=0.;float a=.5;for(int i=0;i<5;i++){v+=a*noise(p);p=p*2.02+vec2(1.7,9.2);a*=.5;}return v;}
`

type Shader = { gl: WebGLRenderingContext; uniform: (name: string) => WebGLUniformLocation | null }

let webgl: boolean | undefined
/** Whether this browser can draw shader orbs. Checked once; shader variants fall back to aura without it. */
function hasWebGL() {
  if (webgl === undefined) {
    try {
      webgl = !!document.createElement("canvas").getContext("webgl")
    } catch {
      webgl = false
    }
  }
  return webgl
}
const noSubscribe = () => () => {}

/** Compiles a fragment shader onto a quad covering the canvas. The ref stays null if it fails. */
function useShader(ref: React.RefObject<HTMLCanvasElement | null>, fragment: string) {
  const shader = React.useRef<Shader | null>(null)
  React.useEffect(() => {
    const gl = ref.current?.getContext("webgl", { premultipliedAlpha: true, antialias: false })
    if (!gl) return
    const compile = (type: number, source: string) => {
      const s = gl.createShader(type)!
      gl.shaderSource(s, source)
      gl.compileShader(s)
      return s
    }
    const program = gl.createProgram()!
    const vs = compile(gl.VERTEX_SHADER, VERTEX)
    const fs = compile(gl.FRAGMENT_SHADER, GLSL_COMMON + fragment)
    gl.attachShader(program, vs)
    gl.attachShader(program, fs)
    gl.linkProgram(program)
    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
      console.error(gl.getShaderInfoLog(fs) ?? gl.getProgramInfoLog(program))
      return
    }
    gl.useProgram(program)
    const buffer = gl.createBuffer()
    gl.bindBuffer(gl.ARRAY_BUFFER, buffer)
    gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 1, -1, -1, 1, 1, 1]), gl.STATIC_DRAW)
    const position = gl.getAttribLocation(program, "p")
    gl.enableVertexAttribArray(position)
    gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 0, 0)
    const locations = new Map<string, WebGLUniformLocation | null>()
    shader.current = {
      gl,
      uniform: (name) => {
        if (!locations.has(name)) locations.set(name, gl.getUniformLocation(program, name))
        return locations.get(name)!
      },
    }
    return () => {
      shader.current = null
      gl.deleteBuffer(buffer)
      gl.deleteProgram(program)
      gl.deleteShader(vs)
      gl.deleteShader(fs)
    }
  }, [ref, fragment])
  return shader
}

/** Sizes the canvas, sets shared and per-orb uniforms (as u_<name>), and draws one frame. */
function drawShader(
  shader: Shader,
  canvas: HTMLCanvasElement,
  size: number,
  colors: [number, number, number][],
  level: number,
  uniforms: Record<string, number>,
) {
  const { gl, uniform } = shader
  const px = Math.round(size * Math.min(window.devicePixelRatio || 1, 2))
  if (canvas.width !== px || canvas.height !== px) {
    canvas.width = px
    canvas.height = px
  }
  gl.viewport(0, 0, px, px)
  gl.uniform2f(uniform("u_res"), px, px)
  gl.uniform1f(uniform("u_level"), level)
  colors.forEach(([r, g, b], i) => gl.uniform3f(uniform(`u_c${i}`), r / 255, g / 255, b / 255))
  for (const [name, value] of Object.entries(uniforms)) gl.uniform1f(uniform(`u_${name}`), value)
  gl.clearColor(0, 0, 0, 0)
  gl.clear(gl.COLOR_BUFFER_BIT)
  gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4)
}

type ShaderOrbProps = OrbProps & { palette?: Palette }

/**
 * Wires a shader orb: palette colors, the compiled program, and a loop that advances
 * `phase` at the state's `pace` so speed changes never jump the pattern.
 */
function useShaderOrb<T extends { pace: number } & Record<string, number>>(
  { state = "idle", level = 0, size = 160, speed = 1, palette = "primary" }: ShaderOrbProps,
  fragment: string,
  targets: Record<VoiceState, T>,
  /** Fixed shape and material settings, sent as u_<name> alongside the eased state values. */
  material: Record<string, number>,
) {
  const canvasRef = React.useRef<HTMLCanvasElement>(null)
  const colorsRef = usePaletteColors(canvasRef, palette, state === "error")
  const shader = useShader(canvasRef, fragment)
  const phase = React.useRef(0)
  useOrbLoop(state, level, speed, targets, (c) => {
    const canvas = canvasRef.current
    if (!shader.current || !canvas || colorsRef.current.length < 4) return
    phase.current += c.dt * c.pace
    const uniforms: Record<string, number> = { ...material, phase: phase.current }
    for (const key of Object.keys(targets.idle)) if (key !== "pace") uniforms[key] = c[key]
    drawShader(shader.current, canvas, size, colorsRef.current, c.level, uniforms)
  })
  return canvasRef
}

const plasmaTargets: Record<VoiceState, { pace: number; turb: number; swirl: number; bright: number }> = {
  idle: { pace: 0.6, turb: 0.4, swirl: 0, bright: 0.6 },
  connecting: { pace: 1.2, turb: 0.3, swirl: 0.6, bright: 0.4 },
  listening: { pace: 1, turb: 0.8, swirl: 0, bright: 1 },
  thinking: { pace: 2, turb: 1, swirl: 1, bright: 0.9 },
  speaking: { pace: 1.4, turb: 1, swirl: 0.2, bright: 1.2 },
  error: { pace: 0.2, turb: 0.2, swirl: 0, bright: 0.3 },
}

/** Domain-warped noise inside a shaded sphere, with bright filaments that flare with level. */
const PLASMA = `uniform float u_phase;
uniform float u_turb;
uniform float u_swirl;
uniform float u_bright;
uniform float u_turbulence;
uniform float u_filaments;
void main(){
  vec2 uv=(gl_FragCoord.xy*2.-u_res)/u_res.y;
  float R=.9*(1.+u_level*.05);
  float r=length(uv)/R;
  float aa=3./u_res.y;
  float mask=1.-smoothstep(1.-aa,1.+aa,r);
  if(mask<=0.){gl_FragColor=vec4(0.);return;}
  float z=sqrt(max(0.,1.-r*r));
  vec2 p=uv/R/(z*.6+.4);
  float t=u_phase;
  float a=u_swirl*((1.-r)*2.5+t*.2);
  float ca=cos(a);float sa=sin(a);
  p=mat2(ca,-sa,sa,ca)*p;
  vec2 q=vec2(fbm(p*1.4+vec2(t*.15,0.)),fbm(p*1.4+vec2(3.1,-t*.12)));
  float n=fbm(p*1.8+q*(1.2+u_turb*1.6+u_level*1.5)*u_turbulence+vec2(0.,t*.1));
  vec3 col=mix(u_c0,u_c1,smoothstep(.25,.65,n));
  col=mix(col,u_c2,smoothstep(.4,.75,q.x)*.8);
  col=mix(col,u_c3,smoothstep(.5,.85,q.y)*.6);
  float fil=pow(1.-abs(sin(n*10.+t*.5)),10.)*(.35+u_level*.8)*u_bright*u_filaments;
  col+=fil*mix(u_c1,vec3(1.),.5);
  col*=.7+.4*z;
  col+=pow(1.-z,2.5)*.4*u_c3;
  gl_FragColor=vec4(col*mask,mask);
}`

/**
 * Glowing plasma: warped noise flowing inside a shaded sphere. Bright filaments flare
 * with `level`; it churns faster and twists while thinking. `palette` picks the colors.
 */
function PlasmaOrb({
  glow = 0,
  turbulence = 1,
  filaments = 1,
  className,
  ...props
}: ShaderOrbProps & { turbulence?: number; filaments?: number }) {
  const { state = "idle", level, size = 160, speed, palette = "primary", ...rest } = props
  const canvasRef = useShaderOrb({ state, level, size, speed, palette }, PLASMA, plasmaTargets, {
    turbulence,
    filaments,
  })
  return orbFrame(
    "plasma",
    state,
    size,
    glow,
    className,
    rest,
    <canvas ref={canvasRef} className="size-full" />,
    paletteGlow(palette, state === "error"),
  )
}

const liquidTargets: Record<VoiceState, { pace: number; spread: number; shine: number }> = {
  idle: { pace: 0.5, spread: 0.8, shine: 0.8 },
  connecting: { pace: 1.3, spread: 0.45, shine: 0.6 },
  listening: { pace: 0.9, spread: 1, shine: 0.9 },
  thinking: { pace: 1.8, spread: 0.7, shine: 0.9 },
  speaking: { pace: 1.2, spread: 1.1, shine: 1 },
  error: { pace: 0.2, spread: 0.55, shine: 0.4 },
}

/** Up to eight metaballs, lit as a glossy surface from the field's gradient. */
const LIQUID = `uniform float u_phase;
uniform float u_spread;
uniform float u_shine;
uniform float u_blobs;
uniform float u_gloss;
// Surface height: 0 at the edge, easing smoothly to flat inside, so rims curve and centres stay calm.
float height(float f){return sqrt(1.-exp(-max(f-1.,0.)*1.5));}
float field(vec2 uv,out vec3 tint){
  float f=0.;vec3 acc=vec3(0.);
  // More blobs are each smaller, so the total mass stays about the same.
  float scale=sqrt(5./u_blobs);
  for(int i=0;i<8;i++){
    float fi=float(i);
    if(fi>=u_blobs)break;
    float k=mod(fi,5.);
    vec2 c=vec2(sin(u_phase*(.7+fi*.17)+fi*1.7),cos(u_phase*(.6+fi*.13)+fi*2.3))*u_spread*(.26+.045*k)*(1.+u_level*.25);
    float rad=(.36-.03*k)*scale*(1.+u_level*.3+.06*sin(u_phase*1.9+fi));
    // Keep each blob, and its soft edge, inside the canvas.
    c*=min(1.,(.9-rad*1.15)/max(length(c),.0001));
    vec2 d=uv-c;
    // Softened so ball centres stay finite; a raw 1/d² spike speckles the lighting.
    float v=rad*rad/(dot(d,d)+rad*rad*.15);
    float m=mod(fi,3.);
    vec3 col=m<.5?u_c1:m<1.5?u_c2:u_c3;
    f+=v;acc+=col*v;
  }
  tint=acc/max(f,.0001);
  return f;
}
void main(){
  vec2 uv=(gl_FragCoord.xy*2.-u_res)/u_res.y;
  float e=2./u_res.y;
  vec3 tint;vec3 unused;
  float f=field(uv,tint);
  float fx=field(uv+vec2(e,0.),unused);
  float fy=field(uv+vec2(0.,e),unused);
  float g=length(vec2(fx-f,fy-f));
  float m=clamp((f-1.)/max(g*1.5,.0001)+.5,0.,1.);
  if(m<=0.){gl_FragColor=vec4(0.);return;}
  float h=height(f);
  vec2 dh=vec2(height(fx)-h,height(fy)-h)/e;
  vec3 n=normalize(vec3(-dh*.18,1.));
  vec3 L=normalize(vec3(-.5,.6,.8));
  float diff=clamp(dot(n,L),0.,1.);
  float spec=pow(clamp(dot(n,normalize(L+vec3(0.,0.,1.))),0.,1.),40.)*u_shine*u_gloss;
  vec3 col=tint*(.55+.55*diff);
  col=mix(col,u_c0,.2*(1.-diff));
  col+=spec*.9;
  gl_FragColor=vec4(col*m,m);
}`

/**
 * Liquid metal: colored blobs that drift, merge and split, lit like a glossy surface.
 * They spread and swell with `level`, pull together while connecting, and churn while
 * thinking. `palette` picks the colors.
 */
function LiquidOrb({
  glow = 0,
  blobs = 5,
  gloss = 1,
  className,
  ...props
}: ShaderOrbProps & { blobs?: number; gloss?: number }) {
  const { state = "idle", level, size = 160, speed, palette = "primary", ...rest } = props
  const canvasRef = useShaderOrb({ state, level, size, speed, palette }, LIQUID, liquidTargets, {
    blobs: Math.max(1, Math.min(8, Math.round(blobs))),
    gloss,
  })
  return orbFrame(
    "liquid",
    state,
    size,
    glow,
    className,
    rest,
    <canvas ref={canvasRef} className="size-full" />,
    paletteGlow(palette, state === "error"),
  )
}

const glassTargets: Record<VoiceState, { pace: number; core: number; swirl: number }> = {
  idle: { pace: 0.4, core: 0.9, swirl: 0 },
  connecting: { pace: 1, core: 0.6, swirl: 0.5 },
  listening: { pace: 0.8, core: 1.1, swirl: 0 },
  thinking: { pace: 1.5, core: 0.9, swirl: 1 },
  speaking: { pace: 1.1, core: 1.2, swirl: 0.2 },
  error: { pace: 0.15, core: 0.7, swirl: 0 },
}

/** Colored light seen through a thick glass sphere: refraction, dispersion, fresnel rim and highlights. */
const GLASS = `uniform float u_phase;
uniform float u_core;
uniform float u_swirl;
uniform float u_thickness;
uniform float u_gloss;
vec3 inner(vec2 p){
  vec3 col=u_c0*.55;
  float size=u_core*(1.+u_level*.4)*.75;
  for(int i=0;i<3;i++){
    float fi=float(i);
    float a=u_phase*(.6+fi*.3)*(1.+u_swirl)+fi*2.1;
    vec2 c=vec2(cos(a),sin(a*.8))*.32;
    vec3 ci=fi<.5?u_c1:fi<1.5?u_c2:u_c3;
    // Mixed rather than added, so overlapping light never blows out to white.
    col=mix(col,ci,smoothstep(size,0.,length(p-c))*.8);
  }
  return col;
}
void main(){
  vec2 uv=(gl_FragCoord.xy*2.-u_res)/u_res.y;
  float R=.9;
  vec2 q=uv/R;
  float r=length(q);
  float aa=3./u_res.y;
  float mask=1.-smoothstep(1.-aa,1.+aa,r);
  if(mask<=0.){gl_FragColor=vec4(0.);return;}
  float z=sqrt(max(0.,1.-r*r));
  vec3 n=vec3(q,z);
  // Thick glass magnifies the centre and bends the edges; channels bend slightly apart.
  float bend=.45*u_thickness;
  vec2 rp=q*(1.-bend+bend*z);
  float disp=.06*u_thickness*(1.-z);
  vec3 col=vec3(inner(rp*(1.+disp)).r,inner(rp).g,inner(rp*(1.-disp)).b);
  // Thicker glass toward the rim absorbs more; the very edge catches a bright fresnel line.
  col*=1.-.45*u_thickness*(1.-z);
  float fres=pow(1.-z,4.);
  col=mix(col,vec3(1.),fres*.65);
  vec3 L=normalize(vec3(-.5,.6,.8));
  col+=pow(max(dot(reflect(-L,n),vec3(0.,0.,1.)),0.),60.)*.9*u_gloss;
  col+=pow(max(dot(reflect(-normalize(vec3(.6,-.5,.6)),n),vec3(0.,0.,1.)),0.),12.)*.12*u_gloss;
  gl_FragColor=vec4(col*mask,mask);
}`

/**
 * A glass sphere with colored light drifting inside, bent and split by the glass.
 * The light swells with `level`, circles faster while thinking, and pulls in while
 * connecting. `palette` picks the colors.
 */
function GlassOrb({
  glow = 0,
  thickness = 1,
  gloss = 1,
  className,
  ...props
}: ShaderOrbProps & { thickness?: number; gloss?: number }) {
  const { state = "idle", level, size = 160, speed, palette = "primary", ...rest } = props
  const canvasRef = useShaderOrb({ state, level, size, speed, palette }, GLASS, glassTargets, { thickness, gloss })
  return orbFrame(
    "glass",
    state,
    size,
    glow,
    className,
    rest,
    <canvas ref={canvasRef} className="size-full" />,
    paletteGlow(palette, state === "error"),
  )
}

/** Style an orb can take from a provider. Size stays per orb, since it depends on where the orb sits. */
type OrbStyle = OrbMaterial &
  Pick<OrbProps, "glow" | "speed" | "className"> & {
    variant?: VoiceOrbVariant
    palette?: Palette
    sensitivity?: number
  }

const VoiceOrbContext = React.createContext<OrbStyle>({})

/**
 * Sets the default orb style for everything inside it: variant, palette, glow, speed,
 * sensitivity and material. Put it at the root to style every orb in an app; any prop on
 * a VoiceOrb still wins, and classes are combined.
 */
function VoiceOrbProvider({ children, ...style }: OrbStyle & { children: React.ReactNode }) {
  return <VoiceOrbContext.Provider value={style}>{children}</VoiceOrbContext.Provider>
}

/**
 * Presence for a voice agent, drawn in the primary color.
 * `particles`: a rotating particle mesh. `ring`: a soft glowing ring.
 * `wave`: twisting ribbons along a line, twice as wide as `size`.
 * `aura`: soft blurred blobs. `bars`: a circular equalizer. `halftone`: a rippling dot matrix.
 * `plasma`: glowing warped noise in a sphere. `liquid`: glossy merging metaballs. `glass`: light
 * refracted through a glass sphere. These three are WebGL shaders and fall back to `aura`
 * where WebGL is unavailable. `dot`: a minimal dot for tight spots, legible down to 16px.
 * Every variant takes the same states, `speed`, `glow` and `sensitivity`.
 */
/** Shape and material settings. Each applies to the variants named; the rest ignore it. */
type OrbMaterial = {
  /** Particles: approximate count. Defaults to scale with size. */
  particles?: number
  /** Ring: stroke weight. Glass: how strongly it bends and tints the light. 1 is the default. */
  thickness?: number
  /** Aura: film grain strength, 0 to 2. */
  grain?: number
  /** Bars: number of bars. */
  bars?: number
  /** Halftone: dot grid density multiplier. */
  density?: number
  /** Plasma: how strongly the noise warps. */
  turbulence?: number
  /** Plasma: brightness of the flaring streaks. */
  filaments?: number
  /** Liquid: number of blobs, 1 to 8. */
  blobs?: number
  /** Liquid and glass: highlight strength. */
  gloss?: number
}

type VoiceOrbProps = OrbProps &
  OrbMaterial & {
    /** How strongly `level` moves the orb. 1 is as measured; 2 doubles it, capped at full. */
    sensitivity?: number
    /** Defaults to the nearest VoiceOrbProvider, then "particles". */
    variant?: VoiceOrbVariant
    /** Aura, plasma, liquid and glass colors: a named palette, custom colors (base + 3), or "primary" (default). */
    palette?: Palette
  }

function VoiceOrb(own: VoiceOrbProps) {
  const defaults = React.useContext(VoiceOrbContext)
  // Props set on this orb win over the provider's; unset ones fall through to it.
  const set = Object.fromEntries(Object.entries(own).filter(([, v]) => v !== undefined)) as VoiceOrbProps
  const {
    variant: resolved = "particles",
    palette,
    level = 0,
    sensitivity = 1,
    particles,
    thickness,
    grain,
    bars,
    density,
    turbulence,
    filaments,
    blobs,
    gloss,
    ...rest
  }: VoiceOrbProps = { ...defaults, ...set, className: cn(defaults.className, own.className) || undefined }
  const webgl = React.useSyncExternalStore(noSubscribe, hasWebGL, () => true)
  const props = { ...rest, level: Math.min(1, level * sensitivity) }
  const aura = <AuraOrb palette={palette} grain={grain} {...props} />
  if (resolved === "ring") return <RingOrb thickness={thickness} {...props} />
  if (resolved === "wave") return <WaveOrb {...props} />
  if (resolved === "aura") return aura
  if (resolved === "plasma")
    return webgl ? <PlasmaOrb palette={palette} turbulence={turbulence} filaments={filaments} {...props} /> : aura
  if (resolved === "glass")
    return webgl ? <GlassOrb palette={palette} thickness={thickness} gloss={gloss} {...props} /> : aura
  if (resolved === "liquid") return webgl ? <LiquidOrb palette={palette} blobs={blobs} gloss={gloss} {...props} /> : aura
  if (resolved === "dot") return <DotOrb {...props} />
  if (resolved === "bars") return <BarsOrb bars={bars} {...props} />
  if (resolved === "halftone") return <HalftoneOrb density={density} {...props} />
  return <ParticleOrb particles={particles} {...props} />
}

export {
  VoiceOrb,
  VoiceOrbProvider,
  auraPalettes,
  type OrbMaterial,
  type OrbPalette,
  type OrbStyle,
  type VoiceOrbVariant,
  type VoiceState,
}
```

---

# Waveform

Live spectrum bars for microphone input or agent speech.

Docs: https://jds-ruddy.vercel.app/docs/components/waveform

## Installation

```bash
npx shadcn@latest add @jds/waveform
```

npm dependencies: `cn`, `motion`

## Usage

```tsx
import { Waveform } from "@/components/voice/waveform"
import { useAudioLevel } from "@/hooks/use-audio-level"

const mic = useAudioLevel()

<Waveform spectrum={mic.spectrum} active={mic.active} />
```

## Example

```tsx
"use client"

import { Button } from "@/components/ui/button"
import { Waveform } from "@/components/voice/waveform"
import { useAudioLevel } from "@/hooks/use-audio-level"
import { useSimulatedSpectrum } from "@/hooks/use-simulated-spectrum"
import { MicIcon, MicOffIcon } from "@/lib/icons"

export default function WaveformDemo() {
  const mic = useAudioLevel({ bands: 32 })
  const simulated = useSimulatedSpectrum(!mic.active, 32)

return (
    <div className="flex flex-col items-center gap-6">
      <Waveform spectrum={mic.active ? mic.spectrum : simulated.spectrum} className="w-64" />
      <Button variant="outline" size="sm" onClick={mic.active ? mic.stop : mic.start}>
        {mic.active ? <MicOffIcon /> : <MicIcon />}
        {mic.active ? "Stop microphone" : "Use microphone"}
      </Button>
      {mic.error && <p className="text-xs text-destructive">{mic.error.message}</p>}
    </div>
  )
}
```

## API Reference

### Waveform

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `spectrum` | `number[]` |  | One value 0 to 1 per bar. |
| `active` | `boolean` | `true` | Inactive bars flatten and dim. |

### useAudioLevel

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `bands` | `number` | `24` | Number of spectrum bands. |
| `returns` | `{ level, spectrum, active, error, start, stop }` |  | Call start() from a user gesture. |

## Source

### components/voice/waveform.tsx

```tsx
"use client"

import * as React from "react"
import { motion } from "motion/react"
import { cn } from "cn"

/** Symmetric bar waveform. Pass `spectrum` (0..1 per band) from `useAudioLevel`. */
function Waveform({
  spectrum,
  active = true,
  className,
  ...props
}: React.ComponentProps<"div"> & { spectrum: number[]; active?: boolean }) {
  return (
    <div
      data-slot="waveform"
      aria-hidden
      className={cn("flex h-10 items-center justify-center gap-0.75", className)}
      {...props}
    >
      {spectrum.map((v, i) => (
        <motion.span
          key={i}
          className={cn("w-0.75 rounded-full", active ? "bg-foreground" : "bg-muted-foreground/40")}
          animate={{ height: `${Math.max(12, (active ? v : 0) * 100)}%` }}
          transition={{ type: "spring", stiffness: 600, damping: 30, mass: 0.3 }}
        />
      ))}
    </div>
  )
}

export { Waveform }
```

### hooks/use-audio-level.ts

```ts
"use client"

import * as React from "react"

/**
 * Live microphone loudness (0..1) and frequency bands, sampled per animation frame.
 * Call `start()` from a user gesture; browsers block mic access otherwise.
 */
export function useAudioLevel({ bands = 24 }: { bands?: number } = {}) {
  const [level, setLevel] = React.useState(0)
  const [spectrum, setSpectrum] = React.useState<number[]>(() => Array(bands).fill(0))
  const [active, setActive] = React.useState(false)
  const [error, setError] = React.useState<Error | null>(null)
  const cleanup = React.useRef<(() => void) | null>(null)

const stop = React.useCallback(() => {
    cleanup.current?.()
    cleanup.current = null
    setActive(false)
    setLevel(0)
    setSpectrum(Array(bands).fill(0))
  }, [bands])

const start = React.useCallback(async () => {
    if (cleanup.current) return
    try {
      const stream = await navigator.mediaDevices.getUserMedia({ audio: true })
      const ctx = new AudioContext()
      const analyser = ctx.createAnalyser()
      analyser.fftSize = 256
      analyser.smoothingTimeConstant = 0.75
      ctx.createMediaStreamSource(stream).connect(analyser)
      const data = new Uint8Array(analyser.frequencyBinCount)
      let raf = 0

const tick = () => {
        analyser.getByteFrequencyData(data)
        const step = Math.floor(data.length / bands)
        const next = Array.from({ length: bands }, (_, i) => {
          let sum = 0
          for (let j = 0; j < step; j++) sum += data[i * step + j]
          return sum / step / 255
        })
        setSpectrum(next)
        setLevel(Math.min(1, (next.reduce((a, b) => a + b, 0) / bands) * 2.2))
        raf = requestAnimationFrame(tick)
      }
      tick()
      setActive(true)
      setError(null)

cleanup.current = () => {
        cancelAnimationFrame(raf)
        stream.getTracks().forEach((t) => t.stop())
        void ctx.close()
      }
    } catch (e) {
      setError(e instanceof Error ? e : new Error(String(e)))
    }
  }, [bands])

React.useEffect(() => () => cleanup.current?.(), [])

return { level, spectrum, active, error, start, stop }
}
```

---

# Push to Talk

Hold to speak with pointer or the Space key. The ring grows with input level so users know they're heard.

Docs: https://jds-ruddy.vercel.app/docs/components/push-to-talk

## Installation

```bash
npx shadcn@latest add @jds/push-to-talk
```

npm dependencies: `cn`, `motion`

Also installs: `@jds/utils`

## Usage

```tsx
import { PushToTalk } from "@/components/voice/push-to-talk"

<PushToTalk onPressStart={mic.start} onPressEnd={mic.stop} level={mic.level} />
```

## Example

```tsx
"use client"

import * as React from "react"

import { Kbd } from "@/components/ui/kbd"
import { PushToTalk } from "@/components/voice/push-to-talk"
import { useSimulatedSpectrum } from "@/hooks/use-simulated-spectrum"

export default function PushToTalkDemo() {
  const [pressed, setPressed] = React.useState(false)
  const { level } = useSimulatedSpectrum(pressed)

return (
    <div className="flex flex-col items-center gap-4">
      <PushToTalk level={level} onPressStart={() => setPressed(true)} onPressEnd={() => setPressed(false)} />
      <p className="flex items-center gap-1.5 text-xs text-muted-foreground">
        {pressed ? (
          "Listening…"
        ) : (
          <>
            Hold the button or <Kbd>Space</Kbd>
          </>
        )}
      </p>
    </div>
  )
}
```

## API Reference

### PushToTalk

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onPressStart` | `() => void` |  |  |
| `onPressEnd` | `() => void` |  | Also fires on window blur. |
| `level` | `number` | `0` | Input loudness 0 to 1. |
| `hotkey` | `boolean` | `true` | Space triggers, except while typing in a field. |

## Source

### components/voice/push-to-talk.tsx

```tsx
"use client"

import * as React from "react"
import { motion } from "motion/react"
import { cn } from "cn"

import { MicIcon } from "@/lib/icons"
import { spring } from "@/lib/motion"

/**
 * Hold to talk: pointer press or the Space key (when `hotkey` is on).
 * Ring scales with `level` so the user sees they're being heard.
 */
function PushToTalk({
  onPressStart,
  onPressEnd,
  level = 0,
  hotkey = true,
  label = "Hold to talk",
  className,
  ...props
}: Omit<React.ComponentProps<"button">, "onPointerDown" | "onPointerUp"> & {
  onPressStart?: () => void
  onPressEnd?: () => void
  level?: number
  hotkey?: boolean
  label?: string
}) {
  const [pressed, setPressed] = React.useState(false)
  const pressedRef = React.useRef(false)

const begin = React.useCallback(() => {
    if (pressedRef.current) return
    pressedRef.current = true
    setPressed(true)
    onPressStart?.()
  }, [onPressStart])

const end = React.useCallback(() => {
    if (!pressedRef.current) return
    pressedRef.current = false
    setPressed(false)
    onPressEnd?.()
  }, [onPressEnd])

React.useEffect(() => {
    if (!hotkey) return
    const isTyping = (t: EventTarget | null) =>
      t instanceof HTMLElement && (t.isContentEditable || ["INPUT", "TEXTAREA", "SELECT"].includes(t.tagName))
    const down = (e: KeyboardEvent) => {
      if (e.code === "Space" && !e.repeat && !isTyping(e.target)) {
        e.preventDefault()
        begin()
      }
    }
    const up = (e: KeyboardEvent) => {
      if (e.code === "Space") end()
    }
    window.addEventListener("keydown", down)
    window.addEventListener("keyup", up)
    window.addEventListener("blur", end)
    return () => {
      window.removeEventListener("keydown", down)
      window.removeEventListener("keyup", up)
      window.removeEventListener("blur", end)
    }
  }, [hotkey, begin, end])

return (
    <div className="relative grid place-items-center">
      <motion.span
        aria-hidden
        className="absolute inset-0 rounded-full bg-muted"
        animate={{ scale: pressed ? 1.25 + level * 0.6 : 1, opacity: pressed ? 1 : 0 }}
        transition={spring.gentle}
      />
      <motion.button
        type="button"
        data-slot="push-to-talk"
        data-pressed={pressed || undefined}
        aria-pressed={pressed}
        aria-label={label}
        onPointerDown={(e) => {
          e.currentTarget.setPointerCapture(e.pointerId)
          begin()
        }}
        onPointerUp={end}
        onPointerCancel={end}
        whileTap={{ scale: 0.94 }}
        transition={spring.snappy}
        className={cn(
          "relative grid size-16 touch-none place-items-center rounded-full border bg-card text-foreground shadow-sm transition-colors duration-200 outline-none select-none focus-visible:ring-4 focus-visible:ring-ring/30",
          "data-pressed:border-foreground data-pressed:bg-foreground data-pressed:text-background",
          className
        )}
        {...(props as React.ComponentProps<typeof motion.button>)}
      >
        <MicIcon className="size-6" />
      </motion.button>
    </div>
  )
}

export { PushToTalk }
```

---

# Live Transcript

Rolling speech transcript per speaker. Interim text is dimmed until recognition commits it.

Docs: https://jds-ruddy.vercel.app/docs/components/live-transcript

## Installation

```bash
npx shadcn@latest add @jds/live-transcript
```

npm dependencies: `cn`, `motion`

## Usage

```tsx
import { LiveTranscript } from "@/components/voice/live-transcript"

<LiveTranscript segments={[{ id: "1", speaker: "user", text: "Move my 3pm", final: false }]} />
```

## Example

```tsx
"use client"

import * as React from "react"

import { LiveTranscript, type TranscriptSegment } from "@/components/voice/live-transcript"

const script: Omit<TranscriptSegment, "final">[] = [
  { id: "1", speaker: "user", text: "What's on my calendar this afternoon?" },
  {
    id: "2",
    speaker: "agent",
    text: "Two things: design review at 2 and a call with Luca at 3.",
  },
  { id: "3", speaker: "user", text: "Push the call to tomorrow." },
]

export default function LiveTranscriptDemo() {
  const [segments, setSegments] = React.useState<TranscriptSegment[]>([])

React.useEffect(() => {
    let line = 0
    let word = 0
    const id = setInterval(() => {
      if (line >= script.length) {
        line = 0
        word = 0
        setSegments([])
        return
      }
      const words = script[line].text.split(" ")
      word++
      const current = {
        ...script[line],
        text: words.slice(0, word).join(" "),
        final: word >= words.length,
      }
      setSegments((prev) => [...prev.filter((s) => s.id !== current.id), current])
      if (word >= words.length) {
        line++
        word = 0
      }
    }, 180)
    return () => clearInterval(id)
  }, [])

return <LiveTranscript segments={segments} className="h-40 w-full max-w-md" />
}
```

## API Reference

### LiveTranscript

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `segments` | `{ id, speaker: "user" \| "agent", text, final }[]` |  |  |
| `agentName` | `string` | `"Agent"` | Label for agent lines. |

## Source

### components/voice/live-transcript.tsx

```tsx
"use client"

import * as React from "react"
import { AnimatePresence, motion } from "motion/react"
import { cn } from "cn"

type TranscriptSegment = { id: string; speaker: "user" | "agent"; text: string; final: boolean }

/**
 * Rolling transcript. Interim (non-final) text renders dimmed so users can see
 * recognition is in flight without mistaking it for committed input.
 */
function LiveTranscript({
  segments,
  agentName = "Agent",
  className,
  ...props
}: React.ComponentProps<"div"> & { segments: TranscriptSegment[]; agentName?: string }) {
  return (
    <div
      data-slot="live-transcript"
      role="log"
      aria-live="polite"
      className={cn("flex flex-col gap-3 text-sm", className)}
      {...props}
    >
      <AnimatePresence initial={false}>
        {segments.map((s) => (
          <motion.div
            key={s.id}
            layout="position"
            initial={{ opacity: 0, y: 6 }}
            animate={{ opacity: 1, y: 0 }}
            className="grid grid-cols-[4.5rem_1fr] items-baseline gap-3"
          >
            <span
              className={cn(
                "text-xs font-medium tracking-wide uppercase",
                s.speaker === "agent" ? "text-foreground" : "text-muted-foreground"
              )}
            >
              {s.speaker === "agent" ? agentName : "You"}
            </span>
            <p className={cn("leading-relaxed transition-colors duration-300", !s.final && "text-muted-foreground")}>
              {s.text}
              {!s.final && <span className="ml-0.5 inline-block h-3.5 w-px animate-pulse bg-current align-middle" />}
            </p>
          </motion.div>
        ))}
      </AnimatePresence>
    </div>
  )
}

export { LiveTranscript, type TranscriptSegment }
```

---

# Voice Picker

Choose a synthetic voice, with a spoken preview for each option.

Docs: https://jds-ruddy.vercel.app/docs/components/voice-picker

## Installation

```bash
npx shadcn@latest add @jds/voice-picker
```

npm dependencies: `@base-ui/react`, `cn`, `motion`

Also installs: `@jds/button`, `@jds/utils`

## Usage

```tsx
import { VoicePicker } from "@/components/voice/voice-picker"

<VoicePicker
  voices={[{ id: "aria", name: "Aria", description: "Warm and steady", tags: ["Calm"] }]}
  value={voice}
  onValueChange={setVoice}
  onPreview={(v) => tts.play(v.id)}
  onStopPreview={() => tts.stop()}
/>
```

## Example

```tsx
"use client"

import { VoicePicker, type Voice } from "@/components/voice/voice-picker"

const voices: Voice[] = [
  { id: "0", name: "Aria", description: "Warm and steady", tags: ["Calm", "Support"] },
  { id: "1", name: "Leo", description: "Bright and quick", tags: ["Upbeat", "Sales"] },
  { id: "2", name: "Mina", description: "Clear and precise", tags: ["Neutral", "Narration"] },
]

/** Previews with the browser's built-in speech synthesis. Swap for your TTS provider. */
function speak(voice: Voice) {
  return new Promise<void>((resolve) => {
    if (typeof speechSynthesis === "undefined") return resolve()
    speechSynthesis.cancel()
    const u = new SpeechSynthesisUtterance(`Hi, I'm ${voice.name}. How can I help you today?`)
    const system = speechSynthesis.getVoices().filter((v) => v.lang.startsWith("en"))
    u.voice = system[Number(voice.id) % Math.max(1, system.length)] ?? null
    u.onend = () => resolve()
    u.onerror = () => resolve()
    speechSynthesis.speak(u)
  })
}

export default function VoicePickerDemo() {
  return (
    <VoicePicker
      voices={voices}
      className="max-w-sm"
      onPreview={speak}
      onStopPreview={() => typeof speechSynthesis !== "undefined" && speechSynthesis.cancel()}
    />
  )
}
```

## API Reference

### VoicePicker

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `voices` | `{ id, name, description?, tags? }[]` |  |  |
| `onPreview` | `(voice) => Promise<void> \| void` |  | Play a sample. The button shows stop until the promise settles. |
| `onStopPreview` | `() => void` |  | Cut a preview short. |
| `value` | `string` |  | Controlled voice id. Or use defaultValue. |

## Source

### components/voice/voice-picker.tsx

```tsx
"use client"

import * as React from "react"
import { Radio } from "@base-ui/react/radio"
import { RadioGroup } from "@base-ui/react/radio-group"
import { AnimatePresence, motion } from "motion/react"
import { cn } from "cn"

import { Button } from "@/components/ui/button"
import { PlayIcon, StopIcon } from "@/lib/icons"
import { spring } from "@/lib/motion"

type Voice = { id: string; name: string; description?: string; tags?: string[] }

/**
 * Choose a synthetic voice. Each option has a preview button: `onPreview` plays a
 * sample and returns a promise that settles when it ends; `onStopPreview` cuts it short.
 */
function VoicePicker({
  voices,
  value: controlled,
  defaultValue,
  onValueChange,
  onPreview,
  onStopPreview,
  className,
}: {
  voices: Voice[]
  value?: string
  defaultValue?: string
  onValueChange?: (id: string) => void
  onPreview?: (voice: Voice) => Promise<void> | void
  onStopPreview?: () => void
  className?: string
}) {
  const [uncontrolled, setUncontrolled] = React.useState(defaultValue ?? voices[0]?.id)
  const [playing, setPlaying] = React.useState<string | null>(null)
  const value = controlled ?? uncontrolled

const preview = async (voice: Voice) => {
    if (playing === voice.id) {
      onStopPreview?.()
      setPlaying(null)
      return
    }
    if (playing) onStopPreview?.()
    setPlaying(voice.id)
    try {
      await onPreview?.(voice)
    } finally {
      setPlaying((p) => (p === voice.id ? null : p))
    }
  }

return (
    <RadioGroup
      data-slot="voice-picker"
      value={value}
      onValueChange={(v) => {
        if (controlled === undefined) setUncontrolled(v as string)
        onValueChange?.(v as string)
      }}
      className={cn("flex w-full flex-col gap-2", className)}
    >
      {voices.map((voice) => (
        <div
          key={voice.id}
          className="relative flex items-center gap-3 rounded-xl border bg-card p-3 transition-colors has-data-checked:border-foreground/40 has-data-checked:bg-accent/40 has-focus-visible:ring-3 has-focus-visible:ring-ring/50"
        >
          {/* The radio stretches over the whole card; the preview button sits above it. */}
          <Radio.Root
            value={voice.id}
            aria-label={voice.name}
            className="peer grid size-4 shrink-0 place-items-center rounded-full border outline-none after:absolute after:inset-0 after:rounded-xl data-checked:border-foreground"
          >
            <Radio.Indicator className="size-2 rounded-full bg-foreground" />
          </Radio.Root>
          <div className="min-w-0 flex-1">
            <div className="text-sm font-medium">{voice.name}</div>
            {voice.description && <div className="text-xs text-muted-foreground">{voice.description}</div>}
            {voice.tags && voice.tags.length > 0 && (
              <div className="mt-1.5 flex flex-wrap gap-1">
                {voice.tags.map((t) => (
                  <span key={t} className="rounded-md bg-muted px-1.5 py-0.5 text-[11px] text-muted-foreground">
                    {t}
                  </span>
                ))}
              </div>
            )}
          </div>
          {onPreview && (
            <Button
              type="button"
              variant="outline"
              size="icon-sm"
              aria-label={playing === voice.id ? `Stop ${voice.name} preview` : `Preview ${voice.name}`}
              className="relative z-10 rounded-full"
              onClick={() => preview(voice)}
            >
              <AnimatePresence mode="popLayout" initial={false}>
                <motion.span
                  key={playing === voice.id ? "stop" : "play"}
                  initial={{ scale: 0.5, opacity: 0 }}
                  animate={{ scale: 1, opacity: 1 }}
                  exit={{ scale: 0.5, opacity: 0 }}
                  transition={spring.snappy}
                  className="grid place-items-center"
                >
                  {playing === voice.id ? (
                    <StopIcon className="size-3 fill-current" />
                  ) : (
                    <PlayIcon className="size-3.5 fill-current" />
                  )}
                </motion.span>
              </AnimatePresence>
            </Button>
          )}
        </div>
      ))}
    </RadioGroup>
  )
}

export { VoicePicker, type Voice }
```

---

# Call Controls

Controls for a realtime voice session: status and timer, mute, interrupt the agent, end the call.

Docs: https://jds-ruddy.vercel.app/docs/components/call-controls

## Installation

```bash
npx shadcn@latest add @jds/call-controls
```

npm dependencies: `@base-ui/react`, `cn`

Also installs: `@jds/button`, `@jds/tooltip`, `@jds/utils`

## Usage

```tsx
import { CallControls, CallEnd, CallInterrupt, CallMute, CallStatus } from "@/components/voice/call-controls"

<CallControls>
  <CallStatus state="connected" startedAt={startedAt} />
  <CallMute onPressedChange={setMuted} />
  <CallInterrupt disabled={!agentSpeaking} onClick={interrupt} />
  <CallEnd onClick={hangUp} />
</CallControls>
```

## Example

```tsx
"use client"

import * as React from "react"
import { toast } from "sonner"

import { Button } from "@/components/ui/button"
import {
  CallControls,
  CallEnd,
  CallInterrupt,
  CallMute,
  CallStatus,
  type CallState,
} from "@/components/voice/call-controls"
import { VoiceOrb } from "@/components/voice/voice-orb"
import { useSimulatedSpectrum } from "@/hooks/use-simulated-spectrum"

export default function CallControlsDemo() {
  const [state, setState] = React.useState<CallState>("connecting")
  const [startedAt, setStartedAt] = React.useState<number>()
  const [speaking, setSpeaking] = React.useState(true)
  const { level } = useSimulatedSpectrum(state === "connected" && speaking)

React.useEffect(() => {
    if (state !== "connecting") return
    const id = setTimeout(() => {
      setState("connected")
      setStartedAt(Date.now())
    }, 1200)
    return () => clearTimeout(id)
  }, [state])

return (
    <div className="flex flex-col items-center gap-6">
      <VoiceOrb
        state={state === "connected" ? (speaking ? "speaking" : "listening") : "idle"}
        level={level}
        size={140}
      />
      {state === "ended" ? (
        <Button variant="outline" onClick={() => setState("connecting")}>
          Call again
        </Button>
      ) : (
        <CallControls>
          <CallStatus state={state} startedAt={startedAt} />
          <CallMute onPressedChange={(muted) => toast(muted ? "Muted" : "Unmuted")} />
          <CallInterrupt disabled={!speaking || state !== "connected"} onClick={() => setSpeaking(false)} />
          <CallEnd onClick={() => setState("ended")} />
        </CallControls>
      )}
    </div>
  )
}
```

## API Reference

### CallStatus

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state` | `"connecting" \| "connected" \| "reconnecting" \| "ended"` |  |  |
| `startedAt` | `number` |  | Epoch ms. Shows elapsed time while connected. |

### CallMute

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pressed` | `boolean` |  | Muted. Or use defaultPressed with onPressedChange. |

## Source

### components/voice/call-controls.tsx

```tsx
"use client"

import * as React from "react"
import { Toggle } from "@base-ui/react/toggle"
import { cn } from "cn"

import { Button } from "@/components/ui/button"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"
import { EndCallIcon, InterruptIcon, MicIcon, MicOffIcon } from "@/lib/icons"

type CallState = "connecting" | "connected" | "reconnecting" | "ended"

/** Pill that holds the controls for a realtime voice session. */
function CallControls({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="call-controls"
      role="toolbar"
      aria-label="Call controls"
      className={cn("inline-flex items-center gap-1.5 rounded-full border bg-card p-1.5 shadow-sm", className)}
      {...props}
    />
  )
}

const stateLabel: Record<CallState, string> = {
  connecting: "Connecting",
  connected: "Connected",
  reconnecting: "Reconnecting",
  ended: "Call ended",
}

/** Connection dot, label, and elapsed time since `startedAt` while connected. */
function CallStatus({ state, startedAt, className }: { state: CallState; startedAt?: number; className?: string }) {
  const [now, setNow] = React.useState(() => Date.now())
  React.useEffect(() => {
    if (state !== "connected") return
    const id = setInterval(() => setNow(Date.now()), 1000)
    return () => clearInterval(id)
  }, [state])

const elapsed = startedAt && state === "connected" ? Math.max(0, Math.floor((now - startedAt) / 1000)) : null
  const time = elapsed === null ? null : `${Math.floor(elapsed / 60)}:${String(elapsed % 60).padStart(2, "0")}`

return (
    <div
      data-slot="call-status"
      data-state={state}
      aria-live="polite"
      className={cn("flex items-center gap-2 px-2.5 text-xs text-muted-foreground", className)}
    >
      <span
        className={cn(
          "size-1.5 rounded-full bg-muted-foreground",
          state === "connected" && "bg-success",
          (state === "connecting" || state === "reconnecting") && "animate-pulse-soft bg-warning"
        )}
      />
      <span>{stateLabel[state]}</span>
      {time && <span className="font-mono text-foreground tabular-nums">{time}</span>}
    </div>
  )
}

function ControlTooltip({ label, children }: { label: string; children: React.ReactElement }) {
  return (
    <Tooltip>
      <TooltipTrigger render={children} />
      <TooltipContent>{label}</TooltipContent>
    </Tooltip>
  )
}

/** Mute the microphone. Pressed means muted. */
function CallMute({ className, pressed: controlled, defaultPressed, onPressedChange, ...props }: Toggle.Props) {
  const [muted, setMuted] = React.useState(defaultPressed ?? false)
  const pressed = controlled ?? muted
  return (
    <ControlTooltip label={pressed ? "Unmute" : "Mute"}>
      <Toggle
        data-slot="call-mute"
        aria-label={pressed ? "Unmute" : "Mute"}
        pressed={pressed}
        onPressedChange={(p, e) => {
          setMuted(p)
          onPressedChange?.(p, e)
        }}
        className={cn(
          "grid size-10 place-items-center rounded-full bg-secondary text-secondary-foreground transition-colors outline-none hover:bg-accent focus-visible:ring-3 focus-visible:ring-ring/50 [&_svg]:size-4.5",
          "data-pressed:bg-foreground data-pressed:text-background",
          className
        )}
        {...props}
      >
        {pressed ? <MicOffIcon /> : <MicIcon />}
      </Toggle>
    </ControlTooltip>
  )
}

/** Stop the agent mid-sentence so the user can take the turn. */
function CallInterrupt({ className, ...props }: React.ComponentProps<typeof Button>) {
  return (
    <ControlTooltip label="Interrupt">
      <Button
        data-slot="call-interrupt"
        variant="secondary"
        aria-label="Interrupt"
        className={cn("size-10 rounded-full [&_svg:not([class*='size-'])]:size-4.5", className)}
        {...props}
      >
        <InterruptIcon />
      </Button>
    </ControlTooltip>
  )
}

function CallEnd({ className, ...props }: React.ComponentProps<typeof Button>) {
  return (
    <ControlTooltip label="End call">
      <Button
        data-slot="call-end"
        aria-label="End call"
        className={cn(
          "h-10 rounded-full bg-destructive px-4 text-white hover:bg-destructive/90 [&_svg:not([class*='size-'])]:size-4.5",
          className
        )}
        {...props}
      >
        <EndCallIcon />
      </Button>
    </ControlTooltip>
  )
}

export { CallControls, CallStatus, CallMute, CallInterrupt, CallEnd, type CallState }
```

---

# Avatar

An image with a text fallback for users and agents.

Docs: https://jds-ruddy.vercel.app/docs/components/avatar

## Installation

```bash
npx shadcn@latest add @jds/avatar
```

npm dependencies: `@base-ui/react`, `cn`

## Example

```tsx
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"

export default function AvatarDemo() {
  return (
    <div className="flex items-center gap-3">
      <Avatar>
        <AvatarImage src="https://github.com/shadcn.png" alt="shadcn" />
        <AvatarFallback>CN</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarFallback>AI</AvatarFallback>
      </Avatar>
    </div>
  )
}
```

## Source

### components/ui/avatar.tsx

```tsx
"use client"

import * as React from "react"
import { Avatar as AvatarPrimitive } from "@base-ui/react/avatar"
import { cn } from "cn"

function Avatar({
  className,
  size = "default",
  ...props
}: AvatarPrimitive.Root.Props & {
  size?: "default" | "sm" | "lg"
}) {
  return (
    <AvatarPrimitive.Root
      data-slot="avatar"
      data-size={size}
      className={cn(
        "group/avatar relative flex size-8 shrink-0 rounded-full select-none after:absolute after:inset-0 after:rounded-full after:border after:border-border after:mix-blend-darken data-[size=lg]:size-10 data-[size=sm]:size-6 dark:after:mix-blend-lighten",
        className
      )}
      {...props}
    />
  )
}

function AvatarImage({ className, ...props }: AvatarPrimitive.Image.Props) {
  return (
    <AvatarPrimitive.Image
      data-slot="avatar-image"
      className={cn(
        "aspect-square size-full rounded-full object-cover",
        className
      )}
      {...props}
    />
  )
}

function AvatarFallback({
  className,
  ...props
}: AvatarPrimitive.Fallback.Props) {
  return (
    <AvatarPrimitive.Fallback
      data-slot="avatar-fallback"
      className={cn(
        "flex size-full items-center justify-center rounded-full bg-muted text-sm text-muted-foreground group-data-[size=sm]/avatar:text-xs",
        className
      )}
      {...props}
    />
  )
}

function AvatarBadge({ className, ...props }: React.ComponentProps<"span">) {
  return (
    <span
      data-slot="avatar-badge"
      className={cn(
        "absolute right-0 bottom-0 z-10 inline-flex items-center justify-center rounded-full bg-primary text-primary-foreground bg-blend-color ring-2 ring-background select-none",
        "group-data-[size=sm]/avatar:size-2 group-data-[size=sm]/avatar:[&>svg]:hidden",
        "group-data-[size=default]/avatar:size-2.5 group-data-[size=default]/avatar:[&>svg]:size-2",
        "group-data-[size=lg]/avatar:size-3 group-data-[size=lg]/avatar:[&>svg]:size-2",
        className
      )}
      {...props}
    />
  )
}

function AvatarGroup({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="avatar-group"
      className={cn(
        "group/avatar-group flex -space-x-2 *:data-[slot=avatar]:ring-2 *:data-[slot=avatar]:ring-background",
        className
      )}
      {...props}
    />
  )
}

function AvatarGroupCount({
  className,
  ...props
}: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="avatar-group-count"
      className={cn(
        "relative flex size-8 shrink-0 items-center justify-center rounded-full bg-muted text-sm text-muted-foreground ring-2 ring-background group-has-data-[size=lg]/avatar-group:size-10 group-has-data-[size=sm]/avatar-group:size-6 [&>svg]:size-4 group-has-data-[size=lg]/avatar-group:[&>svg]:size-5 group-has-data-[size=sm]/avatar-group:[&>svg]:size-3",
        className
      )}
      {...props}
    />
  )
}

export {
  Avatar,
  AvatarImage,
  AvatarFallback,
  AvatarGroup,
  AvatarGroupCount,
  AvatarBadge,
}
```

---

# Badge

A small status label.

Docs: https://jds-ruddy.vercel.app/docs/components/badge

## Installation

```bash
npx shadcn@latest add @jds/badge
```

npm dependencies: `@base-ui/react`, `class-variance-authority`, `cn`

## Example

```tsx
import { Badge } from "@/components/ui/badge"

export default function BadgeDemo() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <Badge>Default</Badge>
      <Badge variant="secondary">Secondary</Badge>
      <Badge variant="outline">Outline</Badge>
      <Badge variant="destructive">Destructive</Badge>
    </div>
  )
}
```

## Source

### components/ui/badge.tsx

```tsx
import { mergeProps } from "@base-ui/react/merge-props"
import { useRender } from "@base-ui/react/use-render"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "cn"

const badgeVariants = cva(
  "group/badge inline-flex h-5 w-fit shrink-0 items-center justify-center gap-1 overflow-hidden rounded-4xl border border-transparent px-2 py-0.5 text-xs font-medium whitespace-nowrap transition-all focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 [&>svg]:pointer-events-none [&>svg]:size-3!",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground [a]:hover:bg-primary/80",
        secondary:
          "bg-secondary text-secondary-foreground [a]:hover:bg-secondary/80",
        destructive:
          "bg-destructive/10 text-destructive focus-visible:ring-destructive/20 dark:bg-destructive/20 dark:focus-visible:ring-destructive/40 [a]:hover:bg-destructive/20",
        outline:
          "border-border text-foreground [a]:hover:bg-muted [a]:hover:text-muted-foreground",
        ghost:
          "hover:bg-muted hover:text-muted-foreground dark:hover:bg-muted/50",
        link: "text-primary underline-offset-4 hover:underline",
      },
    },
    defaultVariants: {
      variant: "default",
    },
  }
)

function Badge({
  className,
  variant = "default",
  render,
  ...props
}: useRender.ComponentProps<"span"> & VariantProps<typeof badgeVariants>) {
  return useRender({
    defaultTagName: "span",
    props: mergeProps<"span">(
      {
        className: cn(badgeVariants({ variant }), className),
      },
      props
    ),
    render,
    state: {
      slot: "badge",
      variant,
    },
  })
}

export { Badge, badgeVariants }
```

---

# Button

A button or a component that looks like a button.

Docs: https://jds-ruddy.vercel.app/docs/components/button

## Installation

```bash
npx shadcn@latest add @jds/button
```

npm dependencies: `@base-ui/react`, `class-variance-authority`, `cn`

## Example

```tsx
import { Button } from "@/components/ui/button"
import { SendIcon } from "@/lib/icons"

export default function ButtonDemo() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <Button>Default</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="outline">Outline</Button>
      <Button variant="ghost">Ghost</Button>
      <Button variant="destructive">Destructive</Button>
      <Button size="icon" aria-label="Send">
        <SendIcon />
      </Button>
    </div>
  )
}
```

## Source

### components/ui/button.tsx

```tsx
import { Button as ButtonPrimitive } from "@base-ui/react/button"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "cn"

const buttonVariants = cva(
  "group/button inline-flex shrink-0 items-center justify-center rounded-lg border border-transparent bg-clip-padding text-sm font-medium whitespace-nowrap transition-all outline-none select-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 active:not-aria-[haspopup]:translate-y-px disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/80",
        outline:
          "border-border bg-background hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:border-input dark:bg-input/30 dark:hover:bg-input/50",
        secondary:
          "bg-secondary text-secondary-foreground hover:bg-[color-mix(in_oklch,var(--secondary),var(--foreground)_5%)] aria-expanded:bg-secondary aria-expanded:text-secondary-foreground",
        ghost:
          "hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:hover:bg-muted/50",
        destructive:
          "bg-destructive/10 text-destructive hover:bg-destructive/20 focus-visible:border-destructive/40 focus-visible:ring-destructive/20 dark:bg-destructive/20 dark:hover:bg-destructive/30 dark:focus-visible:ring-destructive/40",
        link: "text-primary underline-offset-4 hover:underline",
      },
      size: {
        default:
          "h-8 gap-1.5 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
        xs: "h-6 gap-1 rounded-[min(var(--radius-md),10px)] px-2 text-xs in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3",
        sm: "h-7 gap-1 rounded-[min(var(--radius-md),12px)] px-2.5 text-[0.8rem] in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3.5",
        lg: "h-9 gap-1.5 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
        icon: "size-8",
        "icon-xs":
          "size-6 rounded-[min(var(--radius-md),10px)] in-data-[slot=button-group]:rounded-lg [&_svg:not([class*='size-'])]:size-3",
        "icon-sm":
          "size-7 rounded-[min(var(--radius-md),12px)] in-data-[slot=button-group]:rounded-lg",
        "icon-lg": "size-9",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
)

function Button({
  className,
  variant = "default",
  size = "default",
  ...props
}: ButtonPrimitive.Props & VariantProps<typeof buttonVariants>) {
  return (
    <ButtonPrimitive
      data-slot="button"
      className={cn(buttonVariants({ variant, size, className }))}
      {...props}
    />
  )
}

export { Button, buttonVariants }
```

---

# Card

A container for grouped content.

Docs: https://jds-ruddy.vercel.app/docs/components/card

## Installation

```bash
npx shadcn@latest add @jds/card
```

npm dependencies: `cn`

## Example

```tsx
import { Button } from "@/components/ui/button"
import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "@/components/ui/card"

export default function CardDemo() {
  return (
    <Card className="w-full max-w-sm">
      <CardHeader>
        <CardTitle>Support agent</CardTitle>
        <CardDescription>Handles refunds and order questions.</CardDescription>
      </CardHeader>
      <CardContent>
        <p className="text-sm text-muted-foreground">Resolved 1,284 conversations this week.</p>
      </CardContent>
      <CardFooter>
        <Button variant="outline" size="sm">
          Open
        </Button>
      </CardFooter>
    </Card>
  )
}
```

## Source

### components/ui/card.tsx

```tsx
import * as React from "react"
import { cn } from "cn"

function Card({
  className,
  size = "default",
  ...props
}: React.ComponentProps<"div"> & { size?: "default" | "sm" }) {
  return (
    <div
      data-slot="card"
      data-size={size}
      className={cn(
        "group/card flex flex-col gap-(--card-spacing) overflow-hidden rounded-xl bg-card py-(--card-spacing) text-sm text-card-foreground ring-1 ring-foreground/10 [--card-spacing:--spacing(4)] has-data-[slot=card-footer]:pb-0 has-[>img:first-child]:pt-0 data-[size=sm]:[--card-spacing:--spacing(3)] data-[size=sm]:has-data-[slot=card-footer]:pb-0 *:[img:first-child]:rounded-t-xl *:[img:last-child]:rounded-b-xl",
        className
      )}
      {...props}
    />
  )
}

function CardHeader({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="card-header"
      className={cn(
        "group/card-header @container/card-header grid auto-rows-min items-start gap-1 rounded-t-xl px-(--card-spacing) has-data-[slot=card-action]:grid-cols-[1fr_auto] has-data-[slot=card-description]:grid-rows-[auto_auto] [.border-b]:pb-(--card-spacing)",
        className
      )}
      {...props}
    />
  )
}

function CardTitle({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="card-title"
      className={cn(
        "font-heading text-base leading-snug font-medium group-data-[size=sm]/card:text-sm",
        className
      )}
      {...props}
    />
  )
}

function CardDescription({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="card-description"
      className={cn("text-sm text-muted-foreground", className)}
      {...props}
    />
  )
}

function CardAction({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="card-action"
      className={cn(
        "col-start-2 row-span-2 row-start-1 self-start justify-self-end",
        className
      )}
      {...props}
    />
  )
}

function CardContent({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="card-content"
      className={cn("px-(--card-spacing)", className)}
      {...props}
    />
  )
}

function CardFooter({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="card-footer"
      className={cn(
        "flex items-center rounded-b-xl border-t bg-muted/50 p-(--card-spacing)",
        className
      )}
      {...props}
    />
  )
}

export {
  Card,
  CardHeader,
  CardFooter,
  CardTitle,
  CardAction,
  CardDescription,
  CardContent,
}
```

---

# Collapsible

Shows and hides a panel.

Docs: https://jds-ruddy.vercel.app/docs/components/collapsible

## Installation

```bash
npx shadcn@latest add @jds/collapsible
```

npm dependencies: `@base-ui/react`

## Example

```tsx
import { Button } from "@/components/ui/button"
import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@/components/ui/collapsible"
import { ChevronDownIcon } from "@/lib/icons"

export default function CollapsibleDemo() {
  return (
    <Collapsible className="flex w-full max-w-xs flex-col items-start">
      <CollapsibleTrigger render={<Button variant="outline" size="sm" />}>
        Show details
        <ChevronDownIcon />
      </CollapsibleTrigger>
      <CollapsibleContent>
        <div className="mt-2 rounded-lg border p-3 text-sm text-muted-foreground">
          Model: claude-sonnet-5-5. Temperature 0.2. 3 tools enabled.
        </div>
      </CollapsibleContent>
    </Collapsible>
  )
}
```

## Source

### components/ui/collapsible.tsx

```tsx
"use client"

import { Collapsible as CollapsiblePrimitive } from "@base-ui/react/collapsible"

function Collapsible({ ...props }: CollapsiblePrimitive.Root.Props) {
  return <CollapsiblePrimitive.Root data-slot="collapsible" {...props} />
}

function CollapsibleTrigger({ ...props }: CollapsiblePrimitive.Trigger.Props) {
  return (
    <CollapsiblePrimitive.Trigger data-slot="collapsible-trigger" {...props} />
  )
}

function CollapsibleContent({ ...props }: CollapsiblePrimitive.Panel.Props) {
  return (
    <CollapsiblePrimitive.Panel data-slot="collapsible-content" {...props} />
  )
}

export { Collapsible, CollapsibleTrigger, CollapsibleContent }
```

---

# Dialog

A modal window over the page.

Docs: https://jds-ruddy.vercel.app/docs/components/dialog

## Installation

```bash
npx shadcn@latest add @jds/dialog
```

npm dependencies: `@base-ui/react`, `cn`

Also installs: `@jds/button`, `@jds/utils`

## Example

```tsx
import { Button } from "@/components/ui/button"
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog"

export default function DialogDemo() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline" />}>Reset agent memory</DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Reset memory?</DialogTitle>
          <DialogDescription>The agent forgets preferences it learned from past conversations.</DialogDescription>
        </DialogHeader>
        <DialogFooter>
          <DialogClose render={<Button variant="ghost" />}>Cancel</DialogClose>
          <DialogClose render={<Button variant="destructive" />}>Reset</DialogClose>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}
```

## Source

### components/ui/dialog.tsx

```tsx
"use client"

import * as React from "react"
import { Dialog as DialogPrimitive } from "@base-ui/react/dialog"
import { cn } from "cn"

import { Button } from "@/components/ui/button"
import { CloseIcon as XIcon } from "@/lib/icons"

function Dialog({ ...props }: DialogPrimitive.Root.Props) {
  return <DialogPrimitive.Root data-slot="dialog" {...props} />
}

function DialogTrigger({ ...props }: DialogPrimitive.Trigger.Props) {
  return <DialogPrimitive.Trigger data-slot="dialog-trigger" {...props} />
}

function DialogPortal({ ...props }: DialogPrimitive.Portal.Props) {
  return <DialogPrimitive.Portal data-slot="dialog-portal" {...props} />
}

function DialogClose({ ...props }: DialogPrimitive.Close.Props) {
  return <DialogPrimitive.Close data-slot="dialog-close" {...props} />
}

function DialogOverlay({
  className,
  ...props
}: DialogPrimitive.Backdrop.Props) {
  return (
    <DialogPrimitive.Backdrop
      data-slot="dialog-overlay"
      className={cn(
        "fixed inset-0 isolate z-50 bg-black/10 duration-100 supports-backdrop-filter:backdrop-blur-xs data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0",
        className
      )}
      {...props}
    />
  )
}

function DialogContent({
  className,
  children,
  showCloseButton = true,
  ...props
}: DialogPrimitive.Popup.Props & {
  showCloseButton?: boolean
}) {
  return (
    <DialogPortal>
      <DialogOverlay />
      <DialogPrimitive.Popup
        data-slot="dialog-content"
        className={cn(
          "fixed top-1/2 left-1/2 z-50 grid w-full max-w-[calc(100%-2rem)] -translate-x-1/2 -translate-y-1/2 gap-4 rounded-xl bg-popover p-4 text-sm text-popover-foreground ring-1 ring-foreground/10 duration-100 outline-none sm:max-w-sm data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
          className
        )}
        {...props}
      >
        {children}
        {showCloseButton && (
          <DialogPrimitive.Close
            data-slot="dialog-close"
            render={
              <Button
                variant="ghost"
                className="absolute top-2 right-2"
                size="icon-sm"
              />
            }
          >
            <XIcon
            />
            <span className="sr-only">Close</span>
          </DialogPrimitive.Close>
        )}
      </DialogPrimitive.Popup>
    </DialogPortal>
  )
}

function DialogHeader({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="dialog-header"
      className={cn("flex flex-col gap-2", className)}
      {...props}
    />
  )
}

function DialogFooter({
  className,
  showCloseButton = false,
  children,
  ...props
}: React.ComponentProps<"div"> & {
  showCloseButton?: boolean
}) {
  return (
    <div
      data-slot="dialog-footer"
      className={cn(
        "-mx-4 -mb-4 flex flex-col-reverse gap-2 rounded-b-xl border-t bg-muted/50 p-4 sm:flex-row sm:justify-end",
        className
      )}
      {...props}
    >
      {children}
      {showCloseButton && (
        <DialogPrimitive.Close render={<Button variant="outline" />}>
          Close
        </DialogPrimitive.Close>
      )}
    </div>
  )
}

function DialogTitle({ className, ...props }: DialogPrimitive.Title.Props) {
  return (
    <DialogPrimitive.Title
      data-slot="dialog-title"
      className={cn(
        "font-heading text-base leading-none font-medium",
        className
      )}
      {...props}
    />
  )
}

function DialogDescription({
  className,
  ...props
}: DialogPrimitive.Description.Props) {
  return (
    <DialogPrimitive.Description
      data-slot="dialog-description"
      className={cn(
        "text-sm text-muted-foreground *:[a]:underline *:[a]:underline-offset-3 *:[a]:hover:text-foreground",
        className
      )}
      {...props}
    />
  )
}

export {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogOverlay,
  DialogPortal,
  DialogTitle,
  DialogTrigger,
}
```

---

# Input

A single-line text field.

Docs: https://jds-ruddy.vercel.app/docs/components/input

## Installation

```bash
npx shadcn@latest add @jds/input
```

npm dependencies: `@base-ui/react`, `cn`

## Example

```tsx
import { Input } from "@/components/ui/input"

export default function InputDemo() {
  return <Input placeholder="Agent name" className="max-w-xs" />
}
```

## Source

### components/ui/input.tsx

```tsx
import * as React from "react"
import { Input as InputPrimitive } from "@base-ui/react/input"
import { cn } from "cn"

function Input({ className, type, ...props }: React.ComponentProps<"input">) {
  return (
    <InputPrimitive
      type={type}
      data-slot="input"
      className={cn(
        "h-8 w-full min-w-0 rounded-lg border border-input bg-transparent px-2.5 py-1 text-base transition-colors outline-none file:inline-flex file:h-6 file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:pointer-events-none disabled:cursor-not-allowed disabled:bg-input/50 disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 md:text-sm dark:bg-input/30 dark:disabled:bg-input/80 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40",
        className
      )}
      {...props}
    />
  )
}

export { Input }
```

---

# Kbd

A keyboard key or shortcut.

Docs: https://jds-ruddy.vercel.app/docs/components/kbd

## Installation

```bash
npx shadcn@latest add @jds/kbd
```

npm dependencies: `cn`

## Example

```tsx
import { Kbd, KbdGroup } from "@/components/ui/kbd"

export default function KbdDemo() {
  return (
    <div className="flex items-center gap-4 text-sm text-muted-foreground">
      <KbdGroup>
        <Kbd>⌘</Kbd>
        <Kbd>K</Kbd>
      </KbdGroup>
      <span>
        Hold <Kbd>Space</Kbd> to talk
      </span>
    </div>
  )
}
```

## Source

### components/ui/kbd.tsx

```tsx
import { cn } from "cn"

function Kbd({ className, ...props }: React.ComponentProps<"kbd">) {
  return (
    <kbd
      data-slot="kbd"
      className={cn(
        "pointer-events-none inline-flex h-5 w-fit min-w-5 items-center justify-center gap-1 rounded-sm bg-muted px-1 font-sans text-xs font-medium text-muted-foreground select-none in-data-[slot=tooltip-content]:bg-background/20 in-data-[slot=tooltip-content]:text-background dark:in-data-[slot=tooltip-content]:bg-background/10 [&_svg:not([class*='size-'])]:size-3",
        className
      )}
      {...props}
    />
  )
}

function KbdGroup({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <kbd
      data-slot="kbd-group"
      className={cn("inline-flex items-center gap-1", className)}
      {...props}
    />
  )
}

export { Kbd, KbdGroup }
```

---

# Menu

A list of actions in a dropdown.

Docs: https://jds-ruddy.vercel.app/docs/components/dropdown-menu

## Installation

```bash
npx shadcn@latest add @jds/dropdown-menu
```

npm dependencies: `@base-ui/react`, `cn`

Also installs: `@jds/utils`

## Example

```tsx
import { Button } from "@/components/ui/button"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"

export default function DropdownMenuDemo() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>Conversation</DropdownMenuTrigger>
      <DropdownMenuContent className="w-48">
        <DropdownMenuItem>
          Rename <DropdownMenuShortcut>R</DropdownMenuShortcut>
        </DropdownMenuItem>
        <DropdownMenuItem>
          Share <DropdownMenuShortcut>S</DropdownMenuShortcut>
        </DropdownMenuItem>
        <DropdownMenuSeparator />
        <DropdownMenuItem variant="destructive">Delete</DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

## Source

### components/ui/dropdown-menu.tsx

```tsx
"use client"

import * as React from "react"
import { Menu as MenuPrimitive } from "@base-ui/react/menu"
import { cn } from "cn"
import { ChevronRightIcon, CheckIcon } from "@/lib/icons"

function DropdownMenu({ ...props }: MenuPrimitive.Root.Props) {
  return <MenuPrimitive.Root data-slot="dropdown-menu" {...props} />
}

function DropdownMenuPortal({ ...props }: MenuPrimitive.Portal.Props) {
  return <MenuPrimitive.Portal data-slot="dropdown-menu-portal" {...props} />
}

function DropdownMenuTrigger({ ...props }: MenuPrimitive.Trigger.Props) {
  return <MenuPrimitive.Trigger data-slot="dropdown-menu-trigger" {...props} />
}

function DropdownMenuContent({
  align = "start",
  alignOffset = 0,
  side = "bottom",
  sideOffset = 4,
  className,
  ...props
}: MenuPrimitive.Popup.Props &
  Pick<
    MenuPrimitive.Positioner.Props,
    "align" | "alignOffset" | "side" | "sideOffset"
  >) {
  return (
    <MenuPrimitive.Portal>
      <MenuPrimitive.Positioner
        className="isolate z-50 outline-none"
        align={align}
        alignOffset={alignOffset}
        side={side}
        sideOffset={sideOffset}
      >
        <MenuPrimitive.Popup
          data-slot="dropdown-menu-content"
          className={cn("z-50 max-h-(--available-height) w-(--anchor-width) min-w-32 origin-(--transform-origin) overflow-x-hidden overflow-y-auto rounded-lg bg-popover p-1 text-popover-foreground shadow-md ring-1 ring-foreground/10 duration-100 outline-none data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:overflow-hidden data-closed:fade-out-0 data-closed:zoom-out-95", className )}
          {...props}
        />
      </MenuPrimitive.Positioner>
    </MenuPrimitive.Portal>
  )
}

function DropdownMenuGroup({ ...props }: MenuPrimitive.Group.Props) {
  return <MenuPrimitive.Group data-slot="dropdown-menu-group" {...props} />
}

function DropdownMenuLabel({
  className,
  inset,
  ...props
}: MenuPrimitive.GroupLabel.Props & {
  inset?: boolean
}) {
  return (
    <MenuPrimitive.GroupLabel
      data-slot="dropdown-menu-label"
      data-inset={inset}
      className={cn(
        "px-1.5 py-1 text-xs font-medium text-muted-foreground data-inset:pl-7",
        className
      )}
      {...props}
    />
  )
}

function DropdownMenuItem({
  className,
  inset,
  variant = "default",
  ...props
}: MenuPrimitive.Item.Props & {
  inset?: boolean
  variant?: "default" | "destructive"
}) {
  return (
    <MenuPrimitive.Item
      data-slot="dropdown-menu-item"
      data-inset={inset}
      data-variant={variant}
      className={cn(
        "group/dropdown-menu-item relative flex cursor-default items-center gap-1.5 rounded-md px-1.5 py-1 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-inset:pl-7 data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 data-[variant=destructive]:focus:text-destructive dark:data-[variant=destructive]:focus:bg-destructive/20 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 data-[variant=destructive]:*:[svg]:text-destructive",
        className
      )}
      {...props}
    />
  )
}

function DropdownMenuSub({ ...props }: MenuPrimitive.SubmenuRoot.Props) {
  return <MenuPrimitive.SubmenuRoot data-slot="dropdown-menu-sub" {...props} />
}

function DropdownMenuSubTrigger({
  className,
  inset,
  children,
  ...props
}: MenuPrimitive.SubmenuTrigger.Props & {
  inset?: boolean
}) {
  return (
    <MenuPrimitive.SubmenuTrigger
      data-slot="dropdown-menu-sub-trigger"
      data-inset={inset}
      className={cn(
        "flex cursor-default items-center gap-1.5 rounded-md px-1.5 py-1 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-inset:pl-7 data-popup-open:bg-accent data-popup-open:text-accent-foreground data-open:bg-accent data-open:text-accent-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
        className
      )}
      {...props}
    >
      {children}
      <ChevronRightIcon className="ml-auto" />
    </MenuPrimitive.SubmenuTrigger>
  )
}

function DropdownMenuSubContent({
  align = "start",
  alignOffset = -3,
  side = "right",
  sideOffset = 0,
  className,
  ...props
}: React.ComponentProps<typeof DropdownMenuContent>) {
  return (
    <DropdownMenuContent
      data-slot="dropdown-menu-sub-content"
      className={cn("w-auto min-w-[96px] rounded-lg bg-popover p-1 text-popover-foreground shadow-lg ring-1 ring-foreground/10 duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95", className )}
      align={align}
      alignOffset={alignOffset}
      side={side}
      sideOffset={sideOffset}
      {...props}
    />
  )
}

function DropdownMenuCheckboxItem({
  className,
  children,
  checked,
  inset,
  ...props
}: MenuPrimitive.CheckboxItem.Props & {
  inset?: boolean
}) {
  return (
    <MenuPrimitive.CheckboxItem
      data-slot="dropdown-menu-checkbox-item"
      data-inset={inset}
      className={cn(
        "relative flex cursor-default items-center gap-1.5 rounded-md py-1 pr-8 pl-1.5 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground data-inset:pl-7 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
        className
      )}
      checked={checked}
      {...props}
    >
      <span
        className="pointer-events-none absolute right-2 flex items-center justify-center"
        data-slot="dropdown-menu-checkbox-item-indicator"
      >
        <MenuPrimitive.CheckboxItemIndicator>
          <CheckIcon
          />
        </MenuPrimitive.CheckboxItemIndicator>
      </span>
      {children}
    </MenuPrimitive.CheckboxItem>
  )
}

function DropdownMenuRadioGroup({ ...props }: MenuPrimitive.RadioGroup.Props) {
  return (
    <MenuPrimitive.RadioGroup
      data-slot="dropdown-menu-radio-group"
      {...props}
    />
  )
}

function DropdownMenuRadioItem({
  className,
  children,
  inset,
  ...props
}: MenuPrimitive.RadioItem.Props & {
  inset?: boolean
}) {
  return (
    <MenuPrimitive.RadioItem
      data-slot="dropdown-menu-radio-item"
      data-inset={inset}
      className={cn(
        "relative flex cursor-default items-center gap-1.5 rounded-md py-1 pr-8 pl-1.5 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground data-inset:pl-7 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
        className
      )}
      {...props}
    >
      <span
        className="pointer-events-none absolute right-2 flex items-center justify-center"
        data-slot="dropdown-menu-radio-item-indicator"
      >
        <MenuPrimitive.RadioItemIndicator>
          <CheckIcon
          />
        </MenuPrimitive.RadioItemIndicator>
      </span>
      {children}
    </MenuPrimitive.RadioItem>
  )
}

function DropdownMenuSeparator({
  className,
  ...props
}: MenuPrimitive.Separator.Props) {
  return (
    <MenuPrimitive.Separator
      data-slot="dropdown-menu-separator"
      className={cn("-mx-1 my-1 h-px bg-border", className)}
      {...props}
    />
  )
}

function DropdownMenuShortcut({
  className,
  ...props
}: React.ComponentProps<"span">) {
  return (
    <span
      data-slot="dropdown-menu-shortcut"
      className={cn(
        "ml-auto text-xs tracking-widest text-muted-foreground group-focus/dropdown-menu-item:text-accent-foreground",
        className
      )}
      {...props}
    />
  )
}

export {
  DropdownMenu,
  DropdownMenuPortal,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuLabel,
  DropdownMenuItem,
  DropdownMenuCheckboxItem,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuSub,
  DropdownMenuSubTrigger,
  DropdownMenuSubContent,
}
```

---

# Popover

A floating panel anchored to a trigger.

Docs: https://jds-ruddy.vercel.app/docs/components/popover

## Installation

```bash
npx shadcn@latest add @jds/popover
```

npm dependencies: `@base-ui/react`, `cn`

## Example

```tsx
import { Button } from "@/components/ui/button"
import {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/ui/popover"

export default function PopoverDemo() {
  return (
    <Popover>
      <PopoverTrigger render={<Button variant="outline" />}>Context usage</PopoverTrigger>
      <PopoverContent>
        <PopoverHeader>
          <PopoverTitle>42k of 200k tokens</PopoverTitle>
          <PopoverDescription>Older messages are summarized after 150k.</PopoverDescription>
        </PopoverHeader>
      </PopoverContent>
    </Popover>
  )
}
```

## Source

### components/ui/popover.tsx

```tsx
"use client"

import * as React from "react"
import { Popover as PopoverPrimitive } from "@base-ui/react/popover"
import { cn } from "cn"

function Popover({ ...props }: PopoverPrimitive.Root.Props) {
  return <PopoverPrimitive.Root data-slot="popover" {...props} />
}

function PopoverTrigger({ ...props }: PopoverPrimitive.Trigger.Props) {
  return <PopoverPrimitive.Trigger data-slot="popover-trigger" {...props} />
}

function PopoverContent({
  className,
  align = "center",
  alignOffset = 0,
  side = "bottom",
  sideOffset = 4,
  ...props
}: PopoverPrimitive.Popup.Props &
  Pick<
    PopoverPrimitive.Positioner.Props,
    "align" | "alignOffset" | "side" | "sideOffset"
  >) {
  return (
    <PopoverPrimitive.Portal>
      <PopoverPrimitive.Positioner
        align={align}
        alignOffset={alignOffset}
        side={side}
        sideOffset={sideOffset}
        className="isolate z-50"
      >
        <PopoverPrimitive.Popup
          data-slot="popover-content"
          className={cn(
            "z-50 flex w-72 origin-(--transform-origin) flex-col gap-2.5 rounded-lg bg-popover p-2.5 text-sm text-popover-foreground shadow-md ring-1 ring-foreground/10 outline-hidden duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
            className
          )}
          {...props}
        />
      </PopoverPrimitive.Positioner>
    </PopoverPrimitive.Portal>
  )
}

function PopoverHeader({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="popover-header"
      className={cn("flex flex-col gap-0.5 text-sm", className)}
      {...props}
    />
  )
}

function PopoverTitle({ className, ...props }: PopoverPrimitive.Title.Props) {
  return (
    <PopoverPrimitive.Title
      data-slot="popover-title"
      className={cn("font-medium", className)}
      {...props}
    />
  )
}

function PopoverDescription({
  className,
  ...props
}: PopoverPrimitive.Description.Props) {
  return (
    <PopoverPrimitive.Description
      data-slot="popover-description"
      className={cn("text-muted-foreground", className)}
      {...props}
    />
  )
}

export {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
}
```

---

# Scroll Area

A scroll container with styled scrollbars.

Docs: https://jds-ruddy.vercel.app/docs/components/scroll-area

## Installation

```bash
npx shadcn@latest add @jds/scroll-area
```

npm dependencies: `@base-ui/react`, `cn`

## Example

```tsx
import { ScrollArea } from "@/components/ui/scroll-area"
import { Separator } from "@/components/ui/separator"

const runs = Array.from({ length: 30 }, (_, i) => `Run #${1200 - i}`)

export default function ScrollAreaDemo() {
  return (
    <div className="overflow-hidden rounded-lg border">
      <ScrollArea className="h-56 w-48">
        <div className="p-3 text-sm">
          {runs.map((run) => (
            <div key={run}>
              <div className="py-1.5">{run}</div>
              <Separator />
            </div>
          ))}
        </div>
      </ScrollArea>
    </div>
  )
}
```

## Source

### components/ui/scroll-area.tsx

```tsx
"use client"

import * as React from "react"
import { ScrollArea as ScrollAreaPrimitive } from "@base-ui/react/scroll-area"
import { cn } from "cn"

function ScrollArea({
  className,
  children,
  ...props
}: ScrollAreaPrimitive.Root.Props) {
  return (
    <ScrollAreaPrimitive.Root
      data-slot="scroll-area"
      className={cn("relative", className)}
      {...props}
    >
      <ScrollAreaPrimitive.Viewport
        data-slot="scroll-area-viewport"
        className="size-full rounded-[inherit] transition-[color,box-shadow] outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50 focus-visible:outline-1"
      >
        {children}
      </ScrollAreaPrimitive.Viewport>
      <ScrollBar />
      <ScrollAreaPrimitive.Corner />
    </ScrollAreaPrimitive.Root>
  )
}

function ScrollBar({
  className,
  orientation = "vertical",
  ...props
}: ScrollAreaPrimitive.Scrollbar.Props) {
  return (
    <ScrollAreaPrimitive.Scrollbar
      data-slot="scroll-area-scrollbar"
      data-orientation={orientation}
      orientation={orientation}
      className={cn(
        "flex touch-none p-px transition-colors select-none data-horizontal:h-2.5 data-horizontal:flex-col data-horizontal:border-t data-horizontal:border-t-transparent data-vertical:h-full data-vertical:w-2.5 data-vertical:border-l data-vertical:border-l-transparent",
        className
      )}
      {...props}
    >
      <ScrollAreaPrimitive.Thumb
        data-slot="scroll-area-thumb"
        className="relative flex-1 rounded-full bg-border"
      />
    </ScrollAreaPrimitive.Scrollbar>
  )
}

export { ScrollArea, ScrollBar }
```

---

# Select

Pick one value from a list.

Docs: https://jds-ruddy.vercel.app/docs/components/select

## Installation

```bash
npx shadcn@latest add @jds/select
```

npm dependencies: `@base-ui/react`, `cn`

Also installs: `@jds/utils`

## Example

```tsx
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select"

const models = [
  { value: "opus", label: "Claude Opus 5.5" },
  { value: "sonnet", label: "Claude Sonnet 5.5" },
  { value: "haiku", label: "Claude Haiku 4.5" },
]

export default function SelectDemo() {
  return (
    <Select items={models} defaultValue="sonnet">
      <SelectTrigger className="w-52">
        <SelectValue />
      </SelectTrigger>
      <SelectContent>
        {models.map((m) => (
          <SelectItem key={m.value} value={m.value}>
            {m.label}
          </SelectItem>
        ))}
      </SelectContent>
    </Select>
  )
}
```

## Source

### components/ui/select.tsx

```tsx
"use client"

import * as React from "react"
import { Select as SelectPrimitive } from "@base-ui/react/select"
import { cn } from "cn"
import { ChevronDownIcon, CheckIcon, ChevronUpIcon } from "@/lib/icons"

const Select = SelectPrimitive.Root

function SelectGroup({ className, ...props }: SelectPrimitive.Group.Props) {
  return (
    <SelectPrimitive.Group
      data-slot="select-group"
      className={cn("scroll-my-1 p-1", className)}
      {...props}
    />
  )
}

function SelectValue({ className, ...props }: SelectPrimitive.Value.Props) {
  return (
    <SelectPrimitive.Value
      data-slot="select-value"
      className={cn("flex flex-1 text-left", className)}
      {...props}
    />
  )
}

function SelectTrigger({
  className,
  size = "default",
  children,
  ...props
}: SelectPrimitive.Trigger.Props & {
  size?: "sm" | "default"
}) {
  return (
    <SelectPrimitive.Trigger
      data-slot="select-trigger"
      data-size={size}
      className={cn(
        "flex w-fit items-center justify-between gap-1.5 rounded-lg border border-input bg-transparent py-2 pr-2 pl-2.5 text-sm whitespace-nowrap transition-colors outline-none select-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 data-placeholder:text-muted-foreground data-[size=default]:h-8 data-[size=sm]:h-7 data-[size=sm]:rounded-[min(var(--radius-md),10px)] *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-1.5 dark:bg-input/30 dark:hover:bg-input/50 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
        className
      )}
      {...props}
    >
      {children}
      <SelectPrimitive.Icon
        render={
          <ChevronDownIcon className="pointer-events-none size-4 text-muted-foreground" />
        }
      />
    </SelectPrimitive.Trigger>
  )
}

function SelectContent({
  className,
  children,
  side = "bottom",
  sideOffset = 4,
  align = "center",
  alignOffset = 0,
  alignItemWithTrigger = true,
  ...props
}: SelectPrimitive.Popup.Props &
  Pick<
    SelectPrimitive.Positioner.Props,
    "align" | "alignOffset" | "side" | "sideOffset" | "alignItemWithTrigger"
  >) {
  return (
    <SelectPrimitive.Portal>
      <SelectPrimitive.Positioner
        side={side}
        sideOffset={sideOffset}
        align={align}
        alignOffset={alignOffset}
        alignItemWithTrigger={alignItemWithTrigger}
        className="isolate z-50"
      >
        <SelectPrimitive.Popup
          data-slot="select-content"
          data-align-trigger={alignItemWithTrigger}
          className={cn("relative isolate z-50 max-h-(--available-height) w-(--anchor-width) min-w-36 origin-(--transform-origin) overflow-x-hidden overflow-y-auto rounded-lg bg-popover text-popover-foreground shadow-md ring-1 ring-foreground/10 duration-100 data-[align-trigger=true]:animate-none data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95", className )}
          {...props}
        >
          <SelectScrollUpButton />
          <SelectPrimitive.List>{children}</SelectPrimitive.List>
          <SelectScrollDownButton />
        </SelectPrimitive.Popup>
      </SelectPrimitive.Positioner>
    </SelectPrimitive.Portal>
  )
}

function SelectLabel({
  className,
  ...props
}: SelectPrimitive.GroupLabel.Props) {
  return (
    <SelectPrimitive.GroupLabel
      data-slot="select-label"
      className={cn("px-1.5 py-1 text-xs text-muted-foreground", className)}
      {...props}
    />
  )
}

function SelectItem({
  className,
  children,
  ...props
}: SelectPrimitive.Item.Props) {
  return (
    <SelectPrimitive.Item
      data-slot="select-item"
      className={cn(
        "relative flex w-full cursor-default items-center gap-1.5 rounded-md py-1 pr-8 pl-1.5 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2",
        className
      )}
      {...props}
    >
      <SelectPrimitive.ItemText className="flex flex-1 shrink-0 gap-2 whitespace-nowrap">
        {children}
      </SelectPrimitive.ItemText>
      <SelectPrimitive.ItemIndicator
        render={
          <span className="pointer-events-none absolute right-2 flex size-4 items-center justify-center" />
        }
      >
        <CheckIcon className="pointer-events-none" />
      </SelectPrimitive.ItemIndicator>
    </SelectPrimitive.Item>
  )
}

function SelectSeparator({
  className,
  ...props
}: SelectPrimitive.Separator.Props) {
  return (
    <SelectPrimitive.Separator
      data-slot="select-separator"
      className={cn("pointer-events-none -mx-1 my-1 h-px bg-border", className)}
      {...props}
    />
  )
}

function SelectScrollUpButton({
  className,
  ...props
}: React.ComponentProps<typeof SelectPrimitive.ScrollUpArrow>) {
  return (
    <SelectPrimitive.ScrollUpArrow
      data-slot="select-scroll-up-button"
      className={cn(
        "top-0 z-10 flex w-full cursor-default items-center justify-center bg-popover py-1 [&_svg:not([class*='size-'])]:size-4",
        className
      )}
      {...props}
    >
      <ChevronUpIcon
      />
    </SelectPrimitive.ScrollUpArrow>
  )
}

function SelectScrollDownButton({
  className,
  ...props
}: React.ComponentProps<typeof SelectPrimitive.ScrollDownArrow>) {
  return (
    <SelectPrimitive.ScrollDownArrow
      data-slot="select-scroll-down-button"
      className={cn(
        "bottom-0 z-10 flex w-full cursor-default items-center justify-center bg-popover py-1 [&_svg:not([class*='size-'])]:size-4",
        className
      )}
      {...props}
    >
      <ChevronDownIcon
      />
    </SelectPrimitive.ScrollDownArrow>
  )
}

export {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectLabel,
  SelectScrollDownButton,
  SelectScrollUpButton,
  SelectSeparator,
  SelectTrigger,
  SelectValue,
}
```

---

# Separator

A visual divider.

Docs: https://jds-ruddy.vercel.app/docs/components/separator

## Installation

```bash
npx shadcn@latest add @jds/separator
```

npm dependencies: `@base-ui/react`, `cn`

## Example

```tsx
import { Separator } from "@/components/ui/separator"

export default function SeparatorDemo() {
  return (
    <div className="flex h-5 items-center gap-4 text-sm">
      <span>Chat</span>
      <Separator orientation="vertical" />
      <span>Voice</span>
      <Separator orientation="vertical" />
      <span>Tools</span>
    </div>
  )
}
```

## Source

### components/ui/separator.tsx

```tsx
"use client"

import { Separator as SeparatorPrimitive } from "@base-ui/react/separator"
import { cn } from "cn"

function Separator({
  className,
  orientation = "horizontal",
  ...props
}: SeparatorPrimitive.Props) {
  return (
    <SeparatorPrimitive
      data-slot="separator"
      orientation={orientation}
      className={cn(
        "shrink-0 bg-border data-horizontal:h-px data-horizontal:w-full data-vertical:w-px data-vertical:self-stretch",
        className
      )}
      {...props}
    />
  )
}

export { Separator }
```

---

# Sheet

A panel that slides in from an edge. Can render inside a container, non-modal.

Docs: https://jds-ruddy.vercel.app/docs/components/sheet

## Installation

```bash
npx shadcn@latest add @jds/sheet
```

npm dependencies: `@base-ui/react`, `cn`

Also installs: `@jds/button`, `@jds/utils`

## Example

```tsx
import { Button } from "@/components/ui/button"
import { Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle, SheetTrigger } from "@/components/ui/sheet"

export default function SheetDemo() {
  return (
    <Sheet>
      <SheetTrigger render={<Button variant="outline" />}>Open panel</SheetTrigger>
      <SheetContent>
        <SheetHeader>
          <SheetTitle>Agent settings</SheetTitle>
          <SheetDescription>Tools, memory and voice for this agent.</SheetDescription>
        </SheetHeader>
      </SheetContent>
    </Sheet>
  )
}
```

## Source

### components/ui/sheet.tsx

```tsx
"use client"

import * as React from "react"
import { Dialog as SheetPrimitive } from "@base-ui/react/dialog"
import { cn } from "cn"

import { Button } from "@/components/ui/button"
import { CloseIcon } from "@/lib/icons"

function Sheet({ ...props }: SheetPrimitive.Root.Props) {
  return <SheetPrimitive.Root data-slot="sheet" {...props} />
}

function SheetTrigger({ ...props }: SheetPrimitive.Trigger.Props) {
  return <SheetPrimitive.Trigger data-slot="sheet-trigger" {...props} />
}

function SheetClose({ ...props }: SheetPrimitive.Close.Props) {
  return <SheetPrimitive.Close data-slot="sheet-close" {...props} />
}

function SheetPortal({ ...props }: SheetPrimitive.Portal.Props) {
  return <SheetPrimitive.Portal data-slot="sheet-portal" {...props} />
}

function SheetOverlay({ className, ...props }: SheetPrimitive.Backdrop.Props) {
  return (
    <SheetPrimitive.Backdrop
      data-slot="sheet-overlay"
      className={cn(
        "fixed inset-0 z-50 bg-black/10 transition-opacity duration-150 data-ending-style:opacity-0 data-starting-style:opacity-0 supports-backdrop-filter:backdrop-blur-xs",
        className
      )}
      {...props}
    />
  )
}

function SheetContent({
  className,
  children,
  side = "right",
  showCloseButton = true,
  overlay = true,
  container,
  ...props
}: SheetPrimitive.Popup.Props & {
  side?: "top" | "right" | "bottom" | "left"
  showCloseButton?: boolean
  /** Dim the page behind. Turn off for a non-modal side panel. */
  overlay?: boolean
  /** Render into this element instead of document.body, e.g. to keep a panel inside an app frame. */
  container?: SheetPrimitive.Portal.Props["container"]
}) {
  return (
    <SheetPortal container={container}>
      {overlay && <SheetOverlay />}
      <SheetPrimitive.Popup
        data-slot="sheet-content"
        data-side={side}
        className={cn(
          "fixed z-50 flex flex-col gap-4 bg-popover bg-clip-padding text-sm text-popover-foreground shadow-lg transition duration-200 ease-in-out data-ending-style:opacity-0 data-starting-style:opacity-0 data-[side=bottom]:inset-x-0 data-[side=bottom]:bottom-0 data-[side=bottom]:h-auto data-[side=bottom]:border-t data-[side=bottom]:data-ending-style:translate-y-[2.5rem] data-[side=bottom]:data-starting-style:translate-y-[2.5rem] data-[side=left]:inset-y-0 data-[side=left]:left-0 data-[side=left]:h-full data-[side=left]:w-3/4 data-[side=left]:border-r data-[side=left]:data-ending-style:translate-x-[-2.5rem] data-[side=left]:data-starting-style:translate-x-[-2.5rem] data-[side=right]:inset-y-0 data-[side=right]:right-0 data-[side=right]:h-full data-[side=right]:w-3/4 data-[side=right]:border-l data-[side=right]:data-ending-style:translate-x-[2.5rem] data-[side=right]:data-starting-style:translate-x-[2.5rem] data-[side=top]:inset-x-0 data-[side=top]:top-0 data-[side=top]:h-auto data-[side=top]:border-b data-[side=top]:data-ending-style:translate-y-[-2.5rem] data-[side=top]:data-starting-style:translate-y-[-2.5rem] data-[side=left]:sm:max-w-sm data-[side=right]:sm:max-w-sm",
          className
        )}
        {...props}
      >
        {children}
        {showCloseButton && (
          <SheetPrimitive.Close
            data-slot="sheet-close"
            render={
              <Button
                variant="ghost"
                className="absolute top-3 right-3"
                size="icon-sm"
              />
            }
          >
            <CloseIcon />
            <span className="sr-only">Close</span>
          </SheetPrimitive.Close>
        )}
      </SheetPrimitive.Popup>
    </SheetPortal>
  )
}

function SheetHeader({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="sheet-header"
      className={cn("flex flex-col gap-0.5 p-4", className)}
      {...props}
    />
  )
}

function SheetFooter({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="sheet-footer"
      className={cn("mt-auto flex flex-col gap-2 p-4", className)}
      {...props}
    />
  )
}

function SheetTitle({ className, ...props }: SheetPrimitive.Title.Props) {
  return (
    <SheetPrimitive.Title
      data-slot="sheet-title"
      className={cn(
        "font-heading text-base font-medium text-foreground",
        className
      )}
      {...props}
    />
  )
}

function SheetDescription({
  className,
  ...props
}: SheetPrimitive.Description.Props) {
  return (
    <SheetPrimitive.Description
      data-slot="sheet-description"
      className={cn("text-sm text-muted-foreground", className)}
      {...props}
    />
  )
}

export {
  Sheet,
  SheetTrigger,
  SheetClose,
  SheetContent,
  SheetHeader,
  SheetFooter,
  SheetTitle,
  SheetDescription,
}
```

---

# Skeleton

A placeholder while content loads.

Docs: https://jds-ruddy.vercel.app/docs/components/skeleton

## Installation

```bash
npx shadcn@latest add @jds/skeleton
```

npm dependencies: `cn`

## Example

```tsx
import { Skeleton } from "@/components/ui/skeleton"

export default function SkeletonDemo() {
  return (
    <div className="flex w-full max-w-xs items-center gap-3">
      <div className="size-9 overflow-hidden rounded-full">
        <Skeleton className="size-full" />
      </div>
      <div className="flex-1 space-y-2">
        <Skeleton className="h-3 w-3/4" />
        <Skeleton className="h-3 w-1/2" />
      </div>
    </div>
  )
}
```

## Source

### components/ui/skeleton.tsx

```tsx
import { cn } from "cn"

function Skeleton({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="skeleton"
      className={cn("animate-pulse rounded-md bg-muted", className)}
      {...props}
    />
  )
}

export { Skeleton }
```

---

# Tabs

Switch between related views.

Docs: https://jds-ruddy.vercel.app/docs/components/tabs

## Installation

```bash
npx shadcn@latest add @jds/tabs
```

npm dependencies: `@base-ui/react`, `class-variance-authority`, `cn`

## Example

```tsx
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"

export default function TabsDemo() {
  return (
    <Tabs defaultValue="chat" className="w-full max-w-xs">
      <TabsList>
        <TabsTrigger value="chat">Chat</TabsTrigger>
        <TabsTrigger value="voice">Voice</TabsTrigger>
        <TabsTrigger value="tools">Tools</TabsTrigger>
      </TabsList>
      <TabsContent value="chat">
        <p className="pt-3 text-muted-foreground">Text conversations.</p>
      </TabsContent>
      <TabsContent value="voice">
        <p className="pt-3 text-muted-foreground">Realtime speech.</p>
      </TabsContent>
      <TabsContent value="tools">
        <p className="pt-3 text-muted-foreground">3 tools connected.</p>
      </TabsContent>
    </Tabs>
  )
}
```

## Source

### components/ui/tabs.tsx

```tsx
"use client"

import { Tabs as TabsPrimitive } from "@base-ui/react/tabs"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "cn"

function Tabs({
  className,
  orientation = "horizontal",
  ...props
}: TabsPrimitive.Root.Props) {
  return (
    <TabsPrimitive.Root
      data-slot="tabs"
      data-orientation={orientation}
      className={cn(
        "group/tabs flex gap-2 data-horizontal:flex-col",
        className
      )}
      {...props}
    />
  )
}

const tabsListVariants = cva(
  "group/tabs-list inline-flex w-fit items-center justify-center rounded-lg p-[3px] text-muted-foreground group-data-horizontal/tabs:h-8 group-data-vertical/tabs:h-fit group-data-vertical/tabs:flex-col data-[variant=line]:rounded-none",
  {
    variants: {
      variant: {
        default: "bg-muted",
        line: "gap-1 bg-transparent",
      },
    },
    defaultVariants: {
      variant: "default",
    },
  }
)

function TabsList({
  className,
  variant = "default",
  ...props
}: TabsPrimitive.List.Props & VariantProps<typeof tabsListVariants>) {
  return (
    <TabsPrimitive.List
      data-slot="tabs-list"
      data-variant={variant}
      className={cn(tabsListVariants({ variant }), className)}
      {...props}
    />
  )
}

function TabsTrigger({ className, ...props }: TabsPrimitive.Tab.Props) {
  return (
    <TabsPrimitive.Tab
      data-slot="tabs-trigger"
      className={cn(
        "relative inline-flex h-[calc(100%-1px)] flex-1 items-center justify-center gap-1.5 rounded-md border border-transparent px-1.5 py-0.5 text-sm font-medium whitespace-nowrap text-foreground/60 transition-all group-data-vertical/tabs:w-full group-data-vertical/tabs:justify-start hover:text-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 focus-visible:outline-1 focus-visible:outline-ring disabled:pointer-events-none disabled:opacity-50 has-data-[icon=inline-end]:pr-1 has-data-[icon=inline-start]:pl-1 aria-disabled:pointer-events-none aria-disabled:opacity-50 dark:text-muted-foreground dark:hover:text-foreground group-data-[variant=default]/tabs-list:data-active:shadow-sm group-data-[variant=line]/tabs-list:data-active:shadow-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
        "group-data-[variant=line]/tabs-list:bg-transparent group-data-[variant=line]/tabs-list:data-active:bg-transparent dark:group-data-[variant=line]/tabs-list:data-active:border-transparent dark:group-data-[variant=line]/tabs-list:data-active:bg-transparent",
        "data-active:bg-background data-active:text-foreground dark:data-active:border-input dark:data-active:bg-input/30 dark:data-active:text-foreground",
        "after:absolute after:bg-foreground after:opacity-0 after:transition-opacity group-data-horizontal/tabs:after:inset-x-0 group-data-horizontal/tabs:after:bottom-[-5px] group-data-horizontal/tabs:after:h-0.5 group-data-vertical/tabs:after:inset-y-0 group-data-vertical/tabs:after:-right-1 group-data-vertical/tabs:after:w-0.5 group-data-[variant=line]/tabs-list:data-active:after:opacity-100",
        className
      )}
      {...props}
    />
  )
}

function TabsContent({ className, ...props }: TabsPrimitive.Panel.Props) {
  return (
    <TabsPrimitive.Panel
      data-slot="tabs-content"
      className={cn("flex-1 text-sm outline-none", className)}
      {...props}
    />
  )
}

export { Tabs, TabsList, TabsTrigger, TabsContent, tabsListVariants }
```

---

# Textarea

A multi-line text field that grows with content.

Docs: https://jds-ruddy.vercel.app/docs/components/textarea

## Installation

```bash
npx shadcn@latest add @jds/textarea
```

npm dependencies: `cn`

## Example

```tsx
import { Textarea } from "@/components/ui/textarea"

export default function TextareaDemo() {
  return <Textarea placeholder="System prompt" className="max-w-sm" />
}
```

## Source

### components/ui/textarea.tsx

```tsx
import * as React from "react"
import { cn } from "cn"

function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
  return (
    <textarea
      data-slot="textarea"
      className={cn(
        "flex field-sizing-content min-h-16 w-full rounded-lg border border-input bg-transparent px-2.5 py-2 text-base transition-colors outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:bg-input/50 disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 md:text-sm dark:bg-input/30 dark:disabled:bg-input/80 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40",
        className
      )}
      {...props}
    />
  )
}

export { Textarea }
```

---

# Toast

Brief notifications, via Sonner.

Docs: https://jds-ruddy.vercel.app/docs/components/sonner

## Installation

```bash
npx shadcn@latest add @jds/sonner
```

npm dependencies: `next-themes`, `sonner`

Also installs: `@jds/utils`

## Example

```tsx
"use client"

import { toast } from "sonner"

import { Button } from "@/components/ui/button"

export default function SonnerDemo() {
  return (
    <Button
      variant="outline"
      onClick={() =>
        toast("Agent finished", {
          description: "Refund issued for order #4821.",
        })
      }
    >
      Show toast
    </Button>
  )
}
```

## Source

### components/ui/sonner.tsx

```tsx
"use client"

import { useTheme } from "next-themes"
import { Toaster as Sonner, type ToasterProps } from "sonner"
import { SuccessIcon as CircleCheckIcon, InfoIcon, WarningIcon as TriangleAlertIcon, ErrorIcon as OctagonXIcon, SpinnerIcon as Loader2Icon } from "@/lib/icons"

const Toaster = ({ ...props }: ToasterProps) => {
  const { theme = "system" } = useTheme()

return (
    <Sonner
      theme={theme as ToasterProps["theme"]}
      className="toaster group"
      icons={{
        success: (
          <CircleCheckIcon className="size-4" />
        ),
        info: (
          <InfoIcon className="size-4" />
        ),
        warning: (
          <TriangleAlertIcon className="size-4" />
        ),
        error: (
          <OctagonXIcon className="size-4" />
        ),
        loading: (
          <Loader2Icon className="size-4 animate-spin" />
        ),
      }}
      style={
        {
          "--normal-bg": "var(--popover)",
          "--normal-text": "var(--popover-foreground)",
          "--normal-border": "var(--border)",
          "--border-radius": "var(--radius)",
        } as React.CSSProperties
      }
      toastOptions={{
        classNames: {
          toast: "cn-toast",
        },
      }}
      {...props}
    />
  )
}

export { Toaster }
```

---

# Accordion

Stacked sections that expand one or several at a time.

Docs: https://jds-ruddy.vercel.app/docs/components/accordion

## Installation

```bash
npx shadcn@latest add @jds/accordion
```

npm dependencies: `@base-ui/react`, `cn`

Also installs: `@jds/utils`

## Example

```tsx
import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from "@/components/ui/accordion"

const faqs = [
  ["What can the agent access?", "Only the tools and files you connect. You can revoke access at any time in settings."],
  ["Does it act without asking?", "Anything irreversible, like refunds or deletions, waits for your approval first."],
  ["Where is my data stored?", "In the EU region. Conversations are kept for 30 days unless you pin them."],
]

export default function AccordionDemo() {
  return (
    <Accordion defaultValue={["0"]} className="w-full max-w-md">
      {faqs.map(([q, a], i) => (
        <AccordionItem key={q} value={String(i)}>
          <AccordionTrigger>{q}</AccordionTrigger>
          <AccordionContent>{a}</AccordionContent>
        </AccordionItem>
      ))}
    </Accordion>
  )
}
```

## Source

### components/ui/accordion.tsx

```tsx
import { Accordion as AccordionPrimitive } from "@base-ui/react/accordion"
import { cn } from "cn"
import { ChevronDownIcon, ChevronUpIcon } from "@/lib/icons"

function Accordion({ className, ...props }: AccordionPrimitive.Root.Props) {
  return (
    <AccordionPrimitive.Root
      data-slot="accordion"
      className={cn("flex w-full flex-col", className)}
      {...props}
    />
  )
}

function AccordionItem({ className, ...props }: AccordionPrimitive.Item.Props) {
  return (
    <AccordionPrimitive.Item
      data-slot="accordion-item"
      className={cn("not-last:border-b", className)}
      {...props}
    />
  )
}

function AccordionTrigger({
  className,
  children,
  ...props
}: AccordionPrimitive.Trigger.Props) {
  return (
    <AccordionPrimitive.Header className="flex">
      <AccordionPrimitive.Trigger
        data-slot="accordion-trigger"
        className={cn(
          "group/accordion-trigger relative flex flex-1 items-start justify-between rounded-lg border border-transparent py-2.5 text-left text-sm font-medium transition-all outline-none hover:underline focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 focus-visible:after:border-ring aria-disabled:pointer-events-none aria-disabled:opacity-50 **:data-[slot=accordion-trigger-icon]:ml-auto **:data-[slot=accordion-trigger-icon]:size-4 **:data-[slot=accordion-trigger-icon]:text-muted-foreground",
          className
        )}
        {...props}
      >
        {children}
        <ChevronDownIcon data-slot="accordion-trigger-icon" className="pointer-events-none shrink-0 group-aria-expanded/accordion-trigger:hidden" />
        <ChevronUpIcon data-slot="accordion-trigger-icon" className="pointer-events-none hidden shrink-0 group-aria-expanded/accordion-trigger:inline" />
      </AccordionPrimitive.Trigger>
    </AccordionPrimitive.Header>
  )
}

function AccordionContent({
  className,
  children,
  ...props
}: AccordionPrimitive.Panel.Props) {
  return (
    <AccordionPrimitive.Panel
      data-slot="accordion-content"
      className="overflow-hidden text-sm data-open:animate-accordion-down data-closed:animate-accordion-up"
      {...props}
    >
      <div
        className={cn(
          "h-(--accordion-panel-height) pt-0 pb-2.5 data-ending-style:h-0 data-starting-style:h-0 [&_a]:underline [&_a]:underline-offset-3 [&_a]:hover:text-foreground [&_p:not(:last-child)]:mb-4",
          className
        )}
      >
        {children}
      </div>
    </AccordionPrimitive.Panel>
  )
}

export { Accordion, AccordionItem, AccordionTrigger, AccordionContent }
```

---

# Alert

A callout for status or warnings, inline with content.

Docs: https://jds-ruddy.vercel.app/docs/components/alert

## Installation

```bash
npx shadcn@latest add @jds/alert
```

npm dependencies: `class-variance-authority`, `cn`

## Example

```tsx
import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert"
import { InfoIcon, WarningIcon } from "@/lib/icons"

export default function AlertDemo() {
  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <Alert>
        <InfoIcon />
        <AlertTitle>Web search is on</AlertTitle>
        <AlertDescription>Answers may include results from public websites.</AlertDescription>
      </Alert>
      <Alert variant="destructive">
        <WarningIcon />
        <AlertTitle>Tool connection lost</AlertTitle>
        <AlertDescription>Reconnect Linear to let the agent update issues.</AlertDescription>
      </Alert>
    </div>
  )
}
```

## Source

### components/ui/alert.tsx

```tsx
import * as React from "react"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "cn"

const alertVariants = cva(
  "group/alert relative grid w-full gap-0.5 rounded-lg border px-2.5 py-2 text-left text-sm has-data-[slot=alert-action]:relative has-data-[slot=alert-action]:pr-18 has-[>svg]:grid-cols-[auto_1fr] has-[>svg]:gap-x-2 *:[svg]:row-span-2 *:[svg]:translate-y-0.5 *:[svg]:text-current *:[svg:not([class*='size-'])]:size-4",
  {
    variants: {
      variant: {
        default: "bg-card text-card-foreground",
        destructive:
          "bg-card text-destructive *:data-[slot=alert-description]:text-destructive/90 *:[svg]:text-current",
      },
    },
    defaultVariants: {
      variant: "default",
    },
  }
)

function Alert({
  className,
  variant,
  ...props
}: React.ComponentProps<"div"> & VariantProps<typeof alertVariants>) {
  return (
    <div
      data-slot="alert"
      role="alert"
      className={cn(alertVariants({ variant }), className)}
      {...props}
    />
  )
}

function AlertTitle({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="alert-title"
      className={cn(
        "font-medium group-has-[>svg]/alert:col-start-2 [&_a]:underline [&_a]:underline-offset-3 [&_a]:hover:text-foreground",
        className
      )}
      {...props}
    />
  )
}

function AlertDescription({
  className,
  ...props
}: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="alert-description"
      className={cn(
        "text-sm text-balance text-muted-foreground md:text-pretty [&_a]:underline [&_a]:underline-offset-3 [&_a]:hover:text-foreground [&_p:not(:last-child)]:mb-4",
        className
      )}
      {...props}
    />
  )
}

function AlertAction({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="alert-action"
      className={cn("absolute top-2 right-2", className)}
      {...props}
    />
  )
}

export { Alert, AlertTitle, AlertDescription, AlertAction }
```

---

# Alert Dialog

A modal that interrupts to confirm a destructive action.

Docs: https://jds-ruddy.vercel.app/docs/components/alert-dialog

## Installation

```bash
npx shadcn@latest add @jds/alert-dialog
```

npm dependencies: `@base-ui/react`, `cn`

Also installs: `@jds/button`

## Example

```tsx
import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogTrigger,
} from "@/components/ui/alert-dialog"
import { Button } from "@/components/ui/button"

export default function AlertDialogDemo() {
  return (
    <AlertDialog>
      <AlertDialogTrigger render={<Button variant="outline" />}>Delete conversation</AlertDialogTrigger>
      <AlertDialogContent>
        <AlertDialogHeader>
          <AlertDialogTitle>Delete this conversation?</AlertDialogTitle>
          <AlertDialogDescription>Messages, files and artifacts in it will be removed permanently.</AlertDialogDescription>
        </AlertDialogHeader>
        <AlertDialogFooter>
          <AlertDialogCancel>Cancel</AlertDialogCancel>
          <AlertDialogAction variant="destructive">Delete</AlertDialogAction>
        </AlertDialogFooter>
      </AlertDialogContent>
    </AlertDialog>
  )
}
```

## Source

### components/ui/alert-dialog.tsx

```tsx
"use client"

import * as React from "react"
import { AlertDialog as AlertDialogPrimitive } from "@base-ui/react/alert-dialog"
import { cn } from "cn"

import { Button } from "@/components/ui/button"

function AlertDialog({ ...props }: AlertDialogPrimitive.Root.Props) {
  return <AlertDialogPrimitive.Root data-slot="alert-dialog" {...props} />
}

function AlertDialogTrigger({ ...props }: AlertDialogPrimitive.Trigger.Props) {
  return (
    <AlertDialogPrimitive.Trigger data-slot="alert-dialog-trigger" {...props} />
  )
}

function AlertDialogPortal({ ...props }: AlertDialogPrimitive.Portal.Props) {
  return (
    <AlertDialogPrimitive.Portal data-slot="alert-dialog-portal" {...props} />
  )
}

function AlertDialogOverlay({
  className,
  ...props
}: AlertDialogPrimitive.Backdrop.Props) {
  return (
    <AlertDialogPrimitive.Backdrop
      data-slot="alert-dialog-overlay"
      className={cn(
        "fixed inset-0 isolate z-50 bg-black/10 duration-100 supports-backdrop-filter:backdrop-blur-xs data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0",
        className
      )}
      {...props}
    />
  )
}

function AlertDialogContent({
  className,
  size = "default",
  ...props
}: AlertDialogPrimitive.Popup.Props & {
  size?: "default" | "sm"
}) {
  return (
    <AlertDialogPortal>
      <AlertDialogOverlay />
      <AlertDialogPrimitive.Popup
        data-slot="alert-dialog-content"
        data-size={size}
        className={cn(
          "group/alert-dialog-content fixed top-1/2 left-1/2 z-50 grid w-full -translate-x-1/2 -translate-y-1/2 gap-4 rounded-xl bg-popover p-4 text-popover-foreground ring-1 ring-foreground/10 duration-100 outline-none data-[size=default]:max-w-xs data-[size=sm]:max-w-xs data-[size=default]:sm:max-w-sm data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
          className
        )}
        {...props}
      />
    </AlertDialogPortal>
  )
}

function AlertDialogHeader({
  className,
  ...props
}: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="alert-dialog-header"
      className={cn(
        "grid grid-rows-[auto_1fr] place-items-center gap-1.5 text-center has-data-[slot=alert-dialog-media]:grid-rows-[auto_auto_1fr] has-data-[slot=alert-dialog-media]:gap-x-4 sm:group-data-[size=default]/alert-dialog-content:place-items-start sm:group-data-[size=default]/alert-dialog-content:text-left sm:group-data-[size=default]/alert-dialog-content:has-data-[slot=alert-dialog-media]:grid-rows-[auto_1fr]",
        className
      )}
      {...props}
    />
  )
}

function AlertDialogFooter({
  className,
  ...props
}: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="alert-dialog-footer"
      className={cn(
        "-mx-4 -mb-4 flex flex-col-reverse gap-2 rounded-b-xl border-t bg-muted/50 p-4 group-data-[size=sm]/alert-dialog-content:grid group-data-[size=sm]/alert-dialog-content:grid-cols-2 sm:flex-row sm:justify-end",
        className
      )}
      {...props}
    />
  )
}

function AlertDialogMedia({
  className,
  ...props
}: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="alert-dialog-media"
      className={cn(
        "mb-2 inline-flex size-10 items-center justify-center rounded-md bg-muted sm:group-data-[size=default]/alert-dialog-content:row-span-2 *:[svg:not([class*='size-'])]:size-6",
        className
      )}
      {...props}
    />
  )
}

function AlertDialogTitle({
  className,
  ...props
}: React.ComponentProps<typeof AlertDialogPrimitive.Title>) {
  return (
    <AlertDialogPrimitive.Title
      data-slot="alert-dialog-title"
      className={cn(
        "font-heading text-base font-medium sm:group-data-[size=default]/alert-dialog-content:group-has-data-[slot=alert-dialog-media]/alert-dialog-content:col-start-2",
        className
      )}
      {...props}
    />
  )
}

function AlertDialogDescription({
  className,
  ...props
}: React.ComponentProps<typeof AlertDialogPrimitive.Description>) {
  return (
    <AlertDialogPrimitive.Description
      data-slot="alert-dialog-description"
      className={cn(
        "text-sm text-balance text-muted-foreground md:text-pretty *:[a]:underline *:[a]:underline-offset-3 *:[a]:hover:text-foreground",
        className
      )}
      {...props}
    />
  )
}

function AlertDialogAction({
  className,
  ...props
}: React.ComponentProps<typeof Button>) {
  return (
    <Button
      data-slot="alert-dialog-action"
      className={cn(className)}
      {...props}
    />
  )
}

function AlertDialogCancel({
  className,
  variant = "outline",
  size = "default",
  ...props
}: AlertDialogPrimitive.Close.Props &
  Pick<React.ComponentProps<typeof Button>, "variant" | "size">) {
  return (
    <AlertDialogPrimitive.Close
      data-slot="alert-dialog-cancel"
      className={cn(className)}
      render={<Button variant={variant} size={size} />}
      {...props}
    />
  )
}

export {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogMedia,
  AlertDialogOverlay,
  AlertDialogPortal,
  AlertDialogTitle,
  AlertDialogTrigger,
}
```

---

# Breadcrumb

Where you are in a hierarchy, with links back up.

Docs: https://jds-ruddy.vercel.app/docs/components/breadcrumb

## Installation

```bash
npx shadcn@latest add @jds/breadcrumb
```

npm dependencies: `@base-ui/react`, `cn`

Also installs: `@jds/utils`

## Example

```tsx
import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from "@/components/ui/breadcrumb"

export default function BreadcrumbDemo() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="#">Agents</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink href="#">Support</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbPage>Run #1284</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}
```

## Source

### components/ui/breadcrumb.tsx

```tsx
import * as React from "react"
import { mergeProps } from "@base-ui/react/merge-props"
import { useRender } from "@base-ui/react/use-render"
import { cn } from "cn"
import { ChevronRightIcon, MoreIcon as MoreHorizontalIcon } from "@/lib/icons"

function Breadcrumb({ className, ...props }: React.ComponentProps<"nav">) {
  return (
    <nav
      aria-label="breadcrumb"
      data-slot="breadcrumb"
      className={cn(className)}
      {...props}
    />
  )
}

function BreadcrumbList({ className, ...props }: React.ComponentProps<"ol">) {
  return (
    <ol
      data-slot="breadcrumb-list"
      className={cn(
        "flex flex-wrap items-center gap-1.5 text-sm wrap-break-word text-muted-foreground",
        className
      )}
      {...props}
    />
  )
}

function BreadcrumbItem({ className, ...props }: React.ComponentProps<"li">) {
  return (
    <li
      data-slot="breadcrumb-item"
      className={cn("inline-flex items-center gap-1", className)}
      {...props}
    />
  )
}

function BreadcrumbLink({
  className,
  render,
  ...props
}: useRender.ComponentProps<"a">) {
  return useRender({
    defaultTagName: "a",
    props: mergeProps<"a">(
      {
        className: cn("transition-colors hover:text-foreground", className),
      },
      props
    ),
    render,
    state: {
      slot: "breadcrumb-link",
    },
  })
}

function BreadcrumbPage({ className, ...props }: React.ComponentProps<"span">) {
  return (
    <span
      data-slot="breadcrumb-page"
      role="link"
      aria-disabled="true"
      aria-current="page"
      className={cn("font-normal text-foreground", className)}
      {...props}
    />
  )
}

function BreadcrumbSeparator({
  children,
  className,
  ...props
}: React.ComponentProps<"li">) {
  return (
    <li
      data-slot="breadcrumb-separator"
      role="presentation"
      aria-hidden="true"
      className={cn("[&>svg]:size-3.5", className)}
      {...props}
    >
      {children ?? (
        <ChevronRightIcon />
      )}
    </li>
  )
}

function BreadcrumbEllipsis({
  className,
  ...props
}: React.ComponentProps<"span">) {
  return (
    <span
      data-slot="breadcrumb-ellipsis"
      role="presentation"
      aria-hidden="true"
      className={cn(
        "flex size-5 items-center justify-center [&>svg]:size-4",
        className
      )}
      {...props}
    >
      <MoreHorizontalIcon
      />
      <span className="sr-only">More</span>
    </span>
  )
}

export {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbPage,
  BreadcrumbSeparator,
  BreadcrumbEllipsis,
}
```

---

# Checkbox

An on/off choice, usually in a list of settings.

Docs: https://jds-ruddy.vercel.app/docs/components/checkbox

## Installation

```bash
npx shadcn@latest add @jds/checkbox
```

npm dependencies: `@base-ui/react`, `cn`

Also installs: `@jds/utils`

## Example

```tsx
import { Checkbox } from "@/components/ui/checkbox"
import { Label } from "@/components/ui/label"

export default function CheckboxDemo() {
  return (
    <div className="flex flex-col gap-3">
      <Label>
        <Checkbox defaultChecked />
        Ask before sending emails
      </Label>
      <Label>
        <Checkbox />
        Allow web search
      </Label>
    </div>
  )
}
```

## Source

### components/ui/checkbox.tsx

```tsx
"use client"

import { Checkbox as CheckboxPrimitive } from "@base-ui/react/checkbox"
import { cn } from "cn"
import { CheckIcon } from "@/lib/icons"

function Checkbox({ className, ...props }: CheckboxPrimitive.Root.Props) {
  return (
    <CheckboxPrimitive.Root
      data-slot="checkbox"
      className={cn(
        "peer relative flex size-4 shrink-0 items-center justify-center rounded-[4px] border border-input transition-colors outline-none group-has-disabled/field:opacity-50 group-has-[:focus-visible]/field-label:ring-0 group-has-[:focus-visible]/field-label:not-data-checked:border-input after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 aria-invalid:aria-checked:border-primary dark:bg-input/30 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 data-checked:border-primary data-checked:bg-primary data-checked:text-primary-foreground group-has-[:focus-visible]/field-label:data-checked:border-primary dark:data-checked:bg-primary",
        className
      )}
      {...props}
    >
      <CheckboxPrimitive.Indicator
        data-slot="checkbox-indicator"
        className="grid place-content-center text-current transition-none [&>svg]:size-3.5"
      >
        <CheckIcon
        />
      </CheckboxPrimitive.Indicator>
    </CheckboxPrimitive.Root>
  )
}

export { Checkbox }
```

---

# Combobox

A text input that filters a list of options as you type.

Docs: https://jds-ruddy.vercel.app/docs/components/combobox

## Installation

```bash
npx shadcn@latest add @jds/combobox
```

npm dependencies: `@base-ui/react`, `cn`

Also installs: `@jds/button`, `@jds/input-group`, `@jds/utils`

## Example

```tsx
"use client"

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/combobox"

const tools = ["GitHub", "Linear", "Notion", "Slack", "Stripe", "Figma", "Google Drive", "Salesforce"]

export default function ComboboxDemo() {
  return (
    <Combobox items={tools}>
      <ComboboxInput placeholder="Connect a tool…" className="w-64" />
      <ComboboxContent>
        <ComboboxEmpty>No tool found.</ComboboxEmpty>
        <ComboboxList>
          {(item: string) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}
```

## Source

### components/ui/combobox.tsx

```tsx
"use client"

import * as React from "react"
import { Combobox as ComboboxPrimitive } from "@base-ui/react"
import { cn } from "cn"

import { Button } from "@/components/ui/button"
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupInput,
} from "@/components/ui/input-group"
import { ChevronDownIcon, CloseIcon as XIcon, CheckIcon } from "@/lib/icons"

const Combobox = ComboboxPrimitive.Root

function ComboboxValue({ ...props }: ComboboxPrimitive.Value.Props) {
  return <ComboboxPrimitive.Value data-slot="combobox-value" {...props} />
}

function ComboboxTrigger({
  className,
  children,
  ...props
}: ComboboxPrimitive.Trigger.Props) {
  return (
    <ComboboxPrimitive.Trigger
      data-slot="combobox-trigger"
      className={cn("[&_svg:not([class*='size-'])]:size-4", className)}
      {...props}
    >
      {children}
      <ChevronDownIcon className="pointer-events-none size-4 text-muted-foreground" />
    </ComboboxPrimitive.Trigger>
  )
}

function ComboboxClear({ className, ...props }: ComboboxPrimitive.Clear.Props) {
  return (
    <ComboboxPrimitive.Clear
      data-slot="combobox-clear"
      render={<InputGroupButton variant="ghost" size="icon-xs" />}
      className={cn(className)}
      {...props}
    >
      <XIcon className="pointer-events-none" />
    </ComboboxPrimitive.Clear>
  )
}

function ComboboxInput({
  className,
  children,
  disabled = false,
  showTrigger = true,
  showClear = false,
  ...props
}: ComboboxPrimitive.Input.Props & {
  showTrigger?: boolean
  showClear?: boolean
}) {
  return (
    <InputGroup className={cn("w-auto", className)}>
      <ComboboxPrimitive.Input
        render={<InputGroupInput disabled={disabled} />}
        {...props}
      />
      <InputGroupAddon align="inline-end">
        {showTrigger && (
          <InputGroupButton
            size="icon-xs"
            variant="ghost"
            render={<ComboboxTrigger />}
            data-slot="input-group-button"
            className="group-has-data-[slot=combobox-clear]/input-group:hidden data-pressed:bg-transparent"
            disabled={disabled}
          />
        )}
        {showClear && <ComboboxClear disabled={disabled} />}
      </InputGroupAddon>
      {children}
    </InputGroup>
  )
}

function ComboboxContent({
  className,
  side = "bottom",
  sideOffset = 6,
  align = "start",
  alignOffset = 0,
  anchor,
  ...props
}: ComboboxPrimitive.Popup.Props &
  Pick<
    ComboboxPrimitive.Positioner.Props,
    "side" | "align" | "sideOffset" | "alignOffset" | "anchor"
  >) {
  return (
    <ComboboxPrimitive.Portal>
      <ComboboxPrimitive.Positioner
        side={side}
        sideOffset={sideOffset}
        align={align}
        alignOffset={alignOffset}
        anchor={anchor}
        className="isolate z-50"
      >
        <ComboboxPrimitive.Popup
          data-slot="combobox-content"
          data-chips={!!anchor}
          className={cn("group/combobox-content relative max-h-(--available-height) w-(--anchor-width) max-w-(--available-width) min-w-[calc(var(--anchor-width)+--spacing(7))] origin-(--transform-origin) overflow-hidden rounded-lg bg-popover text-popover-foreground shadow-md ring-1 ring-foreground/10 duration-100 data-[chips=true]:min-w-(--anchor-width) data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 *:data-[slot=input-group]:m-1 *:data-[slot=input-group]:mb-0 *:data-[slot=input-group]:h-8 *:data-[slot=input-group]:border-input/30 *:data-[slot=input-group]:bg-input/30 *:data-[slot=input-group]:shadow-none data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95", className )}
          {...props}
        />
      </ComboboxPrimitive.Positioner>
    </ComboboxPrimitive.Portal>
  )
}

function ComboboxList({ className, ...props }: ComboboxPrimitive.List.Props) {
  return (
    <ComboboxPrimitive.List
      data-slot="combobox-list"
      className={cn(
        "no-scrollbar max-h-[min(calc(--spacing(72)---spacing(9)),calc(var(--available-height)---spacing(9)))] scroll-py-1 overflow-y-auto overscroll-contain p-1 data-empty:p-0",
        className
      )}
      {...props}
    />
  )
}

function ComboboxItem({
  className,
  children,
  ...props
}: ComboboxPrimitive.Item.Props) {
  return (
    <ComboboxPrimitive.Item
      data-slot="combobox-item"
      className={cn(
        "relative flex w-full cursor-default items-center gap-2 rounded-md py-1 pr-8 pl-1.5 text-sm outline-hidden select-none data-highlighted:bg-accent data-highlighted:text-accent-foreground not-data-[variant=destructive]:data-highlighted:**:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
        className
      )}
      {...props}
    >
      {children}
      <ComboboxPrimitive.ItemIndicator
        render={
          <span className="pointer-events-none absolute right-2 flex size-4 items-center justify-center" />
        }
      >
        <CheckIcon className="pointer-events-none" />
      </ComboboxPrimitive.ItemIndicator>
    </ComboboxPrimitive.Item>
  )
}

function ComboboxGroup({ className, ...props }: ComboboxPrimitive.Group.Props) {
  return (
    <ComboboxPrimitive.Group
      data-slot="combobox-group"
      className={cn(className)}
      {...props}
    />
  )
}

function ComboboxLabel({
  className,
  ...props
}: ComboboxPrimitive.GroupLabel.Props) {
  return (
    <ComboboxPrimitive.GroupLabel
      data-slot="combobox-label"
      className={cn("px-2 py-1.5 text-xs text-muted-foreground", className)}
      {...props}
    />
  )
}

function ComboboxCollection({ ...props }: ComboboxPrimitive.Collection.Props) {
  return (
    <ComboboxPrimitive.Collection data-slot="combobox-collection" {...props} />
  )
}

function ComboboxEmpty({ className, ...props }: ComboboxPrimitive.Empty.Props) {
  return (
    <ComboboxPrimitive.Empty
      data-slot="combobox-empty"
      className={cn(
        "hidden w-full justify-center py-2 text-center text-sm text-muted-foreground group-data-empty/combobox-content:flex",
        className
      )}
      {...props}
    />
  )
}

function ComboboxSeparator({
  className,
  ...props
}: ComboboxPrimitive.Separator.Props) {
  return (
    <ComboboxPrimitive.Separator
      data-slot="combobox-separator"
      className={cn("-mx-1 my-1 h-px bg-border", className)}
      {...props}
    />
  )
}

function ComboboxChips({
  className,
  ...props
}: React.ComponentPropsWithRef<typeof ComboboxPrimitive.Chips> &
  ComboboxPrimitive.Chips.Props) {
  return (
    <ComboboxPrimitive.Chips
      data-slot="combobox-chips"
      className={cn(
        "flex min-h-8 flex-wrap items-center gap-1 rounded-lg border border-input bg-transparent bg-clip-padding px-2.5 py-1 text-sm transition-colors focus-within:border-ring focus-within:ring-3 focus-within:ring-ring/50 has-aria-invalid:border-destructive has-aria-invalid:ring-3 has-aria-invalid:ring-destructive/20 has-data-[slot=combobox-chip]:px-1 dark:bg-input/30 dark:has-aria-invalid:border-destructive/50 dark:has-aria-invalid:ring-destructive/40",
        className
      )}
      {...props}
    />
  )
}

function ComboboxChip({
  className,
  children,
  showRemove = true,
  ...props
}: ComboboxPrimitive.Chip.Props & {
  showRemove?: boolean
}) {
  return (
    <ComboboxPrimitive.Chip
      data-slot="combobox-chip"
      className={cn(
        "flex h-[calc(--spacing(5.25))] w-fit items-center justify-center gap-1 rounded-sm bg-muted px-1.5 text-xs font-medium whitespace-nowrap text-foreground has-disabled:pointer-events-none has-disabled:cursor-not-allowed has-disabled:opacity-50 has-data-[slot=combobox-chip-remove]:pr-0",
        className
      )}
      {...props}
    >
      {children}
      {showRemove && (
        <ComboboxPrimitive.ChipRemove
          render={<Button variant="ghost" size="icon-xs" />}
          className="-ml-1 opacity-50 hover:opacity-100"
          data-slot="combobox-chip-remove"
        >
          <XIcon className="pointer-events-none" />
        </ComboboxPrimitive.ChipRemove>
      )}
    </ComboboxPrimitive.Chip>
  )
}

function ComboboxChipsInput({
  className,
  ...props
}: ComboboxPrimitive.Input.Props) {
  return (
    <ComboboxPrimitive.Input
      data-slot="combobox-chip-input"
      className={cn("min-w-16 flex-1 outline-none", className)}
      {...props}
    />
  )
}

function useComboboxAnchor() {
  return React.useRef<HTMLDivElement | null>(null)
}

export {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxList,
  ComboboxItem,
  ComboboxGroup,
  ComboboxLabel,
  ComboboxCollection,
  ComboboxEmpty,
  ComboboxSeparator,
  ComboboxChips,
  ComboboxChip,
  ComboboxChipsInput,
  ComboboxTrigger,
  ComboboxValue,
  useComboboxAnchor,
}
```

---

# Command

A searchable command palette with groups and shortcuts.

Docs: https://jds-ruddy.vercel.app/docs/components/command

## Installation

```bash
npx shadcn@latest add @jds/command
```

npm dependencies: `cmdk`, `cn`

Also installs: `@jds/dialog`, `@jds/input-group`, `@jds/utils`

## Example

```tsx
import {
  Command,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
  CommandShortcut,
} from "@/components/ui/command"
import { AgentIcon, FileIcon, SettingsIcon, SparkleIcon } from "@/lib/icons"

export default function CommandDemo() {
  return (
    <div className="w-full max-w-sm overflow-hidden rounded-xl border">
      <Command>
        <CommandInput placeholder="Search or ask…" />
        <CommandList>
          <CommandEmpty>No results.</CommandEmpty>
          <CommandGroup heading="Agents">
            <CommandItem>
              <SparkleIcon />
              New conversation
              <CommandShortcut>⌘N</CommandShortcut>
            </CommandItem>
            <CommandItem>
              <AgentIcon />
              Switch agent
            </CommandItem>
          </CommandGroup>
          <CommandSeparator />
          <CommandGroup heading="Recent">
            <CommandItem>
              <FileIcon />
              Q3 pricing update
            </CommandItem>
            <CommandItem>
              <SettingsIcon />
              Agent settings
              <CommandShortcut>⌘,</CommandShortcut>
            </CommandItem>
          </CommandGroup>
        </CommandList>
      </Command>
    </div>
  )
}
```

## Source

### components/ui/command.tsx

```tsx
"use client"

import * as React from "react"
import { Command as CommandPrimitive } from "cmdk"
import { cn } from "cn"

import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
} from "@/components/ui/dialog"
import {
  InputGroup,
  InputGroupAddon,
} from "@/components/ui/input-group"
import { SearchIcon, CheckIcon } from "@/lib/icons"

function Command({
  className,
  ...props
}: React.ComponentProps<typeof CommandPrimitive>) {
  return (
    <CommandPrimitive
      data-slot="command"
      className={cn(
        "flex size-full flex-col overflow-hidden rounded-xl! bg-popover p-1 text-popover-foreground",
        className
      )}
      {...props}
    />
  )
}

function CommandDialog({
  title = "Command Palette",
  description = "Search for a command to run...",
  children,
  className,
  showCloseButton = false,
  ...props
}: Omit<React.ComponentProps<typeof Dialog>, "children"> & {
  title?: string
  description?: string
  className?: string
  showCloseButton?: boolean
  children: React.ReactNode
}) {
  return (
    <Dialog {...props}>
      <DialogHeader className="sr-only">
        <DialogTitle>{title}</DialogTitle>
        <DialogDescription>{description}</DialogDescription>
      </DialogHeader>
      <DialogContent
        className={cn(
          "top-1/3 translate-y-0 overflow-hidden rounded-xl! p-0",
          className
        )}
        showCloseButton={showCloseButton}
      >
        {children}
      </DialogContent>
    </Dialog>
  )
}

function CommandInput({
  className,
  ...props
}: React.ComponentProps<typeof CommandPrimitive.Input>) {
  return (
    <div data-slot="command-input-wrapper" className="p-1 pb-0">
      <InputGroup className="h-8! rounded-lg! border-input/30 bg-input/30 shadow-none! *:data-[slot=input-group-addon]:pl-2!">
        <CommandPrimitive.Input
          data-slot="command-input"
          className={cn(
            "w-full text-sm outline-hidden disabled:cursor-not-allowed disabled:opacity-50",
            className
          )}
          {...props}
        />
        <InputGroupAddon>
          <SearchIcon className="size-4 shrink-0 opacity-50" />
        </InputGroupAddon>
      </InputGroup>
    </div>
  )
}

function CommandList({
  className,
  ...props
}: React.ComponentProps<typeof CommandPrimitive.List>) {
  return (
    <CommandPrimitive.List
      data-slot="command-list"
      className={cn(
        "no-scrollbar max-h-72 scroll-py-1 overflow-x-hidden overflow-y-auto outline-none",
        className
      )}
      {...props}
    />
  )
}

function CommandEmpty({
  className,
  ...props
}: React.ComponentProps<typeof CommandPrimitive.Empty>) {
  return (
    <CommandPrimitive.Empty
      data-slot="command-empty"
      className={cn("py-6 text-center text-sm", className)}
      {...props}
    />
  )
}

function CommandGroup({
  className,
  ...props
}: React.ComponentProps<typeof CommandPrimitive.Group>) {
  return (
    <CommandPrimitive.Group
      data-slot="command-group"
      className={cn(
        "overflow-hidden p-1 text-foreground **:[[cmdk-group-heading]]:px-2 **:[[cmdk-group-heading]]:py-1.5 **:[[cmdk-group-heading]]:text-xs **:[[cmdk-group-heading]]:font-medium **:[[cmdk-group-heading]]:text-muted-foreground",
        className
      )}
      {...props}
    />
  )
}

function CommandSeparator({
  className,
  ...props
}: React.ComponentProps<typeof CommandPrimitive.Separator>) {
  return (
    <CommandPrimitive.Separator
      data-slot="command-separator"
      className={cn("-mx-1 h-px bg-border", className)}
      {...props}
    />
  )
}

function CommandItem({
  className,
  children,
  ...props
}: React.ComponentProps<typeof CommandPrimitive.Item>) {
  return (
    <CommandPrimitive.Item
      data-slot="command-item"
      className={cn(
        "group/command-item relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none in-data-[slot=dialog-content]:rounded-lg! data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 data-selected:bg-muted data-selected:text-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 data-selected:*:[svg]:text-foreground",
        className
      )}
      {...props}
    >
      {children}
      <CheckIcon className="ml-auto opacity-0 group-has-data-[slot=command-shortcut]/command-item:hidden group-data-[checked=true]/command-item:opacity-100" />
    </CommandPrimitive.Item>
  )
}

function CommandShortcut({
  className,
  ...props
}: React.ComponentProps<"span">) {
  return (
    <span
      data-slot="command-shortcut"
      className={cn(
        "ml-auto text-xs tracking-widest text-muted-foreground group-data-selected/command-item:text-foreground",
        className
      )}
      {...props}
    />
  )
}

export {
  Command,
  CommandDialog,
  CommandInput,
  CommandList,
  CommandEmpty,
  CommandGroup,
  CommandItem,
  CommandShortcut,
  CommandSeparator,
}
```

---

# Context Menu

Actions on right-click or long press.

Docs: https://jds-ruddy.vercel.app/docs/components/context-menu

## Installation

```bash
npx shadcn@latest add @jds/context-menu
```

npm dependencies: `@base-ui/react`, `cn`

Also installs: `@jds/utils`

## Example

```tsx
import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuItem,
  ContextMenuSeparator,
  ContextMenuShortcut,
  ContextMenuTrigger,
} from "@/components/ui/context-menu"

export default function ContextMenuDemo() {
  return (
    <ContextMenu>
      <ContextMenuTrigger
        render={
          <div className="grid h-36 w-72 place-items-center rounded-xl border border-dashed text-sm text-muted-foreground" />
        }
      >
        Right-click a message
      </ContextMenuTrigger>
      <ContextMenuContent className="w-52">
        <ContextMenuItem>
          Copy <ContextMenuShortcut>⌘C</ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuItem>Regenerate</ContextMenuItem>
        <ContextMenuItem>Branch from here</ContextMenuItem>
        <ContextMenuSeparator />
        <ContextMenuItem variant="destructive">Delete</ContextMenuItem>
      </ContextMenuContent>
    </ContextMenu>
  )
}
```

## Source

### components/ui/context-menu.tsx

```tsx
"use client"

import * as React from "react"
import { ContextMenu as ContextMenuPrimitive } from "@base-ui/react/context-menu"
import { cn } from "cn"
import { ChevronRightIcon, CheckIcon } from "@/lib/icons"

function ContextMenu({ ...props }: ContextMenuPrimitive.Root.Props) {
  return <ContextMenuPrimitive.Root data-slot="context-menu" {...props} />
}

function ContextMenuPortal({ ...props }: ContextMenuPrimitive.Portal.Props) {
  return (
    <ContextMenuPrimitive.Portal data-slot="context-menu-portal" {...props} />
  )
}

function ContextMenuTrigger({
  className,
  ...props
}: ContextMenuPrimitive.Trigger.Props) {
  return (
    <ContextMenuPrimitive.Trigger
      data-slot="context-menu-trigger"
      className={cn("select-none", className)}
      {...props}
    />
  )
}

function ContextMenuContent({
  className,
  align = "start",
  alignOffset = 4,
  side = "right",
  sideOffset = 0,
  ...props
}: ContextMenuPrimitive.Popup.Props &
  Pick<
    ContextMenuPrimitive.Positioner.Props,
    "align" | "alignOffset" | "side" | "sideOffset"
  >) {
  return (
    <ContextMenuPrimitive.Portal>
      <ContextMenuPrimitive.Positioner
        className="isolate z-50 outline-none"
        align={align}
        alignOffset={alignOffset}
        side={side}
        sideOffset={sideOffset}
      >
        <ContextMenuPrimitive.Popup
          data-slot="context-menu-content"
          className={cn("z-50 max-h-(--available-height) min-w-36 origin-(--transform-origin) overflow-x-hidden overflow-y-auto rounded-lg bg-popover p-1 text-popover-foreground shadow-md ring-1 ring-foreground/10 duration-100 outline-none data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95", className )}
          {...props}
        />
      </ContextMenuPrimitive.Positioner>
    </ContextMenuPrimitive.Portal>
  )
}

function ContextMenuGroup({ ...props }: ContextMenuPrimitive.Group.Props) {
  return (
    <ContextMenuPrimitive.Group data-slot="context-menu-group" {...props} />
  )
}

function ContextMenuLabel({
  className,
  inset,
  ...props
}: ContextMenuPrimitive.GroupLabel.Props & {
  inset?: boolean
}) {
  return (
    <ContextMenuPrimitive.GroupLabel
      data-slot="context-menu-label"
      data-inset={inset}
      className={cn(
        "px-1.5 py-1 text-xs font-medium text-muted-foreground data-inset:pl-7",
        className
      )}
      {...props}
    />
  )
}

function ContextMenuItem({
  className,
  inset,
  variant = "default",
  ...props
}: ContextMenuPrimitive.Item.Props & {
  inset?: boolean
  variant?: "default" | "destructive"
}) {
  return (
    <ContextMenuPrimitive.Item
      data-slot="context-menu-item"
      data-inset={inset}
      data-variant={variant}
      className={cn(
        "group/context-menu-item relative flex cursor-default items-center gap-1.5 rounded-md px-1.5 py-1 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground data-inset:pl-7 data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 data-[variant=destructive]:focus:text-destructive dark:data-[variant=destructive]:focus:bg-destructive/20 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 focus:*:[svg]:text-accent-foreground data-[variant=destructive]:*:[svg]:text-destructive",
        className
      )}
      {...props}
    />
  )
}

function ContextMenuSub({ ...props }: ContextMenuPrimitive.SubmenuRoot.Props) {
  return (
    <ContextMenuPrimitive.SubmenuRoot data-slot="context-menu-sub" {...props} />
  )
}

function ContextMenuSubTrigger({
  className,
  inset,
  children,
  ...props
}: ContextMenuPrimitive.SubmenuTrigger.Props & {
  inset?: boolean
}) {
  return (
    <ContextMenuPrimitive.SubmenuTrigger
      data-slot="context-menu-sub-trigger"
      data-inset={inset}
      className={cn(
        "flex cursor-default items-center gap-1.5 rounded-md px-1.5 py-1 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground data-inset:pl-7 data-open:bg-accent data-open:text-accent-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
        className
      )}
      {...props}
    >
      {children}
      <ChevronRightIcon className="ml-auto" />
    </ContextMenuPrimitive.SubmenuTrigger>
  )
}

function ContextMenuSubContent({
  ...props
}: React.ComponentProps<typeof ContextMenuContent>) {
  return (
    <ContextMenuContent
      data-slot="context-menu-sub-content"
      className="shadow-lg"
      side="right"
      {...props}
    />
  )
}

function ContextMenuCheckboxItem({
  className,
  children,
  checked,
  inset,
  ...props
}: ContextMenuPrimitive.CheckboxItem.Props & {
  inset?: boolean
}) {
  return (
    <ContextMenuPrimitive.CheckboxItem
      data-slot="context-menu-checkbox-item"
      data-inset={inset}
      className={cn(
        "relative flex cursor-default items-center gap-1.5 rounded-md py-1 pr-8 pl-1.5 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground data-inset:pl-7 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
        className
      )}
      checked={checked}
      {...props}
    >
      <span className="pointer-events-none absolute right-2">
        <ContextMenuPrimitive.CheckboxItemIndicator>
          <CheckIcon
          />
        </ContextMenuPrimitive.CheckboxItemIndicator>
      </span>
      {children}
    </ContextMenuPrimitive.CheckboxItem>
  )
}

function ContextMenuRadioGroup({
  ...props
}: ContextMenuPrimitive.RadioGroup.Props) {
  return (
    <ContextMenuPrimitive.RadioGroup
      data-slot="context-menu-radio-group"
      {...props}
    />
  )
}

function ContextMenuRadioItem({
  className,
  children,
  inset,
  ...props
}: ContextMenuPrimitive.RadioItem.Props & {
  inset?: boolean
}) {
  return (
    <ContextMenuPrimitive.RadioItem
      data-slot="context-menu-radio-item"
      data-inset={inset}
      className={cn(
        "relative flex cursor-default items-center gap-1.5 rounded-md py-1 pr-8 pl-1.5 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground data-inset:pl-7 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
        className
      )}
      {...props}
    >
      <span className="pointer-events-none absolute right-2">
        <ContextMenuPrimitive.RadioItemIndicator>
          <CheckIcon
          />
        </ContextMenuPrimitive.RadioItemIndicator>
      </span>
      {children}
    </ContextMenuPrimitive.RadioItem>
  )
}

function ContextMenuSeparator({
  className,
  ...props
}: ContextMenuPrimitive.Separator.Props) {
  return (
    <ContextMenuPrimitive.Separator
      data-slot="context-menu-separator"
      className={cn("-mx-1 my-1 h-px bg-border", className)}
      {...props}
    />
  )
}

function ContextMenuShortcut({
  className,
  ...props
}: React.ComponentProps<"span">) {
  return (
    <span
      data-slot="context-menu-shortcut"
      className={cn(
        "ml-auto text-xs tracking-widest text-muted-foreground group-focus/context-menu-item:text-accent-foreground",
        className
      )}
      {...props}
    />
  )
}

export {
  ContextMenu,
  ContextMenuTrigger,
  ContextMenuContent,
  ContextMenuItem,
  ContextMenuCheckboxItem,
  ContextMenuRadioItem,
  ContextMenuLabel,
  ContextMenuSeparator,
  ContextMenuShortcut,
  ContextMenuGroup,
  ContextMenuPortal,
  ContextMenuSub,
  ContextMenuSubContent,
  ContextMenuSubTrigger,
  ContextMenuRadioGroup,
}
```

---

# Drawer

A panel that slides up from the bottom and can be swiped away.

Docs: https://jds-ruddy.vercel.app/docs/components/drawer

## Installation

```bash
npx shadcn@latest add @jds/drawer
```

npm dependencies: `@base-ui/react`, `cn`

## Example

```tsx
import { Button } from "@/components/ui/button"
import {
  Drawer,
  DrawerClose,
  DrawerContent,
  DrawerDescription,
  DrawerFooter,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
} from "@/components/ui/drawer"

export default function DrawerDemo() {
  return (
    <Drawer>
      <DrawerTrigger render={<Button variant="outline" />}>Share conversation</DrawerTrigger>
      <DrawerContent>
        <div className="mx-auto w-full max-w-sm">
          <DrawerHeader>
            <DrawerTitle>Share conversation</DrawerTitle>
            <DrawerDescription>Anyone with the link can read it. Files stay private.</DrawerDescription>
          </DrawerHeader>
          <DrawerFooter>
            <Button>Copy link</Button>
            <DrawerClose render={<Button variant="outline" />}>Cancel</DrawerClose>
          </DrawerFooter>
        </div>
      </DrawerContent>
    </Drawer>
  )
}
```

## Source

### components/ui/drawer.tsx

```tsx
"use client"

import * as React from "react"
import { Drawer as DrawerPrimitive } from "@base-ui/react/drawer"
import { cn } from "cn"

type DrawerContextProps = {
  hasSnapPoints: boolean
  modal: DrawerPrimitive.Root.Props["modal"]
  showSwipeHandle: boolean
  swipeDirection: NonNullable<DrawerPrimitive.Root.Props["swipeDirection"]>
}

const DrawerContext = React.createContext<DrawerContextProps | null>(null)

function useDrawer() {
  const context = React.useContext(DrawerContext)

if (!context) {
    throw new Error("useDrawer must be used within a Drawer.")
  }

return context
}

function Drawer({
  modal = true,
  showSwipeHandle = false,
  snapPoints,
  swipeDirection = "down",
  ...props
}: DrawerPrimitive.Root.Props & {
  showSwipeHandle?: boolean
}) {
  const hasSnapPoints = snapPoints != null && snapPoints.length > 0
  const contextValue = React.useMemo(
    () => ({ hasSnapPoints, modal, showSwipeHandle, swipeDirection }),
    [hasSnapPoints, modal, showSwipeHandle, swipeDirection]
  )

return (
    <DrawerContext.Provider value={contextValue}>
      <DrawerPrimitive.Root
        data-slot="drawer"
        modal={modal}
        snapPoints={snapPoints}
        swipeDirection={swipeDirection}
        {...props}
      />
    </DrawerContext.Provider>
  )
}

function DrawerTrigger({ ...props }: DrawerPrimitive.Trigger.Props) {
  return <DrawerPrimitive.Trigger data-slot="drawer-trigger" {...props} />
}

function DrawerPortal({ ...props }: DrawerPrimitive.Portal.Props) {
  return <DrawerPrimitive.Portal data-slot="drawer-portal" {...props} />
}

function DrawerClose({ ...props }: DrawerPrimitive.Close.Props) {
  return <DrawerPrimitive.Close data-slot="drawer-close" {...props} />
}

function DrawerOverlay({
  className,
  ...props
}: DrawerPrimitive.Backdrop.Props) {
  return (
    <DrawerPrimitive.Backdrop
      data-slot="drawer-overlay"
      className={cn(
        "fixed inset-0 z-50 min-h-dvh bg-black/10 opacity-[max(var(--drawer-overlay-min-opacity,0),calc(1-var(--drawer-swipe-progress)))] transition-opacity duration-450 ease-[cubic-bezier(0.32,0.72,0,1)] select-none data-ending-style:pointer-events-none data-ending-style:opacity-0 data-ending-style:duration-[calc(var(--drawer-swipe-strength)*400ms)] data-snap-points:[--drawer-overlay-min-opacity:0.5] data-starting-style:opacity-0 data-swiping:duration-0 supports-backdrop-filter:backdrop-blur-xs supports-[-webkit-touch-callout:none]:absolute",
        className
      )}
      {...props}
    />
  )
}

function DrawerSwipeHandle({
  className,
  ...props
}: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="drawer-swipe-handle"
      aria-hidden="true"
      className={cn(
        "relative z-10 flex shrink-0 cursor-grab transition-opacity duration-200 group-data-nested-drawer-open/drawer-popup:opacity-0 group-data-nested-drawer-swiping/drawer-popup:opacity-100 group-data-[swipe-axis=x]/drawer-popup:h-full group-data-[swipe-axis=x]/drawer-popup:w-3 group-data-[swipe-axis=x]/drawer-popup:items-center group-data-[swipe-axis=y]/drawer-popup:h-3 group-data-[swipe-axis=y]/drawer-popup:w-full group-data-[swipe-axis=y]/drawer-popup:justify-center group-data-[swipe-direction=down]/drawer-popup:items-end group-data-[swipe-direction=left]/drawer-popup:order-last group-data-[swipe-direction=left]/drawer-popup:justify-start group-data-[swipe-direction=right]/drawer-popup:justify-end group-data-[swipe-direction=up]/drawer-popup:order-last group-data-[swipe-direction=up]/drawer-popup:items-start after:block after:shrink-0 after:rounded-full after:bg-muted group-data-[swipe-axis=x]/drawer-popup:after:h-24 group-data-[swipe-axis=x]/drawer-popup:after:w-1 group-data-[swipe-axis=y]/drawer-popup:after:h-1 group-data-[swipe-axis=y]/drawer-popup:after:w-24 active:cursor-grabbing",
        className
      )}
      {...props}
    />
  )
}

function DrawerContent({
  className,
  children,
  ...props
}: DrawerPrimitive.Popup.Props) {
  const { hasSnapPoints, modal, showSwipeHandle, swipeDirection } = useDrawer()
  const swipeAxis =
    swipeDirection === "down" || swipeDirection === "up" ? "y" : "x"

return (
    <DrawerPortal data-slot="drawer-portal">
      {modal === true && (
        <DrawerOverlay data-snap-points={hasSnapPoints ? "" : undefined} />
      )}
      <DrawerPrimitive.Viewport
        data-slot="drawer-viewport"
        data-modal={modal}
        className="pointer-events-none fixed inset-0 z-50 select-none data-[modal=true]:pointer-events-auto"
      >
        <DrawerPrimitive.Popup
          data-slot="drawer-popup"
          data-swipe-axis={swipeAxis}
          data-snap-points={hasSnapPoints ? "" : undefined}
          className={cn(
            // Base.
            "group/drawer-popup pointer-events-auto fixed z-50 m-(--drawer-inset,0px) flex h-(--drawer-content-height) max-h-(--drawer-content-max-height,none) min-h-0 w-(--drawer-content-width,auto) transform-[translate3d(var(--translate-x,0px),var(--translate-y,0px),0)_scale(var(--stack-scale))] flex-col bg-popover text-sm text-popover-foreground transition-[transform,height,opacity,filter] duration-450 ease-[cubic-bezier(0.22,1,0.36,1)] will-change-transform outline-none select-none [interpolate-size:allow-keywords] data-[swipe-direction=down]:rounded-t-xl data-[swipe-direction=down]:border-t data-[swipe-direction=left]:rounded-r-xl data-[swipe-direction=left]:border-r data-[swipe-direction=right]:rounded-l-xl data-[swipe-direction=right]:border-l data-[swipe-direction=up]:rounded-b-xl data-[swipe-direction=up]:border-b",
            // Nested.
            "data-nested-drawer-open:overflow-hidden data-nested-drawer-open:brightness-95",
            // Bleed.
            "after:pointer-events-none after:absolute after:bg-(--drawer-bleed-background,var(--color-popover)) data-[swipe-axis=x]:after:inset-y-0 data-[swipe-axis=x]:after:w-(--bleed) data-[swipe-axis=y]:after:inset-x-0 data-[swipe-axis=y]:after:h-(--bleed) data-[swipe-direction=down]:after:top-full data-[swipe-direction=left]:after:right-full data-[swipe-direction=right]:after:left-full data-[swipe-direction=up]:after:bottom-full",
            // Sizing.
            "[--drawer-content-height:var(--drawer-height,auto)] data-[swipe-axis=x]:[--drawer-content-width:75%] data-[swipe-axis=y]:[--drawer-content-max-height:calc(100dvh-6rem)] data-[swipe-axis=y]:data-snap-points:[--drawer-content-height:100dvh] data-[swipe-axis=x]:sm:[--drawer-content-width:24rem]",
            // Stack.
            "[--bleed:3rem] [--peek:1rem] [--stack-height:var(--drawer-frontmost-height,var(--drawer-height,0px))] [--stack-peek-offset:max(0px,calc((var(--nested-drawers)-var(--stack-progress))*var(--peek)))] [--stack-progress:clamp(0,var(--drawer-swipe-progress),1)] [--stack-scale-base:max(0,calc(1-(var(--nested-drawers)*var(--stack-step))))] [--stack-scale:clamp(0,calc(var(--stack-scale-base)+(var(--stack-step)*var(--stack-progress))),1)] [--stack-shrink:calc(1-var(--stack-scale))] [--stack-step:0.05]",
            // Transitions.
            "data-ending-style:transform-(--closed-transform) data-ending-style:opacity-[0.9999] data-ending-style:duration-[calc(var(--drawer-swipe-strength)*400ms)] data-nested-drawer-swiping:duration-0 data-ending-style:data-nested-drawer-swiping:duration-[calc(var(--drawer-swipe-strength)*400ms)] data-starting-style:transform-(--closed-transform) data-swiping:duration-0 data-ending-style:data-swiping:duration-[calc(var(--drawer-swipe-strength)*400ms)]",
            // Axis: y.
            "data-[swipe-axis=y]:inset-x-0 data-[swipe-axis=y]:data-nested-drawer-open:h-(--stack-height)",
            // Axis: x.
            "data-[swipe-axis=x]:inset-y-0 data-[swipe-axis=x]:flex-row",
            // Direction: down.
            "data-[swipe-direction=down]:bottom-0 data-[swipe-direction=down]:origin-bottom data-[swipe-direction=down]:[--closed-transform:translate3d(0,calc(100%+var(--drawer-inset,0px)+2px),0)] data-[swipe-direction=down]:[--translate-y:calc(var(--drawer-snap-point-offset,0px)+var(--drawer-swipe-movement-y)-var(--stack-peek-offset)-(var(--stack-shrink)*var(--stack-height)))]",
            // Direction: up.
            "data-[swipe-direction=up]:top-0 data-[swipe-direction=up]:origin-top data-[swipe-direction=up]:[--closed-transform:translate3d(0,calc(-100%-var(--drawer-inset,0px)-2px),0)] data-[swipe-direction=up]:[--translate-y:calc(var(--drawer-snap-point-offset,0px)+var(--drawer-swipe-movement-y)+var(--stack-peek-offset)+(var(--stack-shrink)*var(--stack-height)))]",
            // Direction: left.
            "data-[swipe-direction=left]:left-0 data-[swipe-direction=left]:origin-left data-[swipe-direction=left]:[--closed-transform:translate3d(calc(-100%-var(--drawer-inset,0px)-2px),0,0)] data-[swipe-direction=left]:[--translate-x:calc(var(--drawer-swipe-movement-x)+var(--stack-peek-offset)+(var(--stack-shrink)*100%))]",
            // Direction: right.
            "data-[swipe-direction=right]:right-0 data-[swipe-direction=right]:origin-right data-[swipe-direction=right]:[--closed-transform:translate3d(calc(100%+var(--drawer-inset,0px)+2px),0,0)] data-[swipe-direction=right]:[--translate-x:calc(var(--drawer-swipe-movement-x)-var(--stack-peek-offset)-(var(--stack-shrink)*100%))]",
            className
          )}
          {...props}
        >
          {showSwipeHandle && <DrawerSwipeHandle />}
          <DrawerPrimitive.Content
            data-slot="drawer-content"
            className={cn(
              "flex min-h-0 flex-1 flex-col overflow-hidden overscroll-contain rounded-[inherit] transition-opacity duration-300 ease-[cubic-bezier(0.45,1.005,0,1.005)] select-text group-data-nested-drawer-open/drawer-popup:opacity-0 group-data-nested-drawer-swiping/drawer-popup:opacity-100 group-data-swiping/drawer-popup:select-none"
            )}
          >
            {children}
          </DrawerPrimitive.Content>
        </DrawerPrimitive.Popup>
      </DrawerPrimitive.Viewport>
    </DrawerPortal>
  )
}

function DrawerHeader({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="drawer-header"
      className={cn(
        "flex shrink-0 flex-col gap-0.5 p-4 pb-0 group-data-[swipe-axis=y]/drawer-popup:text-center md:gap-0.5 md:text-left",
        className
      )}
      {...props}
    />
  )
}

function DrawerFooter({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="drawer-footer"
      className={cn("mt-auto flex shrink-0 flex-col gap-2 p-4 pt-0", className)}
      {...props}
    />
  )
}

function DrawerTitle({ className, ...props }: DrawerPrimitive.Title.Props) {
  return (
    <DrawerPrimitive.Title
      data-slot="drawer-title"
      className={cn(
        "font-heading text-base font-medium text-foreground",
        className
      )}
      {...props}
    />
  )
}

function DrawerDescription({
  className,
  ...props
}: DrawerPrimitive.Description.Props) {
  return (
    <DrawerPrimitive.Description
      data-slot="drawer-description"
      className={cn("text-sm text-balance text-muted-foreground", className)}
      {...props}
    />
  )
}

export {
  Drawer,
  DrawerPortal,
  DrawerOverlay,
  DrawerSwipeHandle,
  DrawerTrigger,
  DrawerClose,
  DrawerContent,
  DrawerHeader,
  DrawerFooter,
  DrawerTitle,
  DrawerDescription,
}
```

---

# Empty

A placeholder for empty states, with a next step.

Docs: https://jds-ruddy.vercel.app/docs/components/empty

## Installation

```bash
npx shadcn@latest add @jds/empty
```

npm dependencies: `class-variance-authority`, `cn`

## Example

```tsx
import { Button } from "@/components/ui/button"
import { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from "@/components/ui/empty"
import { AgentIcon } from "@/lib/icons"

export default function EmptyDemo() {
  return (
    <div className="w-full max-w-md rounded-xl border">
      <Empty>
        <EmptyHeader>
          <EmptyMedia variant="icon">
            <AgentIcon />
          </EmptyMedia>
          <EmptyTitle>No agents yet</EmptyTitle>
          <EmptyDescription>Create an agent to automate support, research or reporting.</EmptyDescription>
        </EmptyHeader>
        <EmptyContent>
          <Button size="sm">Create agent</Button>
        </EmptyContent>
      </Empty>
    </div>
  )
}
```

## Source

### components/ui/empty.tsx

```tsx
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "cn"

function Empty({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="empty"
      className={cn(
        "flex w-full min-w-0 flex-1 flex-col items-center justify-center gap-4 rounded-xl border-dashed p-6 text-center text-balance",
        className
      )}
      {...props}
    />
  )
}

function EmptyHeader({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="empty-header"
      className={cn("flex max-w-sm flex-col items-center gap-2", className)}
      {...props}
    />
  )
}

const emptyMediaVariants = cva(
  "mb-2 flex shrink-0 items-center justify-center [&_svg]:pointer-events-none [&_svg]:shrink-0",
  {
    variants: {
      variant: {
        default: "bg-transparent",
        icon: "flex size-8 shrink-0 items-center justify-center rounded-lg bg-muted text-foreground [&_svg:not([class*='size-'])]:size-4",
      },
    },
    defaultVariants: {
      variant: "default",
    },
  }
)

function EmptyMedia({
  className,
  variant = "default",
  ...props
}: React.ComponentProps<"div"> & VariantProps<typeof emptyMediaVariants>) {
  return (
    <div
      data-slot="empty-icon"
      data-variant={variant}
      className={cn(emptyMediaVariants({ variant, className }))}
      {...props}
    />
  )
}

function EmptyTitle({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="empty-title"
      className={cn(
        "font-heading text-sm font-medium tracking-tight",
        className
      )}
      {...props}
    />
  )
}

function EmptyDescription({ className, ...props }: React.ComponentProps<"p">) {
  return (
    <div
      data-slot="empty-description"
      className={cn(
        "text-sm/relaxed text-muted-foreground [&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary",
        className
      )}
      {...props}
    />
  )
}

function EmptyContent({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="empty-content"
      className={cn(
        "flex w-full max-w-sm min-w-0 flex-col items-center gap-2.5 text-sm text-balance",
        className
      )}
      {...props}
    />
  )
}

export {
  Empty,
  EmptyHeader,
  EmptyTitle,
  EmptyDescription,
  EmptyContent,
  EmptyMedia,
}
```

---

# Field

Label, control, description and error, laid out consistently.

Docs: https://jds-ruddy.vercel.app/docs/components/field

## Installation

```bash
npx shadcn@latest add @jds/field
```

npm dependencies: `class-variance-authority`, `cn`

Also installs: `@jds/label`, `@jds/separator`

## Example

```tsx
import { Field, FieldDescription, FieldGroup, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"
import { Textarea } from "@/components/ui/textarea"

export default function FieldDemo() {
  return (
    <FieldGroup className="w-full max-w-sm">
      <Field>
        <FieldLabel htmlFor="agent-name">Name</FieldLabel>
        <Input id="agent-name" placeholder="Support agent" />
      </Field>
      <Field>
        <FieldLabel htmlFor="agent-instructions">Instructions</FieldLabel>
        <Textarea id="agent-instructions" placeholder="Be concise. Ask before refunds." />
        <FieldDescription>Sent with every conversation as the system prompt.</FieldDescription>
      </Field>
    </FieldGroup>
  )
}
```

## Source

### components/ui/field.tsx

```tsx
"use client"

import { useMemo } from "react"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "cn"

import { Label } from "@/components/ui/label"
import { Separator } from "@/components/ui/separator"

function FieldSet({ className, ...props }: React.ComponentProps<"fieldset">) {
  return (
    <fieldset
      data-slot="field-set"
      className={cn(
        "flex flex-col gap-4 has-[>[data-slot=checkbox-group]]:gap-3 has-[>[data-slot=radio-group]]:gap-3",
        className
      )}
      {...props}
    />
  )
}

function FieldLegend({
  className,
  variant = "legend",
  ...props
}: React.ComponentProps<"legend"> & { variant?: "legend" | "label" }) {
  return (
    <legend
      data-slot="field-legend"
      data-variant={variant}
      className={cn(
        "mb-1.5 font-medium data-[variant=label]:text-sm data-[variant=legend]:text-base",
        className
      )}
      {...props}
    />
  )
}

function FieldGroup({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="field-group"
      className={cn(
        "group/field-group @container/field-group flex w-full flex-col gap-5 data-[slot=checkbox-group]:gap-3 *:data-[slot=field-group]:gap-4",
        className
      )}
      {...props}
    />
  )
}

const fieldVariants = cva(
  "group/field flex w-full gap-2 data-[invalid=true]:text-destructive",
  {
    variants: {
      orientation: {
        vertical: "flex-col *:w-full [&>.sr-only]:w-auto",
        horizontal:
          "flex-row items-center has-[>[data-slot=field-content]]:items-start *:data-[slot=field-label]:flex-auto has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
        responsive:
          "flex-col *:w-full @md/field-group:flex-row @md/field-group:items-center @md/field-group:*:w-auto @md/field-group:has-[>[data-slot=field-content]]:items-start @md/field-group:*:data-[slot=field-label]:flex-auto [&>.sr-only]:w-auto @md/field-group:has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
      },
    },
    defaultVariants: {
      orientation: "vertical",
    },
  }
)

function Field({
  className,
  orientation = "vertical",
  ...props
}: React.ComponentProps<"div"> & VariantProps<typeof fieldVariants>) {
  return (
    <div
      role="group"
      data-slot="field"
      data-orientation={orientation}
      className={cn(fieldVariants({ orientation }), className)}
      {...props}
    />
  )
}

function FieldContent({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="field-content"
      className={cn(
        "group/field-content flex flex-1 flex-col gap-0.5 leading-snug",
        className
      )}
      {...props}
    />
  )
}

function FieldLabel({
  className,
  ...props
}: React.ComponentProps<typeof Label>) {
  return (
    <Label
      data-slot="field-label"
      className={cn(
        "group/field-label peer/field-label flex w-fit gap-2 leading-snug group-data-[disabled=true]/field:opacity-50 has-data-checked:border-primary/30 has-data-checked:bg-primary/5 has-[>[data-slot=field]]:rounded-lg has-[>[data-slot=field]]:border has-[>[data-slot=field]]:not-has-[:disabled,[data-disabled]]:hover:bg-muted/50 has-[>[data-slot=field]]:has-[:focus-visible]:border-ring has-[>[data-slot=field]]:has-[:focus-visible]:ring-3 has-[>[data-slot=field]]:has-[:focus-visible]:ring-ring/50 *:data-[slot=field]:p-2.5 dark:has-data-checked:border-primary/20 dark:has-data-checked:bg-primary/10",
        "has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col",
        className
      )}
      {...props}
    />
  )
}

function FieldTitle({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="field-label"
      className={cn(
        "flex w-fit items-center gap-2 text-sm font-medium group-data-[disabled=true]/field:opacity-50",
        className
      )}
      {...props}
    />
  )
}

function FieldDescription({ className, ...props }: React.ComponentProps<"p">) {
  return (
    <p
      data-slot="field-description"
      className={cn(
        "text-left text-sm leading-normal font-normal text-muted-foreground group-has-data-horizontal/field:text-balance [[data-variant=legend]+&]:-mt-1.5",
        "last:mt-0 nth-last-2:-mt-1",
        "[&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary",
        className
      )}
      {...props}
    />
  )
}

function FieldSeparator({
  children,
  className,
  ...props
}: React.ComponentProps<"div"> & {
  children?: React.ReactNode
}) {
  return (
    <div
      data-slot="field-separator"
      data-content={!!children}
      className={cn(
        "relative -my-2 h-5 text-sm group-data-[variant=outline]/field-group:-mb-2",
        className
      )}
      {...props}
    >
      <Separator className="absolute inset-0 top-1/2" />
      {children && (
        <span
          className="relative mx-auto block w-fit bg-background px-2 text-muted-foreground"
          data-slot="field-separator-content"
        >
          {children}
        </span>
      )}
    </div>
  )
}

function FieldError({
  className,
  children,
  errors,
  ...props
}: React.ComponentProps<"div"> & {
  errors?: Array<{ message?: string } | undefined>
}) {
  const content = useMemo(() => {
    if (children) {
      return children
    }

if (!errors?.length) {
      return null
    }

const uniqueErrors = [
      ...new Map(errors.map((error) => [error?.message, error])).values(),
    ]

if (uniqueErrors?.length == 1) {
      return uniqueErrors[0]?.message
    }

return (
      <ul className="ml-4 flex list-disc flex-col gap-1">
        {uniqueErrors.map(
          (error, index) =>
            error?.message && <li key={index}>{error.message}</li>
        )}
      </ul>
    )
  }, [children, errors])

if (!content) {
    return null
  }

return (
    <div
      role="alert"
      data-slot="field-error"
      className={cn("text-sm font-normal text-destructive", className)}
      {...props}
    >
      {content}
    </div>
  )
}

export {
  Field,
  FieldLabel,
  FieldDescription,
  FieldError,
  FieldGroup,
  FieldLegend,
  FieldSeparator,
  FieldSet,
  FieldContent,
  FieldTitle,
}
```

---

# Hover Card

A rich preview when hovering a link or mention.

Docs: https://jds-ruddy.vercel.app/docs/components/hover-card

## Installation

```bash
npx shadcn@latest add @jds/hover-card
```

npm dependencies: `@base-ui/react`, `cn`

## Example

```tsx
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/ui/hover-card"

export default function HoverCardDemo() {
  return (
    <HoverCard>
      <HoverCardTrigger render={<a href="#" className="text-sm font-medium underline underline-offset-4" />}>
        @researcher
      </HoverCardTrigger>
      <HoverCardContent className="w-72">
        <div className="flex gap-3">
          <Avatar>
            <AvatarFallback>RE</AvatarFallback>
          </Avatar>
          <div className="space-y-1">
            <p className="text-sm font-medium">Researcher</p>
            <p className="text-sm text-muted-foreground">Searches the web and your docs, then cites every claim.</p>
            <p className="text-xs text-muted-foreground">Used 214 times this week</p>
          </div>
        </div>
      </HoverCardContent>
    </HoverCard>
  )
}
```

## Source

### components/ui/hover-card.tsx

```tsx
"use client"

import { PreviewCard as PreviewCardPrimitive } from "@base-ui/react/preview-card"
import { cn } from "cn"

function HoverCard({ ...props }: PreviewCardPrimitive.Root.Props) {
  return <PreviewCardPrimitive.Root data-slot="hover-card" {...props} />
}

function HoverCardTrigger({ ...props }: PreviewCardPrimitive.Trigger.Props) {
  return (
    <PreviewCardPrimitive.Trigger data-slot="hover-card-trigger" {...props} />
  )
}

function HoverCardContent({
  className,
  side = "bottom",
  sideOffset = 4,
  align = "center",
  alignOffset = 4,
  ...props
}: PreviewCardPrimitive.Popup.Props &
  Pick<
    PreviewCardPrimitive.Positioner.Props,
    "align" | "alignOffset" | "side" | "sideOffset"
  >) {
  return (
    <PreviewCardPrimitive.Portal data-slot="hover-card-portal">
      <PreviewCardPrimitive.Positioner
        align={align}
        alignOffset={alignOffset}
        side={side}
        sideOffset={sideOffset}
        className="isolate z-50"
      >
        <PreviewCardPrimitive.Popup
          data-slot="hover-card-content"
          className={cn(
            "z-50 w-64 origin-(--transform-origin) rounded-lg bg-popover p-2.5 text-sm text-popover-foreground shadow-md ring-1 ring-foreground/10 outline-hidden duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
            className
          )}
          {...props}
        />
      </PreviewCardPrimitive.Positioner>
    </PreviewCardPrimitive.Portal>
  )
}

export { HoverCard, HoverCardTrigger, HoverCardContent }
```

---

# Input Group

An input with icons, text or buttons attached.

Docs: https://jds-ruddy.vercel.app/docs/components/input-group

## Installation

```bash
npx shadcn@latest add @jds/input-group
```

npm dependencies: `class-variance-authority`, `cn`

Also installs: `@jds/button`, `@jds/input`, `@jds/textarea`

## Example

```tsx
import { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput } from "@/components/ui/input-group"
import { SearchIcon } from "@/lib/icons"

export default function InputGroupDemo() {
  return (
    <InputGroup className="max-w-sm">
      <InputGroupAddon>
        <SearchIcon />
      </InputGroupAddon>
      <InputGroupInput placeholder="Search conversations" />
      <InputGroupAddon align="inline-end">
        <InputGroupButton>Search</InputGroupButton>
      </InputGroupAddon>
    </InputGroup>
  )
}
```

## Source

### components/ui/input-group.tsx

```tsx
"use client"

import * as React from "react"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "cn"

import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"
import { Textarea } from "@/components/ui/textarea"

function InputGroup({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="input-group"
      role="group"
      className={cn(
        "group/input-group relative flex h-8 w-full min-w-0 items-center rounded-lg border border-input transition-colors outline-none in-data-[slot=combobox-content]:focus-within:border-inherit in-data-[slot=combobox-content]:focus-within:ring-0 has-disabled:bg-input/50 has-disabled:opacity-50 has-[[data-slot=input-group-control]:focus-visible]:border-ring has-[[data-slot=input-group-control]:focus-visible]:ring-3 has-[[data-slot=input-group-control]:focus-visible]:ring-ring/50 has-[[data-slot][aria-invalid=true]]:border-destructive has-[[data-slot][aria-invalid=true]]:ring-3 has-[[data-slot][aria-invalid=true]]:ring-destructive/20 has-[>[data-align=block-end]]:h-auto has-[>[data-align=block-end]]:flex-col has-[>[data-align=block-start]]:h-auto has-[>[data-align=block-start]]:flex-col has-[>textarea]:h-auto dark:bg-input/30 dark:has-disabled:bg-input/80 dark:has-[[data-slot][aria-invalid=true]]:ring-destructive/40 has-[>[data-align=block-end]]:[&>input]:pt-3 has-[>[data-align=block-start]]:[&>input]:pb-3 has-[>[data-align=inline-end]]:[&>input]:pr-1.5 has-[>[data-align=inline-start]]:[&>input]:pl-1.5",
        className
      )}
      {...props}
    />
  )
}

const inputGroupAddonVariants = cva(
  "flex h-auto cursor-text items-center justify-center gap-2 py-1.5 text-sm font-medium text-muted-foreground select-none group-data-[disabled=true]/input-group:opacity-50 [&>kbd]:rounded-[calc(var(--radius)-5px)] [&>svg:not([class*='size-'])]:size-4",
  {
    variants: {
      align: {
        "inline-start":
          "order-first pl-2 has-[>button]:ml-[-0.3rem] has-[>kbd]:ml-[-0.15rem]",
        "inline-end":
          "order-last pr-2 has-[>button]:mr-[-0.3rem] has-[>kbd]:mr-[-0.15rem]",
        "block-start":
          "order-first w-full justify-start px-2.5 pt-2 group-has-[>input]/input-group:pt-2 [.border-b]:pb-2",
        "block-end":
          "order-last w-full justify-start px-2.5 pb-2 group-has-[>input]/input-group:pb-2 [.border-t]:pt-2",
      },
    },
    defaultVariants: {
      align: "inline-start",
    },
  }
)

function InputGroupAddon({
  className,
  align = "inline-start",
  ...props
}: React.ComponentProps<"div"> & VariantProps<typeof inputGroupAddonVariants>) {
  return (
    <div
      role="group"
      data-slot="input-group-addon"
      data-align={align}
      className={cn(inputGroupAddonVariants({ align }), className)}
      onClick={(e) => {
        if ((e.target as HTMLElement).closest("button")) {
          return
        }
        e.currentTarget.parentElement?.querySelector("input")?.focus()
      }}
      {...props}
    />
  )
}

const inputGroupButtonVariants = cva(
  "flex items-center gap-2 text-sm shadow-none",
  {
    variants: {
      size: {
        xs: "h-6 gap-1 rounded-[calc(var(--radius)-3px)] px-1.5 [&>svg:not([class*='size-'])]:size-3.5",
        sm: "",
        "icon-xs":
          "size-6 rounded-[calc(var(--radius)-3px)] p-0 has-[>svg]:p-0",
        "icon-sm": "size-8 p-0 has-[>svg]:p-0",
      },
    },
    defaultVariants: {
      size: "xs",
    },
  }
)

function InputGroupButton({
  className,
  type = "button",
  variant = "ghost",
  size = "xs",
  ...props
}: Omit<React.ComponentProps<typeof Button>, "size" | "type"> &
  VariantProps<typeof inputGroupButtonVariants> & {
    type?: "button" | "submit" | "reset"
  }) {
  return (
    <Button
      type={type}
      data-size={size}
      variant={variant}
      className={cn(inputGroupButtonVariants({ size }), className)}
      {...props}
    />
  )
}

function InputGroupText({ className, ...props }: React.ComponentProps<"span">) {
  return (
    <span
      className={cn(
        "flex items-center gap-2 text-sm text-muted-foreground [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4",
        className
      )}
      {...props}
    />
  )
}

function InputGroupInput({
  className,
  ...props
}: React.ComponentProps<"input">) {
  return (
    <Input
      data-slot="input-group-control"
      className={cn(
        "flex-1 rounded-none border-0 bg-transparent shadow-none ring-0 focus-visible:ring-0 disabled:bg-transparent aria-invalid:ring-0 dark:bg-transparent dark:disabled:bg-transparent",
        className
      )}
      {...props}
    />
  )
}

function InputGroupTextarea({
  className,
  ...props
}: React.ComponentProps<"textarea">) {
  return (
    <Textarea
      data-slot="input-group-control"
      className={cn(
        "flex-1 resize-none rounded-none border-0 bg-transparent py-2 shadow-none ring-0 focus-visible:ring-0 disabled:bg-transparent aria-invalid:ring-0 dark:bg-transparent dark:disabled:bg-transparent",
        className
      )}
      {...props}
    />
  )
}

export {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupText,
  InputGroupInput,
  InputGroupTextarea,
}
```

---

# Input OTP

One-time code entry, one character per slot.

Docs: https://jds-ruddy.vercel.app/docs/components/input-otp

## Installation

```bash
npx shadcn@latest add @jds/input-otp
```

npm dependencies: `cn`, `input-otp`

Also installs: `@jds/utils`

## Example

```tsx
"use client"

import { InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot } from "@/components/ui/input-otp"

export default function InputOTPDemo() {
  return (
    <InputOTP maxLength={6}>
      <InputOTPGroup>
        <InputOTPSlot index={0} />
        <InputOTPSlot index={1} />
        <InputOTPSlot index={2} />
      </InputOTPGroup>
      <InputOTPSeparator />
      <InputOTPGroup>
        <InputOTPSlot index={3} />
        <InputOTPSlot index={4} />
        <InputOTPSlot index={5} />
      </InputOTPGroup>
    </InputOTP>
  )
}
```

## Source

### components/ui/input-otp.tsx

```tsx
"use client"

import * as React from "react"
import { cn } from "cn"
import { OTPInput, OTPInputContext } from "input-otp"
import { MinusIcon } from "@/lib/icons"

function InputOTP({
  className,
  containerClassName,
  ...props
}: React.ComponentProps<typeof OTPInput> & {
  containerClassName?: string
}) {
  return (
    <OTPInput
      data-slot="input-otp"
      containerClassName={cn(
        "flex items-center has-disabled:opacity-50",
        containerClassName
      )}
      spellCheck={false}
      className={cn("disabled:cursor-not-allowed", className)}
      {...props}
    />
  )
}

function InputOTPGroup({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="input-otp-group"
      className={cn(
        "flex items-center rounded-lg has-aria-invalid:border-destructive has-aria-invalid:ring-3 has-aria-invalid:ring-destructive/20 dark:has-aria-invalid:ring-destructive/40",
        className
      )}
      {...props}
    />
  )
}

function InputOTPSlot({
  index,
  className,
  ...props
}: React.ComponentProps<"div"> & {
  index: number
}) {
  const inputOTPContext = React.useContext(OTPInputContext)
  const { char, hasFakeCaret, isActive } = inputOTPContext?.slots[index] ?? {}

return (
    <div
      data-slot="input-otp-slot"
      data-active={isActive}
      className={cn(
        "relative flex size-8 items-center justify-center border-y border-r border-input text-sm transition-all outline-none first:rounded-l-lg first:border-l last:rounded-r-lg aria-invalid:border-destructive data-[active=true]:z-10 data-[active=true]:border-ring data-[active=true]:ring-3 data-[active=true]:ring-ring/50 data-[active=true]:aria-invalid:border-destructive data-[active=true]:aria-invalid:ring-destructive/20 dark:bg-input/30 dark:data-[active=true]:aria-invalid:ring-destructive/40",
        className
      )}
      {...props}
    >
      {char}
      {hasFakeCaret && (
        <div className="pointer-events-none absolute inset-0 flex items-center justify-center">
          <div className="h-4 w-px animate-caret-blink bg-foreground duration-1000" />
        </div>
      )}
    </div>
  )
}

function InputOTPSeparator({ ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="input-otp-separator"
      className="flex items-center [&_svg:not([class*='size-'])]:size-4"
      role="separator"
      {...props}
    >
      <MinusIcon
      />
    </div>
  )
}

export { InputOTP, InputOTPGroup, InputOTPSlot, InputOTPSeparator }
```

---

# Label

Accessible text for a form control.

Docs: https://jds-ruddy.vercel.app/docs/components/label

## Installation

```bash
npx shadcn@latest add @jds/label
```

npm dependencies: `cn`

## Example

```tsx
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

export default function LabelDemo() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-2">
      <Label htmlFor="api-key">API key</Label>
      <Input id="api-key" type="password" placeholder="sk-…" />
    </div>
  )
}
```

## Source

### components/ui/label.tsx

```tsx
"use client"

import * as React from "react"
import { cn } from "cn"

function Label({ className, ...props }: React.ComponentProps<"label">) {
  return (
    <label
      data-slot="label"
      className={cn(
        "flex items-center gap-2 text-sm leading-none font-medium select-none group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50",
        className
      )}
      {...props}
    />
  )
}

export { Label }
```

---

# Menubar

A desktop-style bar of menus.

Docs: https://jds-ruddy.vercel.app/docs/components/menubar

## Installation

```bash
npx shadcn@latest add @jds/menubar
```

npm dependencies: `@base-ui/react`, `cn`

Also installs: `@jds/dropdown-menu`, `@jds/utils`

## Example

```tsx
import {
  Menubar,
  MenubarContent,
  MenubarItem,
  MenubarMenu,
  MenubarSeparator,
  MenubarShortcut,
  MenubarTrigger,
} from "@/components/ui/menubar"

export default function MenubarDemo() {
  return (
    <Menubar>
      <MenubarMenu>
        <MenubarTrigger>Conversation</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>
            New <MenubarShortcut>⌘N</MenubarShortcut>
          </MenubarItem>
          <MenubarItem>Duplicate</MenubarItem>
          <MenubarSeparator />
          <MenubarItem>Export as Markdown</MenubarItem>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>Agent</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>Switch model</MenubarItem>
          <MenubarItem>Tools…</MenubarItem>
          <MenubarItem>Memory…</MenubarItem>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>View</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>Show reasoning</MenubarItem>
          <MenubarItem>Show tool calls</MenubarItem>
        </MenubarContent>
      </MenubarMenu>
    </Menubar>
  )
}
```

## Source

### components/ui/menubar.tsx

```tsx
"use client"

import * as React from "react"
import { Menu as MenuPrimitive } from "@base-ui/react/menu"
import { Menubar as MenubarPrimitive } from "@base-ui/react/menubar"
import { cn } from "cn"

import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuPortal,
  DropdownMenuRadioGroup,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
import { CheckIcon } from "@/lib/icons"

function Menubar({ className, ...props }: MenubarPrimitive.Props) {
  return (
    <MenubarPrimitive
      data-slot="menubar"
      className={cn(
        "flex h-8 items-center gap-0.5 rounded-lg border p-[3px]",
        className
      )}
      {...props}
    />
  )
}

function MenubarMenu({ ...props }: React.ComponentProps<typeof DropdownMenu>) {
  return <DropdownMenu data-slot="menubar-menu" {...props} />
}

function MenubarGroup({
  ...props
}: React.ComponentProps<typeof DropdownMenuGroup>) {
  return <DropdownMenuGroup data-slot="menubar-group" {...props} />
}

function MenubarPortal({
  ...props
}: React.ComponentProps<typeof DropdownMenuPortal>) {
  return <DropdownMenuPortal data-slot="menubar-portal" {...props} />
}

function MenubarTrigger({
  className,
  ...props
}: React.ComponentProps<typeof DropdownMenuTrigger>) {
  return (
    <DropdownMenuTrigger
      data-slot="menubar-trigger"
      className={cn(
        "flex items-center rounded-sm px-1.5 py-[2px] text-sm font-medium outline-hidden select-none hover:bg-muted aria-expanded:bg-muted",
        className
      )}
      {...props}
    />
  )
}

function MenubarContent({
  className,
  align = "start",
  alignOffset = -4,
  sideOffset = 8,
  ...props
}: React.ComponentProps<typeof DropdownMenuContent>) {
  return (
    <DropdownMenuContent
      data-slot="menubar-content"
      align={align}
      alignOffset={alignOffset}
      sideOffset={sideOffset}
      className={cn("min-w-36 rounded-lg bg-popover p-1 text-popover-foreground shadow-md ring-1 ring-foreground/10 duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95", className )}
      {...props}
    />
  )
}

function MenubarItem({
  className,
  inset,
  variant = "default",
  ...props
}: React.ComponentProps<typeof DropdownMenuItem>) {
  return (
    <DropdownMenuItem
      data-slot="menubar-item"
      data-inset={inset}
      data-variant={variant}
      className={cn(
        "group/menubar-item gap-1.5 rounded-md px-1.5 py-1 text-sm focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-inset:pl-7 data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 data-[variant=destructive]:focus:text-destructive dark:data-[variant=destructive]:focus:bg-destructive/20 data-disabled:opacity-50 [&_svg:not([class*='size-'])]:size-4 data-[variant=destructive]:*:[svg]:text-destructive!",
        className
      )}
      {...props}
    />
  )
}

function MenubarCheckboxItem({
  className,
  children,
  checked,
  inset,
  ...props
}: MenuPrimitive.CheckboxItem.Props & {
  inset?: boolean
}) {
  return (
    <MenuPrimitive.CheckboxItem
      data-slot="menubar-checkbox-item"
      data-inset={inset}
      className={cn(
        "relative flex cursor-default items-center gap-1.5 rounded-md py-1 pr-1.5 pl-7 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground data-inset:pl-7 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0",
        className
      )}
      checked={checked}
      {...props}
    >
      <span className="pointer-events-none absolute left-1.5 flex size-4 items-center justify-center [&_svg:not([class*='size-'])]:size-4">
        <MenuPrimitive.CheckboxItemIndicator>
          <CheckIcon
          />
        </MenuPrimitive.CheckboxItemIndicator>
      </span>
      {children}
    </MenuPrimitive.CheckboxItem>
  )
}

function MenubarRadioGroup({
  ...props
}: React.ComponentProps<typeof DropdownMenuRadioGroup>) {
  return <DropdownMenuRadioGroup data-slot="menubar-radio-group" {...props} />
}

function MenubarRadioItem({
  className,
  children,
  inset,
  ...props
}: MenuPrimitive.RadioItem.Props & {
  inset?: boolean
}) {
  return (
    <MenuPrimitive.RadioItem
      data-slot="menubar-radio-item"
      data-inset={inset}
      className={cn(
        "relative flex cursor-default items-center gap-1.5 rounded-md py-1 pr-1.5 pl-7 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground data-inset:pl-7 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
        className
      )}
      {...props}
    >
      <span className="pointer-events-none absolute left-1.5 flex size-4 items-center justify-center [&_svg:not([class*='size-'])]:size-4">
        <MenuPrimitive.RadioItemIndicator>
          <CheckIcon
          />
        </MenuPrimitive.RadioItemIndicator>
      </span>
      {children}
    </MenuPrimitive.RadioItem>
  )
}

function MenubarLabel({
  className,
  inset,
  ...props
}: React.ComponentProps<typeof DropdownMenuLabel> & {
  inset?: boolean
}) {
  return (
    <DropdownMenuLabel
      data-slot="menubar-label"
      data-inset={inset}
      className={cn(
        "px-1.5 py-1 text-sm font-medium data-inset:pl-7",
        className
      )}
      {...props}
    />
  )
}

function MenubarSeparator({
  className,
  ...props
}: React.ComponentProps<typeof DropdownMenuSeparator>) {
  return (
    <DropdownMenuSeparator
      data-slot="menubar-separator"
      className={cn("-mx-1 my-1 h-px bg-border", className)}
      {...props}
    />
  )
}

function MenubarShortcut({
  className,
  ...props
}: React.ComponentProps<typeof DropdownMenuShortcut>) {
  return (
    <DropdownMenuShortcut
      data-slot="menubar-shortcut"
      className={cn(
        "ml-auto text-xs tracking-widest text-muted-foreground group-focus/menubar-item:text-accent-foreground",
        className
      )}
      {...props}
    />
  )
}

function MenubarSub({
  ...props
}: React.ComponentProps<typeof DropdownMenuSub>) {
  return <DropdownMenuSub data-slot="menubar-sub" {...props} />
}

function MenubarSubTrigger({
  className,
  inset,
  ...props
}: React.ComponentProps<typeof DropdownMenuSubTrigger> & {
  inset?: boolean
}) {
  return (
    <DropdownMenuSubTrigger
      data-slot="menubar-sub-trigger"
      data-inset={inset}
      className={cn(
        "gap-1.5 rounded-md px-1.5 py-1 text-sm focus:bg-accent focus:text-accent-foreground data-inset:pl-7 data-open:bg-accent data-open:text-accent-foreground [&_svg:not([class*='size-'])]:size-4",
        className
      )}
      {...props}
    />
  )
}

function MenubarSubContent({
  className,
  ...props
}: React.ComponentProps<typeof DropdownMenuSubContent>) {
  return (
    <DropdownMenuSubContent
      data-slot="menubar-sub-content"
      className={cn("min-w-32 rounded-lg bg-popover p-1 text-popover-foreground shadow-lg ring-1 ring-foreground/10 duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95", className )}
      {...props}
    />
  )
}

export {
  Menubar,
  MenubarPortal,
  MenubarMenu,
  MenubarTrigger,
  MenubarContent,
  MenubarGroup,
  MenubarSeparator,
  MenubarLabel,
  MenubarItem,
  MenubarShortcut,
  MenubarCheckboxItem,
  MenubarRadioGroup,
  MenubarRadioItem,
  MenubarSub,
  MenubarSubTrigger,
  MenubarSubContent,
}
```

---

# Pagination

Move between pages of results.

Docs: https://jds-ruddy.vercel.app/docs/components/pagination

## Installation

```bash
npx shadcn@latest add @jds/pagination
```

npm dependencies: `cn`

Also installs: `@jds/button`, `@jds/utils`

## Example

```tsx
import {
  Pagination,
  PaginationContent,
  PaginationEllipsis,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
} from "@/components/ui/pagination"

export default function PaginationDemo() {
  return (
    <Pagination>
      <PaginationContent>
        <PaginationItem>
          <PaginationPrevious href="#" />
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#">1</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#" isActive>
            2
          </PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#">3</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationEllipsis />
        </PaginationItem>
        <PaginationItem>
          <PaginationNext href="#" />
        </PaginationItem>
      </PaginationContent>
    </Pagination>
  )
}
```

## Source

### components/ui/pagination.tsx

```tsx
import * as React from "react"
import { cn } from "cn"

import { Button } from "@/components/ui/button"
import { ChevronLeftIcon, ChevronRightIcon, MoreIcon as MoreHorizontalIcon } from "@/lib/icons"

function Pagination({ className, ...props }: React.ComponentProps<"nav">) {
  return (
    <nav
      role="navigation"
      aria-label="pagination"
      data-slot="pagination"
      className={cn("mx-auto flex w-full justify-center", className)}
      {...props}
    />
  )
}

function PaginationContent({
  className,
  ...props
}: React.ComponentProps<"ul">) {
  return (
    <ul
      data-slot="pagination-content"
      className={cn("flex items-center gap-0.5", className)}
      {...props}
    />
  )
}

function PaginationItem({ ...props }: React.ComponentProps<"li">) {
  return <li data-slot="pagination-item" {...props} />
}

type PaginationLinkProps = {
  isActive?: boolean
} & Pick<React.ComponentProps<typeof Button>, "size"> &
  React.ComponentProps<"a">

function PaginationLink({
  className,
  isActive,
  size = "icon",
  ...props
}: PaginationLinkProps) {
  return (
    <Button
      variant={isActive ? "outline" : "ghost"}
      size={size}
      className={cn(className)}
      nativeButton={false}
      render={
        <a
          aria-current={isActive ? "page" : undefined}
          data-slot="pagination-link"
          data-active={isActive}
          {...props}
        />
      }
    />
  )
}

function PaginationPrevious({
  className,
  text = "Previous",
  ...props
}: React.ComponentProps<typeof PaginationLink> & { text?: string }) {
  return (
    <PaginationLink
      aria-label="Go to previous page"
      size="default"
      className={cn("pl-1.5!", className)}
      {...props}
    >
      <ChevronLeftIcon data-icon="inline-start" />
      <span className="hidden sm:block">{text}</span>
    </PaginationLink>
  )
}

function PaginationNext({
  className,
  text = "Next",
  ...props
}: React.ComponentProps<typeof PaginationLink> & { text?: string }) {
  return (
    <PaginationLink
      aria-label="Go to next page"
      size="default"
      className={cn("pr-1.5!", className)}
      {...props}
    >
      <span className="hidden sm:block">{text}</span>
      <ChevronRightIcon data-icon="inline-end" />
    </PaginationLink>
  )
}

function PaginationEllipsis({
  className,
  ...props
}: React.ComponentProps<"span">) {
  return (
    <span
      aria-hidden
      data-slot="pagination-ellipsis"
      className={cn(
        "flex size-8 items-center justify-center [&_svg:not([class*='size-'])]:size-4",
        className
      )}
      {...props}
    >
      <MoreHorizontalIcon
      />
      <span className="sr-only">More pages</span>
    </span>
  )
}

export {
  Pagination,
  PaginationContent,
  PaginationEllipsis,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
}
```

---

# Progress

Completion of a known-length task.

Docs: https://jds-ruddy.vercel.app/docs/components/progress

## Installation

```bash
npx shadcn@latest add @jds/progress
```

npm dependencies: `@base-ui/react`, `cn`

## Example

```tsx
"use client"

import * as React from "react"

import { Progress, ProgressLabel, ProgressValue } from "@/components/ui/progress"

export default function ProgressDemo() {
  const [value, setValue] = React.useState(12)
  React.useEffect(() => {
    const id = setInterval(() => setValue((v) => (v >= 100 ? 8 : Math.min(100, v + 9))), 700)
    return () => clearInterval(id)
  }, [])
  return (
    <Progress value={value} className="w-full max-w-sm">
      <ProgressLabel>Indexing documents</ProgressLabel>
      <ProgressValue />
    </Progress>
  )
}
```

## Source

### components/ui/progress.tsx

```tsx
"use client"

import { Progress as ProgressPrimitive } from "@base-ui/react/progress"
import { cn } from "cn"

function Progress({
  className,
  children,
  value,
  ...props
}: ProgressPrimitive.Root.Props) {
  return (
    <ProgressPrimitive.Root
      value={value}
      data-slot="progress"
      className={cn("flex flex-wrap gap-3", className)}
      {...props}
    >
      {children}
      <ProgressTrack>
        <ProgressIndicator />
      </ProgressTrack>
    </ProgressPrimitive.Root>
  )
}

function ProgressTrack({ className, ...props }: ProgressPrimitive.Track.Props) {
  return (
    <ProgressPrimitive.Track
      className={cn(
        "relative flex h-1 w-full items-center overflow-x-hidden rounded-full bg-muted",
        className
      )}
      data-slot="progress-track"
      {...props}
    />
  )
}

function ProgressIndicator({
  className,
  ...props
}: ProgressPrimitive.Indicator.Props) {
  return (
    <ProgressPrimitive.Indicator
      data-slot="progress-indicator"
      className={cn("h-full bg-primary transition-all", className)}
      {...props}
    />
  )
}

function ProgressLabel({ className, ...props }: ProgressPrimitive.Label.Props) {
  return (
    <ProgressPrimitive.Label
      className={cn("text-sm font-medium", className)}
      data-slot="progress-label"
      {...props}
    />
  )
}

function ProgressValue({ className, ...props }: ProgressPrimitive.Value.Props) {
  return (
    <ProgressPrimitive.Value
      className={cn(
        "ml-auto text-sm text-muted-foreground tabular-nums",
        className
      )}
      data-slot="progress-value"
      {...props}
    />
  )
}

export {
  Progress,
  ProgressTrack,
  ProgressIndicator,
  ProgressLabel,
  ProgressValue,
}
```

---

# Radio Group

Pick exactly one of a few options.

Docs: https://jds-ruddy.vercel.app/docs/components/radio-group

## Installation

```bash
npx shadcn@latest add @jds/radio-group
```

npm dependencies: `@base-ui/react`, `cn`

## Example

```tsx
import { Label } from "@/components/ui/label"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"

const options = [
  ["ask", "Ask every time"],
  ["risky", "Only for irreversible actions"],
  ["never", "Never ask"],
] as const

export default function RadioGroupDemo() {
  return (
    <RadioGroup defaultValue="risky">
      {options.map(([value, label]) => (
        <Label key={value}>
          <RadioGroupItem value={value} />
          {label}
        </Label>
      ))}
    </RadioGroup>
  )
}
```

## Source

### components/ui/radio-group.tsx

```tsx
"use client"

import { Radio as RadioPrimitive } from "@base-ui/react/radio"
import { RadioGroup as RadioGroupPrimitive } from "@base-ui/react/radio-group"
import { cn } from "cn"

function RadioGroup({ className, ...props }: RadioGroupPrimitive.Props) {
  return (
    <RadioGroupPrimitive
      data-slot="radio-group"
      className={cn("grid w-full gap-2", className)}
      {...props}
    />
  )
}

function RadioGroupItem({ className, ...props }: RadioPrimitive.Root.Props) {
  return (
    <RadioPrimitive.Root
      data-slot="radio-group-item"
      className={cn(
        "group/radio-group-item peer relative flex aspect-square size-4 shrink-0 rounded-full border border-input outline-none group-has-[:focus-visible]/field-label:ring-0 group-has-[:focus-visible]/field-label:not-data-checked:border-input after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 aria-invalid:aria-checked:border-primary dark:bg-input/30 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 data-checked:border-primary data-checked:bg-primary data-checked:text-primary-foreground group-has-[:focus-visible]/field-label:data-checked:border-primary dark:data-checked:bg-primary",
        className
      )}
      {...props}
    >
      <RadioPrimitive.Indicator
        data-slot="radio-group-indicator"
        className="flex size-4 items-center justify-center"
      >
        <span className="absolute top-1/2 left-1/2 size-2 -translate-x-1/2 -translate-y-1/2 rounded-full bg-primary-foreground" />
      </RadioPrimitive.Indicator>
    </RadioPrimitive.Root>
  )
}

export { RadioGroup, RadioGroupItem }
```

---

# Slider

Choose a value within a range.

Docs: https://jds-ruddy.vercel.app/docs/components/slider

## Installation

```bash
npx shadcn@latest add @jds/slider
```

npm dependencies: `@base-ui/react`, `cn`

## Example

```tsx
"use client"

import * as React from "react"

import { Slider } from "@/components/ui/slider"

export default function SliderDemo() {
  const [value, setValue] = React.useState(0.7)
  return (
    <div className="flex w-full max-w-xs flex-col gap-3">
      <div className="flex justify-between text-sm">
        <span>Temperature</span>
        <span className="font-mono text-muted-foreground tabular-nums">{value.toFixed(1)}</span>
      </div>
      <Slider value={value} onValueChange={(v) => setValue(v as number)} min={0} max={2} step={0.1} />
    </div>
  )
}
```

## Source

### components/ui/slider.tsx

```tsx
import { Slider as SliderPrimitive } from "@base-ui/react/slider"
import { cn } from "cn"

function Slider({
  className,
  defaultValue,
  value,
  min = 0,
  max = 100,
  ...props
}: SliderPrimitive.Root.Props) {
  const _values = Array.isArray(value)
    ? value
    : Array.isArray(defaultValue)
      ? defaultValue
      : [min, max]

return (
    <SliderPrimitive.Root
      className={cn("data-horizontal:w-full data-vertical:h-full", className)}
      data-slot="slider"
      defaultValue={defaultValue}
      value={value}
      min={min}
      max={max}
      thumbAlignment="edge"
      {...props}
    >
      <SliderPrimitive.Control className="relative flex w-full touch-none items-center select-none data-disabled:opacity-50 data-vertical:h-full data-vertical:min-h-40 data-vertical:w-auto data-vertical:flex-col">
        <SliderPrimitive.Track
          data-slot="slider-track"
          className="relative grow overflow-hidden rounded-full bg-muted select-none data-horizontal:h-1 data-horizontal:w-full data-vertical:h-full data-vertical:w-1"
        >
          <SliderPrimitive.Indicator
            data-slot="slider-range"
            className="bg-primary select-none data-horizontal:h-full data-vertical:w-full"
          />
        </SliderPrimitive.Track>
        {Array.from({ length: _values.length }, (_, index) => (
          <SliderPrimitive.Thumb
            data-slot="slider-thumb"
            key={index}
            className="relative block size-3 shrink-0 rounded-full border border-ring bg-white ring-ring/50 transition-[color,box-shadow] select-none after:absolute after:-inset-2 hover:ring-3 focus-visible:ring-3 focus-visible:outline-hidden active:ring-3 disabled:pointer-events-none disabled:opacity-50"
          />
        ))}
      </SliderPrimitive.Control>
    </SliderPrimitive.Root>
  )
}

export { Slider }
```

---

# Spinner

Indeterminate loading indicator.

Docs: https://jds-ruddy.vercel.app/docs/components/spinner

## Installation

```bash
npx shadcn@latest add @jds/spinner
```

npm dependencies: `cn`

Also installs: `@jds/utils`

## Example

```tsx
import { Button } from "@/components/ui/button"
import { Spinner } from "@/components/ui/spinner"

export default function SpinnerDemo() {
  return (
    <div className="flex items-center gap-4">
      <Spinner />
      <Button disabled size="sm">
        <Spinner />
        Connecting
      </Button>
    </div>
  )
}
```

## Source

### components/ui/spinner.tsx

```tsx
import { cn } from "cn"
import { SpinnerIcon as Loader2Icon } from "@/lib/icons"

function Spinner({ className, ...props }: React.ComponentProps<"svg">) {
  return (
    <Loader2Icon data-slot="spinner" role="status" aria-label="Loading" className={cn("size-4 animate-spin", className)} {...props} />
  )
}

export { Spinner }
```

---

# Switch

Turn a setting on or off, taking effect immediately.

Docs: https://jds-ruddy.vercel.app/docs/components/switch

## Installation

```bash
npx shadcn@latest add @jds/switch
```

npm dependencies: `@base-ui/react`, `cn`

## Example

```tsx
import { Label } from "@/components/ui/label"
import { Switch } from "@/components/ui/switch"

export default function SwitchDemo() {
  return (
    <div className="flex flex-col gap-3">
      <Label>
        <Switch defaultChecked />
        Voice mode
      </Label>
      <Label>
        <Switch />
        Memory
      </Label>
    </div>
  )
}
```

## Source

### components/ui/switch.tsx

```tsx
"use client"

import { Switch as SwitchPrimitive } from "@base-ui/react/switch"
import { cn } from "cn"

function Switch({
  className,
  size = "default",
  ...props
}: SwitchPrimitive.Root.Props & {
  size?: "sm" | "default"
}) {
  return (
    <SwitchPrimitive.Root
      data-slot="switch"
      data-size={size}
      className={cn(
        "peer group/switch relative inline-flex shrink-0 items-center rounded-full border border-transparent transition-all outline-none group-has-[:focus-visible]/field-label:border-transparent group-has-[:focus-visible]/field-label:ring-0 after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 data-[size=default]:h-[18.4px] data-[size=default]:w-[32px] data-[size=sm]:h-[14px] data-[size=sm]:w-[24px] dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 data-checked:bg-primary data-unchecked:bg-input dark:data-unchecked:bg-input/80 data-disabled:cursor-not-allowed data-disabled:opacity-50",
        className
      )}
      {...props}
    >
      <SwitchPrimitive.Thumb
        data-slot="switch-thumb"
        className="pointer-events-none block rounded-full bg-background ring-0 transition-transform group-data-[size=default]/switch:size-4 group-data-[size=sm]/switch:size-3 group-data-[size=default]/switch:data-checked:translate-x-[calc(100%-2px)] group-data-[size=sm]/switch:data-checked:translate-x-[calc(100%-2px)] dark:data-checked:bg-primary-foreground group-data-[size=default]/switch:data-unchecked:translate-x-0 group-data-[size=sm]/switch:data-unchecked:translate-x-0 dark:data-unchecked:bg-foreground"
      />
    </SwitchPrimitive.Root>
  )
}

export { Switch }
```

---

# Table

Rows and columns of structured data.

Docs: https://jds-ruddy.vercel.app/docs/components/table

## Installation

```bash
npx shadcn@latest add @jds/table
```

npm dependencies: `cn`

## Example

```tsx
import { Badge } from "@/components/ui/badge"
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table"

const runs = [
  { id: "#1284", agent: "Support", status: "Completed", tokens: "18.2k" },
  { id: "#1283", agent: "Researcher", status: "Running", tokens: "42.9k" },
  { id: "#1282", agent: "Support", status: "Needs approval", tokens: "7.4k" },
  { id: "#1281", agent: "Reviewer", status: "Failed", tokens: "3.1k" },
]

export default function TableDemo() {
  return (
    <Table className="max-w-lg">
      <TableHeader>
        <TableRow>
          <TableHead>Run</TableHead>
          <TableHead>Agent</TableHead>
          <TableHead>Status</TableHead>
          <TableHead className="text-right">Tokens</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        {runs.map((r) => (
          <TableRow key={r.id}>
            <TableCell>
              <span className="font-mono">{r.id}</span>
            </TableCell>
            <TableCell>{r.agent}</TableCell>
            <TableCell>
              <Badge variant={r.status === "Failed" ? "destructive" : "secondary"}>{r.status}</Badge>
            </TableCell>
            <TableCell className="text-right">
              <span className="font-mono tabular-nums">{r.tokens}</span>
            </TableCell>
          </TableRow>
        ))}
      </TableBody>
    </Table>
  )
}
```

## Source

### components/ui/table.tsx

```tsx
"use client"

import * as React from "react"
import { cn } from "cn"

function Table({ className, ...props }: React.ComponentProps<"table">) {
  return (
    <div
      data-slot="table-container"
      className="relative w-full overflow-x-auto"
    >
      <table
        data-slot="table"
        className={cn("w-full caption-bottom text-sm", className)}
        {...props}
      />
    </div>
  )
}

function TableHeader({ className, ...props }: React.ComponentProps<"thead">) {
  return (
    <thead
      data-slot="table-header"
      className={cn("[&_tr]:border-b", className)}
      {...props}
    />
  )
}

function TableBody({ className, ...props }: React.ComponentProps<"tbody">) {
  return (
    <tbody
      data-slot="table-body"
      className={cn("[&_tr:last-child]:border-0", className)}
      {...props}
    />
  )
}

function TableFooter({ className, ...props }: React.ComponentProps<"tfoot">) {
  return (
    <tfoot
      data-slot="table-footer"
      className={cn(
        "border-t bg-muted/50 font-medium [&>tr]:last:border-b-0",
        className
      )}
      {...props}
    />
  )
}

function TableRow({ className, ...props }: React.ComponentProps<"tr">) {
  return (
    <tr
      data-slot="table-row"
      className={cn(
        "border-b transition-colors hover:bg-muted/50 has-aria-expanded:bg-muted/50 data-[state=selected]:bg-muted",
        className
      )}
      {...props}
    />
  )
}

function TableHead({ className, ...props }: React.ComponentProps<"th">) {
  return (
    <th
      data-slot="table-head"
      className={cn(
        "h-10 px-2 text-left align-middle font-medium whitespace-nowrap text-foreground [&:has([role=checkbox])]:pr-0",
        className
      )}
      {...props}
    />
  )
}

function TableCell({ className, ...props }: React.ComponentProps<"td">) {
  return (
    <td
      data-slot="table-cell"
      className={cn(
        "p-2 align-middle whitespace-nowrap [&:has([role=checkbox])]:pr-0",
        className
      )}
      {...props}
    />
  )
}

function TableCaption({
  className,
  ...props
}: React.ComponentProps<"caption">) {
  return (
    <caption
      data-slot="table-caption"
      className={cn("mt-4 text-sm text-muted-foreground", className)}
      {...props}
    />
  )
}

export {
  Table,
  TableHeader,
  TableBody,
  TableFooter,
  TableHead,
  TableRow,
  TableCell,
  TableCaption,
}
```

---

# Toggle

A button that stays pressed.

Docs: https://jds-ruddy.vercel.app/docs/components/toggle

## Installation

```bash
npx shadcn@latest add @jds/toggle
```

npm dependencies: `@base-ui/react`, `class-variance-authority`, `cn`

## Example

```tsx
import { Toggle } from "@/components/ui/toggle"
import { WebSearchIcon } from "@/lib/icons"

export default function ToggleDemo() {
  return (
    <Toggle aria-label="Web search" variant="outline">
      <WebSearchIcon />
      Web search
    </Toggle>
  )
}
```

## Source

### components/ui/toggle.tsx

```tsx
"use client"

import { Toggle as TogglePrimitive } from "@base-ui/react/toggle"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "cn"

const toggleVariants = cva(
  "group/toggle inline-flex items-center justify-center gap-1 rounded-lg text-sm font-medium whitespace-nowrap transition-all outline-none hover:bg-muted hover:text-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 aria-pressed:bg-foreground/10 aria-pressed:text-foreground data-pressed:bg-foreground/10 data-pressed:text-foreground dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
  {
    variants: {
      variant: {
        default: "bg-transparent",
        outline:
          "border border-input bg-transparent hover:bg-muted aria-pressed:border-foreground/30 data-pressed:border-foreground/30",
      },
      size: {
        default: "h-8 min-w-8 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
        sm: "h-7 min-w-7 rounded-[min(var(--radius-md),12px)] px-2.5 text-[0.8rem] has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3.5",
        lg: "h-9 min-w-9 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  },
)

function Toggle({
  className,
  variant = "default",
  size = "default",
  ...props
}: TogglePrimitive.Props & VariantProps<typeof toggleVariants>) {
  return <TogglePrimitive data-slot="toggle" className={cn(toggleVariants({ variant, size, className }))} {...props} />
}

export { Toggle, toggleVariants }
```

---

# Toggle Group

A set of toggles, single or multiple choice.

Docs: https://jds-ruddy.vercel.app/docs/components/toggle-group

## Installation

```bash
npx shadcn@latest add @jds/toggle-group
```

npm dependencies: `@base-ui/react`, `class-variance-authority`, `cn`

Also installs: `@jds/toggle`

## Example

```tsx
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"

export default function ToggleGroupDemo() {
  return (
    <ToggleGroup defaultValue={["chat"]} variant="outline">
      <ToggleGroupItem value="chat">Chat</ToggleGroupItem>
      <ToggleGroupItem value="voice">Voice</ToggleGroupItem>
      <ToggleGroupItem value="agent">Agent</ToggleGroupItem>
    </ToggleGroup>
  )
}
```

## Source

### components/ui/toggle-group.tsx

```tsx
"use client"

import * as React from "react"
import { Toggle as TogglePrimitive } from "@base-ui/react/toggle"
import { ToggleGroup as ToggleGroupPrimitive } from "@base-ui/react/toggle-group"
import { type VariantProps } from "class-variance-authority"
import { cn } from "cn"

import { toggleVariants } from "@/components/ui/toggle"

const ToggleGroupContext = React.createContext<
  VariantProps<typeof toggleVariants> & {
    spacing?: number
    orientation?: "horizontal" | "vertical"
  }
>({
  size: "default",
  variant: "default",
  spacing: 2,
  orientation: "horizontal",
})

function ToggleGroup({
  className,
  variant,
  size,
  spacing = 2,
  orientation = "horizontal",
  children,
  ...props
}: ToggleGroupPrimitive.Props &
  VariantProps<typeof toggleVariants> & {
    spacing?: number
    orientation?: "horizontal" | "vertical"
  }) {
  return (
    <ToggleGroupPrimitive
      data-slot="toggle-group"
      data-variant={variant}
      data-size={size}
      data-spacing={spacing}
      data-orientation={orientation}
      style={{ "--gap": spacing } as React.CSSProperties}
      className={cn(
        "group/toggle-group flex w-fit flex-row items-center gap-[--spacing(var(--gap))] rounded-lg data-[size=sm]:rounded-[min(var(--radius-md),10px)] data-vertical:flex-col data-vertical:items-stretch",
        className
      )}
      {...props}
    >
      <ToggleGroupContext.Provider
        value={{ variant, size, spacing, orientation }}
      >
        {children}
      </ToggleGroupContext.Provider>
    </ToggleGroupPrimitive>
  )
}

function ToggleGroupItem({
  className,
  children,
  variant = "default",
  size = "default",
  ...props
}: TogglePrimitive.Props & VariantProps<typeof toggleVariants>) {
  const context = React.useContext(ToggleGroupContext)

return (
    <TogglePrimitive
      data-slot="toggle-group-item"
      data-variant={context.variant || variant}
      data-size={context.size || size}
      data-spacing={context.spacing}
      className={cn(
        "shrink-0 group-data-[spacing=0]/toggle-group:rounded-none group-data-[spacing=0]/toggle-group:px-2 focus:z-10 focus-visible:z-10 group-data-[spacing=0]/toggle-group:has-data-[icon=inline-end]:pr-1.5 group-data-[spacing=0]/toggle-group:has-data-[icon=inline-start]:pl-1.5 group-data-horizontal/toggle-group:data-[spacing=0]:first:rounded-l-lg group-data-vertical/toggle-group:data-[spacing=0]:first:rounded-t-lg group-data-horizontal/toggle-group:data-[spacing=0]:last:rounded-r-lg group-data-vertical/toggle-group:data-[spacing=0]:last:rounded-b-lg group-data-horizontal/toggle-group:data-[spacing=0]:data-[variant=outline]:border-l-0 group-data-vertical/toggle-group:data-[spacing=0]:data-[variant=outline]:border-t-0 group-data-horizontal/toggle-group:data-[spacing=0]:data-[variant=outline]:first:border-l group-data-vertical/toggle-group:data-[spacing=0]:data-[variant=outline]:first:border-t",
        toggleVariants({
          variant: context.variant || variant,
          size: context.size || size,
        }),
        className
      )}
      {...props}
    >
      {children}
    </TogglePrimitive>
  )
}

export { ToggleGroup, ToggleGroupItem }
```

---

# Calendar

A month grid for picking a date or range.

Docs: https://jds-ruddy.vercel.app/docs/components/calendar

## Installation

```bash
npx shadcn@latest add @jds/calendar
```

npm dependencies: `cn`, `react-day-picker`

Also installs: `@jds/button`, `@jds/utils`

## Example

```tsx
"use client"

import * as React from "react"

import { Calendar } from "@/components/ui/calendar"

export default function CalendarDemo() {
  // A fixed date keeps the demo (and its screenshot test) stable; use new Date() in your app.
  const [date, setDate] = React.useState<Date | undefined>(new Date(2026, 8, 15))
  return (
    <div className="rounded-xl border">
      <Calendar mode="single" selected={date} onSelect={setDate} defaultMonth={new Date(2026, 8, 1)} />
    </div>
  )
}
```

### Date picker

```tsx
"use client"

import * as React from "react"
import { format } from "date-fns"

import { Button } from "@/components/ui/button"
import { Calendar } from "@/components/ui/calendar"
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"
import { ChevronDownIcon } from "@/lib/icons"

export default function DatePickerDemo() {
  const [date, setDate] = React.useState<Date>()
  const [open, setOpen] = React.useState(false)
  return (
    <div className="flex flex-col gap-2">
      <span className="text-sm font-medium">Schedule the report</span>
      <Popover open={open} onOpenChange={setOpen}>
        <PopoverTrigger render={<Button variant="outline" className="w-56 justify-between" />}>
          {date ? format(date, "PPP") : "Pick a date"}
          <ChevronDownIcon />
        </PopoverTrigger>
        <PopoverContent className="w-auto" align="start">
          <Calendar
            mode="single"
            selected={date}
            onSelect={(d) => {
              setDate(d)
              setOpen(false)
            }}
          />
        </PopoverContent>
      </Popover>
    </div>
  )
}
```

## Source

### components/ui/calendar.tsx

```tsx
"use client"

import * as React from "react"
import { cn } from "cn"
import {
  DayPicker,
  getDefaultClassNames,
  type DayButton,
  type Locale,
} from "react-day-picker"

import { Button, buttonVariants } from "@/components/ui/button"
import { ChevronLeftIcon, ChevronRightIcon, ChevronDownIcon } from "@/lib/icons"

function Calendar({
  className,
  classNames,
  showOutsideDays = true,
  captionLayout = "label",
  buttonVariant = "ghost",
  locale,
  formatters,
  components,
  ...props
}: React.ComponentProps<typeof DayPicker> & {
  buttonVariant?: React.ComponentProps<typeof Button>["variant"]
}) {
  const defaultClassNames = getDefaultClassNames()

return (
    <DayPicker
      showOutsideDays={showOutsideDays}
      className={cn(
        "group/calendar bg-transparent p-2 [--cell-radius:var(--radius-md)] [--cell-size:--spacing(7)]",
        String.raw`rtl:**:[.rdp-button\_next>svg]:rotate-180`,
        String.raw`rtl:**:[.rdp-button\_previous>svg]:rotate-180`,
        className
      )}
      captionLayout={captionLayout}
      locale={locale}
      formatters={{
        formatMonthDropdown: (date) =>
          date.toLocaleString(locale?.code, { month: "short" }),
        ...formatters,
      }}
      classNames={{
        root: cn("w-fit", defaultClassNames.root),
        months: cn(
          "relative flex flex-col gap-4 md:flex-row",
          defaultClassNames.months
        ),
        month: cn("flex w-full flex-col gap-4", defaultClassNames.month),
        nav: cn(
          "absolute inset-x-0 top-0 flex w-full items-center justify-between gap-1",
          defaultClassNames.nav
        ),
        button_previous: cn(
          buttonVariants({ variant: buttonVariant }),
          "size-(--cell-size) p-0 select-none aria-disabled:opacity-50",
          defaultClassNames.button_previous
        ),
        button_next: cn(
          buttonVariants({ variant: buttonVariant }),
          "size-(--cell-size) p-0 select-none aria-disabled:opacity-50",
          defaultClassNames.button_next
        ),
        month_caption: cn(
          "flex h-(--cell-size) w-full items-center justify-center px-(--cell-size)",
          defaultClassNames.month_caption
        ),
        dropdowns: cn(
          "flex h-(--cell-size) w-full items-center justify-center gap-1.5 text-sm font-medium",
          defaultClassNames.dropdowns
        ),
        dropdown_root: cn(
          "relative rounded-(--cell-radius)",
          defaultClassNames.dropdown_root
        ),
        dropdown: cn(
          "absolute inset-0 bg-popover opacity-0",
          defaultClassNames.dropdown
        ),
        caption_label: cn(
          "font-medium select-none",
          captionLayout === "label"
            ? "text-sm"
            : "flex items-center gap-1 rounded-(--cell-radius) text-sm [&>svg]:size-3.5 [&>svg]:text-muted-foreground",
          defaultClassNames.caption_label
        ),
        month_grid: cn("w-full border-collapse", defaultClassNames.month_grid),
        weekdays: cn("flex", defaultClassNames.weekdays),
        weekday: cn(
          "flex-1 rounded-(--cell-radius) text-[0.8rem] font-normal text-muted-foreground select-none",
          defaultClassNames.weekday
        ),
        week: cn("mt-2 flex w-full", defaultClassNames.week),
        week_number_header: cn(
          "w-(--cell-size) select-none",
          defaultClassNames.week_number_header
        ),
        week_number: cn(
          "text-[0.8rem] text-muted-foreground select-none",
          defaultClassNames.week_number
        ),
        day: cn(
          "group/day relative aspect-square h-full w-full rounded-(--cell-radius) p-0 text-center select-none [&:last-child[data-selected=true]_button]:rounded-r-(--cell-radius)",
          props.showWeekNumber
            ? "[&:nth-child(2)[data-selected=true]_button]:rounded-l-(--cell-radius)"
            : "[&:first-child[data-selected=true]_button]:rounded-l-(--cell-radius)",
          defaultClassNames.day
        ),
        range_start: cn(
          "relative isolate z-0 rounded-l-(--cell-radius) bg-muted after:absolute after:inset-y-0 after:right-0 after:w-4 after:bg-muted",
          defaultClassNames.range_start
        ),
        range_middle: cn("rounded-none", defaultClassNames.range_middle),
        range_end: cn(
          "relative isolate z-0 rounded-r-(--cell-radius) bg-muted after:absolute after:inset-y-0 after:left-0 after:w-4 after:bg-muted",
          defaultClassNames.range_end
        ),
        today: cn(
          "rounded-(--cell-radius) bg-muted text-foreground data-[selected=true]:bg-transparent",
          defaultClassNames.today
        ),
        outside: cn(
          "text-muted-foreground aria-selected:text-muted-foreground",
          defaultClassNames.outside
        ),
        disabled: cn(
          "text-muted-foreground opacity-50",
          defaultClassNames.disabled
        ),
        hidden: cn("invisible", defaultClassNames.hidden),
        ...classNames,
      }}
      components={{
        Root: ({ className, rootRef, ...props }) => {
          return (
            <div
              data-slot="calendar"
              ref={rootRef}
              className={cn(className)}
              {...props}
            />
          )
        },
        Chevron: ({ className, orientation, ...props }) => {
          if (orientation === "left") {
            return (
              <ChevronLeftIcon className={cn("size-4", className)} {...props} />
            )
          }

if (orientation === "right") {
            return (
              <ChevronRightIcon className={cn("size-4", className)} {...props} />
            )
          }

return (
            <ChevronDownIcon className={cn("size-4", className)} {...props} />
          )
        },
        DayButton: ({ ...props }) => (
          <CalendarDayButton locale={locale} {...props} />
        ),
        WeekNumber: ({ children, ...props }) => {
          return (
            <td {...props}>
              <div className="flex size-(--cell-size) items-center justify-center text-center">
                {children}
              </div>
            </td>
          )
        },
        ...components,
      }}
      {...props}
    />
  )
}

function CalendarDayButton({
  className,
  day,
  modifiers,
  locale,
  ...props
}: React.ComponentProps<typeof DayButton> & { locale?: Partial<Locale> }) {
  const defaultClassNames = getDefaultClassNames()

const ref = React.useRef<HTMLButtonElement>(null)
  React.useEffect(() => {
    if (modifiers.focused) ref.current?.focus()
  }, [modifiers.focused])

return (
    <Button
      variant="ghost"
      size="icon"
      data-day={day.date.toLocaleDateString(locale?.code)}
      data-selected-single={
        modifiers.selected &&
        !modifiers.range_start &&
        !modifiers.range_end &&
        !modifiers.range_middle
      }
      data-range-start={modifiers.range_start}
      data-range-end={modifiers.range_end}
      data-range-middle={modifiers.range_middle}
      className={cn(
        "relative isolate z-10 flex aspect-square size-auto w-full min-w-(--cell-size) flex-col gap-1 border-0 leading-none font-normal group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-[3px] group-data-[focused=true]/day:ring-ring/50 data-[range-end=true]:rounded-(--cell-radius) data-[range-end=true]:rounded-r-(--cell-radius) data-[range-end=true]:bg-primary data-[range-end=true]:text-primary-foreground data-[range-middle=true]:rounded-none data-[range-middle=true]:bg-muted data-[range-middle=true]:text-foreground data-[range-start=true]:rounded-(--cell-radius) data-[range-start=true]:rounded-l-(--cell-radius) data-[range-start=true]:bg-primary data-[range-start=true]:text-primary-foreground data-[selected-single=true]:bg-primary data-[selected-single=true]:text-primary-foreground dark:hover:text-foreground [&>span]:text-xs [&>span]:opacity-70",
        defaultClassNames.day,
        className
      )}
      {...props}
    />
  )
}

export { Calendar, CalendarDayButton }
```

---

# Carousel

Swipe or step through a row of cards.

Docs: https://jds-ruddy.vercel.app/docs/components/carousel

## Installation

```bash
npx shadcn@latest add @jds/carousel
```

npm dependencies: `cn`, `embla-carousel-react`

Also installs: `@jds/button`, `@jds/utils`

## Example

```tsx
import { Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious } from "@/components/ui/carousel"

const prompts = [
  ["Summarize", "Turn a long thread into three bullet points."],
  ["Draft", "Write a reply in your tone, ready to send."],
  ["Research", "Find sources and compare the options."],
  ["Plan", "Break a goal into steps with owners and dates."],
  ["Review", "Check a document for gaps and risky claims."],
] as const

export default function CarouselDemo() {
  return (
    <Carousel className="w-full max-w-xs">
      <CarouselContent>
        {prompts.map(([title, body]) => (
          <CarouselItem key={title}>
            <div className="flex aspect-4/3 flex-col justify-end gap-1 rounded-xl border bg-card p-5">
              <span className="text-lg font-semibold">{title}</span>
              <span className="text-sm text-muted-foreground">{body}</span>
            </div>
          </CarouselItem>
        ))}
      </CarouselContent>
      <CarouselPrevious />
      <CarouselNext />
    </Carousel>
  )
}
```

## Source

### components/ui/carousel.tsx

```tsx
"use client"

import * as React from "react"
import { cn } from "cn"
import useEmblaCarousel, {
  type UseEmblaCarouselType,
} from "embla-carousel-react"

import { Button } from "@/components/ui/button"
import { ChevronLeftIcon, ChevronRightIcon } from "@/lib/icons"

type CarouselApi = UseEmblaCarouselType[1]
type UseCarouselParameters = Parameters<typeof useEmblaCarousel>
type CarouselOptions = UseCarouselParameters[0]
type CarouselPlugin = UseCarouselParameters[1]

type CarouselProps = {
  opts?: CarouselOptions
  plugins?: CarouselPlugin
  orientation?: "horizontal" | "vertical"
  setApi?: (api: CarouselApi) => void
}

type CarouselContextProps = {
  carouselRef: ReturnType<typeof useEmblaCarousel>[0]
  api: ReturnType<typeof useEmblaCarousel>[1]
  scrollPrev: () => void
  scrollNext: () => void
  canScrollPrev: boolean
  canScrollNext: boolean
} & CarouselProps

const CarouselContext = React.createContext<CarouselContextProps | null>(null)

function useCarousel() {
  const context = React.useContext(CarouselContext)

if (!context) {
    throw new Error("useCarousel must be used within a <Carousel />")
  }

return context
}

function Carousel({
  orientation = "horizontal",
  opts,
  setApi,
  plugins,
  className,
  children,
  ...props
}: React.ComponentProps<"div"> & CarouselProps) {
  const [carouselRef, api] = useEmblaCarousel(
    {
      ...opts,
      axis: orientation === "horizontal" ? "x" : "y",
    },
    plugins
  )
  const [canScrollPrev, setCanScrollPrev] = React.useState(false)
  const [canScrollNext, setCanScrollNext] = React.useState(false)

const onSelect = React.useCallback((api: CarouselApi) => {
    if (!api) return
    setCanScrollPrev(api.canScrollPrev())
    setCanScrollNext(api.canScrollNext())
  }, [])

const scrollPrev = React.useCallback(() => {
    api?.scrollPrev()
  }, [api])

const scrollNext = React.useCallback(() => {
    api?.scrollNext()
  }, [api])

const handleKeyDown = React.useCallback(
    (event: React.KeyboardEvent<HTMLDivElement>) => {
      if (event.key === "ArrowLeft") {
        event.preventDefault()
        scrollPrev()
      } else if (event.key === "ArrowRight") {
        event.preventDefault()
        scrollNext()
      }
    },
    [scrollPrev, scrollNext]
  )

React.useEffect(() => {
    if (!api || !setApi) return
    setApi(api)
  }, [api, setApi])

React.useEffect(() => {
    if (!api) return
    // Read the initial scroll state after mount, not synchronously inside the effect.
    queueMicrotask(() => onSelect(api))
    api.on("reInit", onSelect)
    api.on("select", onSelect)

return () => {
      api.off("reInit", onSelect)
      api.off("select", onSelect)
    }
  }, [api, onSelect])

return (
    <CarouselContext.Provider
      value={{
        carouselRef,
        api: api,
        opts,
        orientation:
          orientation || (opts?.axis === "y" ? "vertical" : "horizontal"),
        scrollPrev,
        scrollNext,
        canScrollPrev,
        canScrollNext,
      }}
    >
      <div
        onKeyDownCapture={handleKeyDown}
        className={cn("relative", className)}
        role="region"
        aria-roledescription="carousel"
        data-slot="carousel"
        {...props}
      >
        {children}
      </div>
    </CarouselContext.Provider>
  )
}

function CarouselContent({ className, ...props }: React.ComponentProps<"div">) {
  const { carouselRef, orientation } = useCarousel()

return (
    <div
      ref={carouselRef}
      className="overflow-hidden"
      data-slot="carousel-content"
    >
      <div
        className={cn(
          "flex",
          orientation === "horizontal" ? "-ml-4" : "-mt-4 flex-col",
          className
        )}
        {...props}
      />
    </div>
  )
}

function CarouselItem({ className, ...props }: React.ComponentProps<"div">) {
  const { orientation } = useCarousel()

return (
    <div
      role="group"
      aria-roledescription="slide"
      data-slot="carousel-item"
      className={cn(
        "min-w-0 shrink-0 grow-0 basis-full",
        orientation === "horizontal" ? "pl-4" : "pt-4",
        className
      )}
      {...props}
    />
  )
}

function CarouselPrevious({
  className,
  variant = "outline",
  size = "icon-sm",
  ...props
}: React.ComponentProps<typeof Button>) {
  const { orientation, scrollPrev, canScrollPrev } = useCarousel()

return (
    <Button
      data-slot="carousel-previous"
      variant={variant}
      size={size}
      className={cn(
        "absolute touch-manipulation rounded-full",
        orientation === "horizontal"
          ? "inset-y-0 -left-12 my-auto"
          : "-top-12 left-1/2 -translate-x-1/2 rotate-90",
        className
      )}
      disabled={!canScrollPrev}
      onClick={scrollPrev}
      {...props}
    >
      <ChevronLeftIcon />
      <span className="sr-only">Previous slide</span>
    </Button>
  )
}

function CarouselNext({
  className,
  variant = "outline",
  size = "icon-sm",
  ...props
}: React.ComponentProps<typeof Button>) {
  const { orientation, scrollNext, canScrollNext } = useCarousel()

return (
    <Button
      data-slot="carousel-next"
      variant={variant}
      size={size}
      className={cn(
        "absolute touch-manipulation rounded-full",
        orientation === "horizontal"
          ? "inset-y-0 -right-12 my-auto"
          : "-bottom-12 left-1/2 -translate-x-1/2 rotate-90",
        className
      )}
      disabled={!canScrollNext}
      onClick={scrollNext}
      {...props}
    >
      <ChevronRightIcon />
      <span className="sr-only">Next slide</span>
    </Button>
  )
}

export {
  type CarouselApi,
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselPrevious,
  CarouselNext,
  useCarousel,
}
```

---

# Form

Consistent form layout with native validation, built on Base UI Form.

Docs: https://jds-ruddy.vercel.app/docs/components/form

## Installation

```bash
npx shadcn@latest add @jds/form
```

npm dependencies: `@base-ui/react`, `cn`

## Example

```tsx
"use client"

import * as React from "react"
import { toast } from "sonner"

import { Button } from "@/components/ui/button"
import { Field, FieldDescription, FieldError, FieldLabel } from "@/components/ui/field"
import { Form } from "@/components/ui/form"
import { Input } from "@/components/ui/input"
import { Textarea } from "@/components/ui/textarea"

type Errors = Partial<Record<"name" | "webhook", string>>

export default function FormDemo() {
  const [errors, setErrors] = React.useState<Errors>({})

return (
    <Form
      className="max-w-sm"
      onSubmit={(e) => {
        e.preventDefault()
        const data = new FormData(e.currentTarget)
        const next: Errors = {}
        if (!String(data.get("name")).trim()) next.name = "Give the agent a name."
        const url = String(data.get("webhook"))
        if (url && !url.startsWith("https://")) next.webhook = "Webhooks must use https."
        setErrors(next)
        if (Object.keys(next).length === 0) toast("Agent created")
      }}
    >
      <Field data-invalid={!!errors.name || undefined}>
        <FieldLabel htmlFor="form-name">Name</FieldLabel>
        <Input id="form-name" name="name" placeholder="Support agent" aria-invalid={!!errors.name} />
        <FieldError>{errors.name}</FieldError>
      </Field>
      <Field>
        <FieldLabel htmlFor="form-prompt">Instructions</FieldLabel>
        <Textarea id="form-prompt" name="prompt" placeholder="Be concise. Ask before refunds." />
      </Field>
      <Field data-invalid={!!errors.webhook || undefined}>
        <FieldLabel htmlFor="form-webhook">Webhook</FieldLabel>
        <Input id="form-webhook" name="webhook" placeholder="https://…" aria-invalid={!!errors.webhook} />
        {errors.webhook ? (
          <FieldError>{errors.webhook}</FieldError>
        ) : (
          <FieldDescription>Called when a run finishes. Optional.</FieldDescription>
        )}
      </Field>
      <Button type="submit" className="self-start">
        Create agent
      </Button>
    </Form>
  )
}
```

## Source

### components/ui/form.tsx

```tsx
"use client"

import { Form as FormPrimitive } from "@base-ui/react/form"
import { cn } from "cn"

/**
 * A form with consistent spacing that works with <Field> parts. Built on Base UI Form:
 * native constraint validation (required, type, min…) and the first invalid control
 * is focused on submit. Pass `errors` (by field name) to show server-side errors.
 */
function Form({ className, ...props }: FormPrimitive.Props) {
  return <FormPrimitive data-slot="form" className={cn("flex w-full flex-col gap-6", className)} {...props} />
}

export { Form }
```

---

# Meter

A measurement within a known range, like quota used.

Docs: https://jds-ruddy.vercel.app/docs/components/meter

## Installation

```bash
npx shadcn@latest add @jds/meter
```

npm dependencies: `@base-ui/react`, `cn`

## Example

```tsx
import { Meter, MeterLabel, MeterValue } from "@/components/ui/meter"

export default function MeterDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-6">
      <Meter value={62}>
        <MeterLabel>Monthly credits</MeterLabel>
        <MeterValue />
      </Meter>
      <Meter value={18_400} max={25_000} format={{ notation: "compact" }}>
        <MeterLabel>Knowledge base</MeterLabel>
        <MeterValue>{(formatted) => `${formatted} of 25K chunks`}</MeterValue>
      </Meter>
    </div>
  )
}
```

## Source

### components/ui/meter.tsx

```tsx
"use client"

import { Meter as MeterPrimitive } from "@base-ui/react/meter"
import { cn } from "cn"

/**
 * A measurement within a known range, like storage or quota used. Unlike Progress,
 * it isn't a task moving toward done. Label and value sit above the track.
 */
function Meter({ className, children, ...props }: MeterPrimitive.Root.Props) {
  return (
    <MeterPrimitive.Root data-slot="meter" className={cn("flex flex-wrap gap-x-3 gap-y-2", className)} {...props}>
      {children}
      <MeterTrack>
        <MeterIndicator />
      </MeterTrack>
    </MeterPrimitive.Root>
  )
}

function MeterTrack({ className, ...props }: MeterPrimitive.Track.Props) {
  return (
    <MeterPrimitive.Track
      data-slot="meter-track"
      className={cn("relative h-1.5 w-full basis-full overflow-hidden rounded-full bg-muted", className)}
      {...props}
    />
  )
}

function MeterIndicator({ className, ...props }: MeterPrimitive.Indicator.Props) {
  return (
    <MeterPrimitive.Indicator
      data-slot="meter-indicator"
      className={cn("h-full rounded-full bg-primary transition-[width] duration-300", className)}
      {...props}
    />
  )
}

function MeterLabel({ className, ...props }: MeterPrimitive.Label.Props) {
  return <MeterPrimitive.Label data-slot="meter-label" className={cn("text-sm font-medium", className)} {...props} />
}

function MeterValue({ className, ...props }: MeterPrimitive.Value.Props) {
  return (
    <MeterPrimitive.Value
      data-slot="meter-value"
      className={cn("ml-auto text-sm text-muted-foreground tabular-nums", className)}
      {...props}
    />
  )
}

export { Meter, MeterTrack, MeterIndicator, MeterLabel, MeterValue }
```

---

# Navigation Menu

Top-level site navigation with rich dropdowns.

Docs: https://jds-ruddy.vercel.app/docs/components/navigation-menu

## Installation

```bash
npx shadcn@latest add @jds/navigation-menu
```

npm dependencies: `@base-ui/react`, `class-variance-authority`, `cn`

Also installs: `@jds/utils`

## Example

```tsx
import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
} from "@/components/ui/navigation-menu"

const agents = [
  ["Support", "Answers customers and handles refunds with approval."],
  ["Researcher", "Searches the web and your docs, with citations."],
  ["Reviewer", "Reads pull requests and flags risky changes."],
] as const

export default function NavigationMenuDemo() {
  return (
    <NavigationMenu>
      <NavigationMenuList>
        <NavigationMenuItem>
          <NavigationMenuTrigger>Agents</NavigationMenuTrigger>
          <NavigationMenuContent>
            <ul className="grid w-96 gap-1 p-1">
              {agents.map(([title, body]) => (
                <li key={title}>
                  <NavigationMenuLink href="#">
                    <div className="text-sm font-medium">{title}</div>
                    <p className="text-sm text-muted-foreground">{body}</p>
                  </NavigationMenuLink>
                </li>
              ))}
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem>
          <NavigationMenuLink href="#">Runs</NavigationMenuLink>
        </NavigationMenuItem>
        <NavigationMenuItem>
          <NavigationMenuLink href="#">Settings</NavigationMenuLink>
        </NavigationMenuItem>
      </NavigationMenuList>
    </NavigationMenu>
  )
}
```

## Source

### components/ui/navigation-menu.tsx

```tsx
import { NavigationMenu as NavigationMenuPrimitive } from "@base-ui/react/navigation-menu"
import { cva } from "class-variance-authority"
import { cn } from "cn"
import { ChevronDownIcon } from "@/lib/icons"

function NavigationMenu({
  align = "start",
  className,
  children,
  ...props
}: NavigationMenuPrimitive.Root.Props &
  Pick<NavigationMenuPrimitive.Positioner.Props, "align">) {
  return (
    <NavigationMenuPrimitive.Root
      data-slot="navigation-menu"
      className={cn(
        "group/navigation-menu relative flex max-w-max flex-1 items-center justify-center",
        className
      )}
      {...props}
    >
      {children}
      <NavigationMenuPositioner align={align} />
    </NavigationMenuPrimitive.Root>
  )
}

function NavigationMenuList({
  className,
  ...props
}: React.ComponentPropsWithRef<typeof NavigationMenuPrimitive.List>) {
  return (
    <NavigationMenuPrimitive.List
      data-slot="navigation-menu-list"
      className={cn(
        "group flex flex-1 list-none items-center justify-center gap-0",
        className
      )}
      {...props}
    />
  )
}

function NavigationMenuItem({
  className,
  ...props
}: React.ComponentPropsWithRef<typeof NavigationMenuPrimitive.Item>) {
  return (
    <NavigationMenuPrimitive.Item
      data-slot="navigation-menu-item"
      className={cn("relative", className)}
      {...props}
    />
  )
}

const navigationMenuTriggerStyle = cva(
  "group/navigation-menu-trigger inline-flex h-9 w-max items-center justify-center rounded-lg px-2.5 py-1.5 text-sm font-medium transition-all outline-none hover:bg-muted focus:bg-muted focus-visible:ring-3 focus-visible:ring-ring/50 focus-visible:outline-1 disabled:pointer-events-none disabled:opacity-50 data-popup-open:bg-muted/50 data-popup-open:hover:bg-muted data-open:bg-muted/50 data-open:hover:bg-muted data-open:focus:bg-muted"
)

function NavigationMenuTrigger({
  className,
  children,
  ...props
}: NavigationMenuPrimitive.Trigger.Props) {
  return (
    <NavigationMenuPrimitive.Trigger
      data-slot="navigation-menu-trigger"
      className={cn(navigationMenuTriggerStyle(), "group", className)}
      {...props}
    >
      {children}{" "}
      <ChevronDownIcon className="relative top-px ml-1 size-3 transition duration-300 group-data-popup-open/navigation-menu-trigger:rotate-180 group-data-open/navigation-menu-trigger:rotate-180" aria-hidden="true" />
    </NavigationMenuPrimitive.Trigger>
  )
}

function NavigationMenuContent({
  className,
  ...props
}: NavigationMenuPrimitive.Content.Props) {
  return (
    <NavigationMenuPrimitive.Content
      data-slot="navigation-menu-content"
      className={cn(
        "data-ending-style:data-[activation-direction=left]:translate-x-[50%] data-ending-style:data-[activation-direction=right]:translate-x-[-50%] data-starting-style:data-[activation-direction=left]:translate-x-[-50%] data-starting-style:data-[activation-direction=right]:translate-x-[50%] h-full w-auto p-1 transition-[opacity,transform,translate] duration-[0.35s] ease-[cubic-bezier(0.22,1,0.36,1)] group-data-[viewport=false]/navigation-menu:rounded-lg group-data-[viewport=false]/navigation-menu:bg-popover group-data-[viewport=false]/navigation-menu:text-popover-foreground group-data-[viewport=false]/navigation-menu:shadow group-data-[viewport=false]/navigation-menu:ring-1 group-data-[viewport=false]/navigation-menu:ring-foreground/10 group-data-[viewport=false]/navigation-menu:duration-300 data-ending-style:opacity-0 data-starting-style:opacity-0 data-[motion=from-end]:slide-in-from-right-52 data-[motion=from-start]:slide-in-from-left-52 data-[motion=to-end]:slide-out-to-right-52 data-[motion=to-start]:slide-out-to-left-52 data-[motion^=from-]:animate-in data-[motion^=from-]:fade-in data-[motion^=to-]:animate-out data-[motion^=to-]:fade-out **:data-[slot=navigation-menu-link]:focus:ring-0 **:data-[slot=navigation-menu-link]:focus:outline-none group-data-[viewport=false]/navigation-menu:data-open:animate-in group-data-[viewport=false]/navigation-menu:data-open:fade-in-0 group-data-[viewport=false]/navigation-menu:data-open:zoom-in-95 group-data-[viewport=false]/navigation-menu:data-closed:animate-out group-data-[viewport=false]/navigation-menu:data-closed:fade-out-0 group-data-[viewport=false]/navigation-menu:data-closed:zoom-out-95",
        className
      )}
      {...props}
    />
  )
}

function NavigationMenuPositioner({
  className,
  side = "bottom",
  sideOffset = 8,
  align = "start",
  alignOffset = 0,
  ...props
}: NavigationMenuPrimitive.Positioner.Props) {
  return (
    <NavigationMenuPrimitive.Portal>
      <NavigationMenuPrimitive.Positioner
        side={side}
        sideOffset={sideOffset}
        align={align}
        alignOffset={alignOffset}
        className={cn(
          "isolate z-50 h-(--positioner-height) w-(--positioner-width) max-w-(--available-width) transition-[top,left,right,bottom] duration-[0.35s] ease-[cubic-bezier(0.22,1,0.36,1)] data-instant:transition-none data-[side=bottom]:before:top-[-10px] data-[side=bottom]:before:right-0 data-[side=bottom]:before:left-0",
          className
        )}
        {...props}
      >
        <NavigationMenuPrimitive.Popup className="data-ending-style:ease-[ease] relative h-(--popup-height) w-(--popup-width) origin-(--transform-origin) rounded-lg bg-popover text-popover-foreground shadow ring-1 ring-foreground/10 transition-[opacity,transform,width,height,scale,translate] duration-[0.35s] ease-[cubic-bezier(0.22,1,0.36,1)] outline-none data-ending-style:scale-90 data-ending-style:opacity-0 data-ending-style:duration-150 data-starting-style:scale-90 data-starting-style:opacity-0">
          <NavigationMenuPrimitive.Viewport className="relative size-full overflow-hidden" />
        </NavigationMenuPrimitive.Popup>
      </NavigationMenuPrimitive.Positioner>
    </NavigationMenuPrimitive.Portal>
  )
}

function NavigationMenuLink({
  className,
  ...props
}: NavigationMenuPrimitive.Link.Props) {
  return (
    <NavigationMenuPrimitive.Link
      data-slot="navigation-menu-link"
      className={cn(
        "flex items-center gap-2 rounded-lg p-2 text-sm transition-all outline-none hover:bg-muted focus:bg-muted focus-visible:ring-3 focus-visible:ring-ring/50 focus-visible:outline-1 in-data-[slot=navigation-menu-content]:rounded-md data-active:bg-muted/50 data-active:hover:bg-muted data-active:focus:bg-muted [&_svg:not([class*='size-'])]:size-4",
        className
      )}
      {...props}
    />
  )
}

function NavigationMenuIndicator({
  className,
  ...props
}: React.ComponentPropsWithRef<typeof NavigationMenuPrimitive.Icon>) {
  return (
    <NavigationMenuPrimitive.Icon
      data-slot="navigation-menu-indicator"
      className={cn(
        "top-full z-1 flex h-1.5 items-end justify-center overflow-hidden data-[state=hidden]:animate-out data-[state=hidden]:fade-out data-[state=visible]:animate-in data-[state=visible]:fade-in",
        className
      )}
      {...props}
    >
      <div className="relative top-[60%] h-2 w-2 rotate-45 rounded-tl-sm bg-border shadow-md" />
    </NavigationMenuPrimitive.Icon>
  )
}

export {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuIndicator,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
  navigationMenuTriggerStyle,
  NavigationMenuPositioner,
}
```

---

# Number Field

A numeric input with steppers, arrow keys and drag-to-scrub.

Docs: https://jds-ruddy.vercel.app/docs/components/number-field

## Installation

```bash
npx shadcn@latest add @jds/number-field
```

npm dependencies: `@base-ui/react`, `cn`

Also installs: `@jds/utils`

## Example

```tsx
import {
  NumberField,
  NumberFieldDecrement,
  NumberFieldGroup,
  NumberFieldIncrement,
  NumberFieldInput,
  NumberFieldScrubArea,
} from "@/components/ui/number-field"

export default function NumberFieldDemo() {
  return (
    <NumberField defaultValue={4096} min={256} max={32000} step={256} className="w-48">
      <NumberFieldScrubArea>Max output tokens</NumberFieldScrubArea>
      <NumberFieldGroup>
        <NumberFieldDecrement />
        <NumberFieldInput />
        <NumberFieldIncrement />
      </NumberFieldGroup>
    </NumberField>
  )
}
```

## Source

### components/ui/number-field.tsx

```tsx
"use client"

import { NumberField as NumberFieldPrimitive } from "@base-ui/react/number-field"
import { cn } from "cn"

import { AddIcon, MinusIcon } from "@/lib/icons"

function NumberField({ className, ...props }: NumberFieldPrimitive.Root.Props) {
  return (
    <NumberFieldPrimitive.Root
      data-slot="number-field"
      className={cn("flex flex-col gap-2", className)}
      {...props}
    />
  )
}

/** Input with − and + steppers. Drag the label (see NumberFieldScrubArea) or use arrow keys to change the value. */
function NumberFieldGroup({ className, ...props }: NumberFieldPrimitive.Group.Props) {
  return (
    <NumberFieldPrimitive.Group
      data-slot="number-field-group"
      className={cn(
        "flex h-8 w-full items-center overflow-hidden rounded-lg border border-input bg-transparent transition-colors focus-within:border-ring focus-within:ring-3 focus-within:ring-ring/50 data-disabled:opacity-50 dark:bg-input/30",
        className
      )}
      {...props}
    />
  )
}

function NumberFieldInput({ className, ...props }: NumberFieldPrimitive.Input.Props) {
  return (
    <NumberFieldPrimitive.Input
      data-slot="number-field-input"
      className={cn(
        "h-full min-w-0 flex-1 bg-transparent px-2 text-center text-sm tabular-nums outline-none",
        className
      )}
      {...props}
    />
  )
}

const stepper =
  "grid h-full w-8 shrink-0 place-items-center text-muted-foreground transition-colors outline-none select-none hover:bg-accent hover:text-foreground data-disabled:pointer-events-none data-disabled:opacity-40 [&_svg]:size-3.5"

function NumberFieldDecrement({ className, ...props }: NumberFieldPrimitive.Decrement.Props) {
  return (
    <NumberFieldPrimitive.Decrement
      data-slot="number-field-decrement"
      aria-label="Decrease"
      className={cn(stepper, "border-r", className)}
      {...props}
    >
      <MinusIcon />
    </NumberFieldPrimitive.Decrement>
  )
}

function NumberFieldIncrement({ className, ...props }: NumberFieldPrimitive.Increment.Props) {
  return (
    <NumberFieldPrimitive.Increment
      data-slot="number-field-increment"
      aria-label="Increase"
      className={cn(stepper, "border-l", className)}
      {...props}
    >
      <AddIcon />
    </NumberFieldPrimitive.Increment>
  )
}

/** Wrap a label in this so dragging it horizontally changes the value. */
function NumberFieldScrubArea({ className, ...props }: NumberFieldPrimitive.ScrubArea.Props) {
  return (
    <NumberFieldPrimitive.ScrubArea
      data-slot="number-field-scrub-area"
      className={cn("cursor-ew-resize text-sm font-medium select-none", className)}
      {...props}
    />
  )
}

export {
  NumberField,
  NumberFieldGroup,
  NumberFieldInput,
  NumberFieldDecrement,
  NumberFieldIncrement,
  NumberFieldScrubArea,
}
```

---

# Resizable

Panels the user can resize by dragging the divider.

Docs: https://jds-ruddy.vercel.app/docs/components/resizable

## Installation

```bash
npx shadcn@latest add @jds/resizable
```

npm dependencies: `cn`, `react-resizable-panels`

## Example

```tsx
import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from "@/components/ui/resizable"

export default function ResizableDemo() {
  return (
    <div className="h-64 w-full max-w-xl overflow-hidden rounded-xl border">
      <ResizablePanelGroup orientation="horizontal">
        <ResizablePanel defaultSize="30%" minSize="20%">
          <div className="flex h-full items-center justify-center p-4 text-sm text-muted-foreground">Conversations</div>
        </ResizablePanel>
        <ResizableHandle withHandle />
        <ResizablePanel defaultSize="70%" minSize="40%">
          <ResizablePanelGroup orientation="vertical">
            <ResizablePanel defaultSize="65%">
              <div className="flex h-full items-center justify-center p-4 text-sm">Chat</div>
            </ResizablePanel>
            <ResizableHandle withHandle />
            <ResizablePanel defaultSize="35%" minSize="20%">
              <div className="flex h-full items-center justify-center p-4 text-sm text-muted-foreground">Artifact</div>
            </ResizablePanel>
          </ResizablePanelGroup>
        </ResizablePanel>
      </ResizablePanelGroup>
    </div>
  )
}
```

## Source

### components/ui/resizable.tsx

```tsx
"use client"

import { cn } from "cn"
import * as ResizablePrimitive from "react-resizable-panels"

function ResizablePanelGroup({
  className,
  ...props
}: ResizablePrimitive.GroupProps) {
  return (
    <ResizablePrimitive.Group
      data-slot="resizable-panel-group"
      className={cn(
        "flex h-full w-full aria-[orientation=vertical]:flex-col",
        className
      )}
      {...props}
    />
  )
}

function ResizablePanel({ ...props }: ResizablePrimitive.PanelProps) {
  return <ResizablePrimitive.Panel data-slot="resizable-panel" {...props} />
}

function ResizableHandle({
  withHandle,
  className,
  ...props
}: ResizablePrimitive.SeparatorProps & {
  withHandle?: boolean
}) {
  return (
    <ResizablePrimitive.Separator
      data-slot="resizable-handle"
      className={cn(
        "relative flex w-px items-center justify-center bg-border ring-offset-background after:absolute after:inset-y-0 after:left-1/2 after:w-1 after:-translate-x-1/2 focus-visible:ring-1 focus-visible:ring-ring focus-visible:outline-hidden aria-[orientation=horizontal]:h-px aria-[orientation=horizontal]:w-full aria-[orientation=horizontal]:after:left-0 aria-[orientation=horizontal]:after:h-1 aria-[orientation=horizontal]:after:w-full aria-[orientation=horizontal]:after:translate-x-0 aria-[orientation=horizontal]:after:-translate-y-1/2 [&[aria-orientation=horizontal]>div]:rotate-90",
        className
      )}
      {...props}
    >
      {withHandle && (
        <div className="z-10 flex h-6 w-1 shrink-0 rounded-lg bg-border" />
      )}
    </ResizablePrimitive.Separator>
  )
}

export { ResizableHandle, ResizablePanel, ResizablePanelGroup }
```

---

# Toolbar

A row of controls with arrow-key navigation between them.

Docs: https://jds-ruddy.vercel.app/docs/components/toolbar

## Installation

```bash
npx shadcn@latest add @jds/toolbar
```

npm dependencies: `@base-ui/react`, `cn`

Also installs: `@jds/button`

## Example

```tsx
import { Toolbar, ToolbarButton, ToolbarGroup, ToolbarSeparator } from "@/components/ui/toolbar"
import { CopyIcon, DownloadIcon, RegenerateIcon, ThumbsDownIcon, ThumbsUpIcon } from "@/lib/icons"

export default function ToolbarDemo() {
  return (
    <Toolbar aria-label="Response actions">
      <ToolbarGroup>
        <ToolbarButton aria-label="Copy">
          <CopyIcon />
        </ToolbarButton>
        <ToolbarButton aria-label="Regenerate">
          <RegenerateIcon />
        </ToolbarButton>
        <ToolbarButton aria-label="Download">
          <DownloadIcon />
        </ToolbarButton>
      </ToolbarGroup>
      <ToolbarSeparator />
      <ToolbarGroup>
        <ToolbarButton aria-label="Good response">
          <ThumbsUpIcon />
        </ToolbarButton>
        <ToolbarButton aria-label="Bad response">
          <ThumbsDownIcon />
        </ToolbarButton>
      </ToolbarGroup>
    </Toolbar>
  )
}
```

## Source

### components/ui/toolbar.tsx

```tsx
"use client"

import { Toolbar as ToolbarPrimitive } from "@base-ui/react/toolbar"
import { cn } from "cn"

import { buttonVariants } from "@/components/ui/button"

/** A row of controls with roving focus: Tab enters once, arrow keys move between items. */
function Toolbar({ className, ...props }: ToolbarPrimitive.Root.Props) {
  return (
    <ToolbarPrimitive.Root
      data-slot="toolbar"
      className={cn(
        "flex items-center gap-1 rounded-lg border bg-card p-1 data-[orientation=vertical]:flex-col",
        className
      )}
      {...props}
    />
  )
}

function ToolbarButton({ className, ...props }: ToolbarPrimitive.Button.Props) {
  return (
    <ToolbarPrimitive.Button
      data-slot="toolbar-button"
      className={cn(
        buttonVariants({ variant: "ghost", size: "sm" }),
        "data-pressed:bg-accent data-pressed:text-foreground",
        className
      )}
      {...props}
    />
  )
}

function ToolbarLink({ className, ...props }: ToolbarPrimitive.Link.Props) {
  return (
    <ToolbarPrimitive.Link
      data-slot="toolbar-link"
      className={cn(buttonVariants({ variant: "link", size: "sm" }), className)}
      {...props}
    />
  )
}

function ToolbarGroup({ className, ...props }: ToolbarPrimitive.Group.Props) {
  return <ToolbarPrimitive.Group data-slot="toolbar-group" className={cn("flex items-center gap-1", className)} {...props} />
}

function ToolbarSeparator({ className, ...props }: ToolbarPrimitive.Separator.Props) {
  return (
    <ToolbarPrimitive.Separator
      data-slot="toolbar-separator"
      className={cn("mx-0.5 h-5 w-px shrink-0 bg-border data-[orientation=horizontal]:mx-0 data-[orientation=horizontal]:my-0.5 data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-5", className)}
      {...props}
    />
  )
}

export { Toolbar, ToolbarButton, ToolbarLink, ToolbarGroup, ToolbarSeparator }
```

---

# Tooltip

A label on hover or focus.

Docs: https://jds-ruddy.vercel.app/docs/components/tooltip

## Installation

```bash
npx shadcn@latest add @jds/tooltip
```

npm dependencies: `@base-ui/react`, `cn`

## Example

```tsx
import { Button } from "@/components/ui/button"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"
import { AttachIcon } from "@/lib/icons"

export default function TooltipDemo() {
  return (
    <Tooltip>
      <TooltipTrigger render={<Button variant="outline" size="icon" aria-label="Attach" />}>
        <AttachIcon />
      </TooltipTrigger>
      <TooltipContent>Attach files</TooltipContent>
    </Tooltip>
  )
}
```

## Source

### components/ui/tooltip.tsx

```tsx
"use client"

import { Tooltip as TooltipPrimitive } from "@base-ui/react/tooltip"
import { cn } from "cn"

function TooltipProvider({
  delay = 0,
  ...props
}: TooltipPrimitive.Provider.Props) {
  return (
    <TooltipPrimitive.Provider
      data-slot="tooltip-provider"
      delay={delay}
      {...props}
    />
  )
}

function Tooltip({ ...props }: TooltipPrimitive.Root.Props) {
  return <TooltipPrimitive.Root data-slot="tooltip" {...props} />
}

function TooltipTrigger({ ...props }: TooltipPrimitive.Trigger.Props) {
  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />
}

function TooltipContent({
  className,
  side = "top",
  sideOffset = 4,
  align = "center",
  alignOffset = 0,
  children,
  ...props
}: TooltipPrimitive.Popup.Props &
  Pick<
    TooltipPrimitive.Positioner.Props,
    "align" | "alignOffset" | "side" | "sideOffset"
  >) {
  return (
    <TooltipPrimitive.Portal>
      <TooltipPrimitive.Positioner
        align={align}
        alignOffset={alignOffset}
        side={side}
        sideOffset={sideOffset}
        className="isolate z-50"
      >
        <TooltipPrimitive.Popup
          data-slot="tooltip-content"
          className={cn(
            "z-50 inline-flex w-fit max-w-xs origin-(--transform-origin) items-center gap-1.5 rounded-md bg-foreground px-3 py-1.5 text-xs text-background has-data-[slot=kbd]:pr-1.5 data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-50 **:data-[slot=kbd]:rounded-sm data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
            className
          )}
          {...props}
        >
          {children}
          <TooltipPrimitive.Arrow className="z-50 size-2.5 translate-y-[calc(-50%-2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground data-[side=bottom]:top-1 data-[side=inline-end]:top-1/2! data-[side=inline-end]:-left-1 data-[side=inline-end]:-translate-y-1/2 data-[side=inline-start]:top-1/2! data-[side=inline-start]:-right-1 data-[side=inline-start]:-translate-y-1/2 data-[side=left]:top-1/2! data-[side=left]:-right-1 data-[side=left]:-translate-y-1/2 data-[side=right]:top-1/2! data-[side=right]:-left-1 data-[side=right]:-translate-y-1/2 data-[side=top]:-bottom-2.5" />
        </TooltipPrimitive.Popup>
      </TooltipPrimitive.Positioner>
    </TooltipPrimitive.Portal>
  )
}

export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider }
```