create-inox-app 0.1.0

package/dist/templates/claude-config/app/.agents/skills/ai-elements/references/tool.md

@@ -0,0 +1,275 @@
+# Tool
+
+A collapsible component for displaying tool invocation details in AI chatbot interfaces.
+
+The `Tool` component displays a collapsible interface for showing/hiding tool details. It is designed to take the `ToolUIPart` type from the AI SDK and display it in a collapsible interface.
+
+See `scripts/tool.tsx` for this example.
+
+## Installation
+
+```bash
+npx ai-elements@latest add tool
+```
+
+## Usage in AI SDK
+
+Build a simple stateful weather app that renders the last message in a tool using [`useChat`](/docs/reference/ai-sdk-ui/use-chat).
+
+Add the following component to your frontend:
+
+```tsx title="app/page.tsx"
+"use client";
+
+import { useChat } from "@ai-sdk/react";
+import { DefaultChatTransport, type ToolUIPart } from "ai";
+import { Button } from "@/components/ui/button";
+import { MessageResponse } from "@/components/ai-elements/message";
+import {
+  Tool,
+  ToolContent,
+  ToolHeader,
+  ToolInput,
+  ToolOutput,
+} from "@/components/ai-elements/tool";
+
+type WeatherToolInput = {
+  location: string;
+  units: "celsius" | "fahrenheit";
+};
+
+type WeatherToolOutput = {
+  location: string;
+  temperature: string;
+  conditions: string;
+  humidity: string;
+  windSpeed: string;
+  lastUpdated: string;
+};
+
+type WeatherToolUIPart = ToolUIPart<{
+  fetch_weather_data: {
+    input: WeatherToolInput;
+    output: WeatherToolOutput;
+  };
+}>;
+
+const Example = () => {
+  const { messages, sendMessage, status } = useChat({
+    transport: new DefaultChatTransport({
+      api: "/api/weather",
+    }),
+  });
+
+  const handleWeatherClick = () => {
+    sendMessage({ text: "Get weather data for San Francisco in fahrenheit" });
+  };
+
+  const latestMessage = messages[messages.length - 1];
+  const weatherTool = latestMessage?.parts?.find(
+    (part) => part.type === "tool-fetch_weather_data",
+  ) as WeatherToolUIPart | undefined;
+
+  return (
+    <div className="max-w-4xl mx-auto p-6 relative size-full rounded-lg border h-[600px]">
+      <div className="flex flex-col h-full">
+        <div className="space-y-4">
+          <Button onClick={handleWeatherClick} disabled={status !== "ready"}>
+            Get Weather for San Francisco
+          </Button>
+
+          {weatherTool && (
+            <Tool defaultOpen={true}>
+              <ToolHeader type="tool-fetch_weather_data" state={weatherTool.state} />
+              <ToolContent>
+                <ToolInput input={weatherTool.input} />
+                <ToolOutput
+                  output={
+                    <MessageResponse>{formatWeatherResult(weatherTool.output)}</MessageResponse>
+                  }
+                  errorText={weatherTool.errorText}
+                />
+              </ToolContent>
+            </Tool>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+};
+
+function formatWeatherResult(result: WeatherToolOutput): string {
+  return `**Weather for ${result.location}**
+
+**Temperature:** ${result.temperature}  
+**Conditions:** ${result.conditions}  
+**Humidity:** ${result.humidity}  
+**Wind Speed:** ${result.windSpeed}  
+
+*Last updated: ${result.lastUpdated}*`;
+}
+
+export default Example;
+```
+
+Add the following route to your backend:
+
+```ts title="app/api/weather/route.tsx"
+import { streamText, UIMessage, convertToModelMessages } from "ai";
+import { z } from "zod";
+
+// Allow streaming responses up to 30 seconds
+export const maxDuration = 30;
+
+export async function POST(req: Request) {
+  const { messages }: { messages: UIMessage[] } = await req.json();
+
+  const result = streamText({
+    model: "openai/gpt-4o",
+    messages: await convertToModelMessages(messages),
+    tools: {
+      fetch_weather_data: {
+        description: "Fetch weather information for a specific location",
+        parameters: z.object({
+          location: z.string().describe("The city or location to get weather for"),
+          units: z.enum(["celsius", "fahrenheit"]).default("celsius").describe("Temperature units"),
+        }),
+        inputSchema: z.object({
+          location: z.string(),
+          units: z.enum(["celsius", "fahrenheit"]).default("celsius"),
+        }),
+        execute: async ({ location, units }) => {
+          await new Promise((resolve) => setTimeout(resolve, 1500));
+
+          const temp =
+            units === "celsius"
+              ? Math.floor(Math.random() * 35) + 5
+              : Math.floor(Math.random() * 63) + 41;
+
+          return {
+            location,
+            temperature: `${temp}°${units === "celsius" ? "C" : "F"}`,
+            conditions: "Sunny",
+            humidity: `12%`,
+            windSpeed: `35 ${units === "celsius" ? "km/h" : "mph"}`,
+            lastUpdated: new Date().toLocaleString(),
+          };
+        },
+      },
+    },
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+## Features
+
+- Collapsible interface for showing/hiding tool details
+- Visual status indicators with icons and badges
+- Support for multiple tool execution states (pending, running, completed, error)
+- Formatted parameter display with JSON syntax highlighting
+- Result and error handling with appropriate styling
+- Composable structure for flexible layouts
+- Accessible keyboard navigation and screen reader support
+- Consistent styling that matches your design system
+- Auto-opens completed tools by default for better UX
+
+## Examples
+
+### Input Streaming (Pending)
+
+Shows a tool in its initial state while parameters are being processed.
+
+See `scripts/tool-input-streaming.tsx` for this example.
+
+### Input Available (Running)
+
+Shows a tool that's actively executing with its parameters.
+
+See `scripts/tool-input-available.tsx` for this example.
+
+### Output Available (Completed)
+
+Shows a completed tool with successful results. Opens by default to show the results. In this instance, the output is a JSON object, so we can use the `CodeBlock` component to display it.
+
+See `scripts/tool-output-available.tsx` for this example.
+
+### Output Error
+
+Shows a tool that encountered an error during execution. Opens by default to display the error.
+
+See `scripts/tool-output-error.tsx` for this example.
+
+## Props
+
+### `<Tool />`
+
+| Prop       | Type                                       | Default | Description                                                   |
+| ---------- | ------------------------------------------ | ------- | ------------------------------------------------------------- |
+| `...props` | `React.ComponentProps<typeof Collapsible>` | -       | Any other props are spread to the root Collapsible component. |
+
+### `<ToolHeader />`
+
+| Prop        | Type                                              | Default  | Description                                                                                          |
+| ----------- | ------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
+| `title`     | `string`                                          | -        | Custom title to display instead of the derived tool name.                                            |
+| `type`      | `ToolUIPart[`                                     | Required | The type/name of the tool.                                                                           |
+| `state`     | `ToolUIPart[`                                     | Required | The current state of the tool (input-streaming, input-available, output-available, or output-error). |
+| `toolName`  | `string`                                          | -        | Required when type is                                                                                |
+| `className` | `string`                                          | -        | Additional CSS classes to apply to the header.                                                       |
+| `...props`  | `React.ComponentProps<typeof CollapsibleTrigger>` | -        | Any other props are spread to the CollapsibleTrigger.                                                |
+
+### `<ToolContent />`
+
+| Prop       | Type                                              | Default | Description                                           |
+| ---------- | ------------------------------------------------- | ------- | ----------------------------------------------------- |
+| `...props` | `React.ComponentProps<typeof CollapsibleContent>` | -       | Any other props are spread to the CollapsibleContent. |
+
+### `<ToolInput />`
+
+| Prop       | Type                    | Default | Description                                                           |
+| ---------- | ----------------------- | ------- | --------------------------------------------------------------------- |
+| `input`    | `ToolUIPart[`           | -       | The input parameters passed to the tool, displayed as formatted JSON. |
+| `...props` | `React.ComponentProps<` | -       | Any other props are spread to the underlying div.                     |
+
+### `<ToolOutput />`
+
+| Prop        | Type                    | Default | Description                                       |
+| ----------- | ----------------------- | ------- | ------------------------------------------------- |
+| `output`    | `React.ReactNode`       | -       | The output/result of the tool execution.          |
+| `errorText` | `ToolUIPart[`           | -       | An error message if the tool execution failed.    |
+| `...props`  | `React.ComponentProps<` | -       | Any other props are spread to the underlying div. |
+
+## Type Exports
+
+### `ToolPart`
+
+Union type representing both static and dynamic tool UI parts.
+
+```tsx
+type ToolPart = ToolUIPart | DynamicToolUIPart;
+```
+
+## Utilities
+
+### `getStatusBadge`
+
+Returns a Badge component with icon and label based on tool state.
+
+```tsx
+import { getStatusBadge } from "@/components/ai-elements/tool";
+
+// Returns a Badge with appropriate icon and label
+const badge = getStatusBadge("output-available");
+```
+
+Supported states:
+
+- `input-streaming` - "Pending"
+- `input-available` - "Running"
+- `approval-requested` - "Awaiting Approval"
+- `approval-responded` - "Responded"
+- `output-available` - "Completed"
+- `output-error` - "Error"
+- `output-denied` - "Denied"

package/dist/templates/claude-config/app/.agents/skills/ai-elements/references/toolbar.md

@@ -0,0 +1,30 @@
+# Toolbar
+
+A styled toolbar component for React Flow nodes with flexible positioning and custom actions.
+
+The `Toolbar` component provides a positioned toolbar that attaches to nodes in React Flow canvases. It features modern card styling with backdrop blur and flexbox layout for action buttons and controls.
+
+## Installation
+
+```bash
+npx ai-elements@latest add toolbar
+```
+
+## Features
+
+- Attaches to any React Flow node
+- Bottom positioning by default
+- Rounded card design with border
+- Theme-aware background styling
+- Flexbox layout with gap spacing
+- Full TypeScript support
+- Compatible with all React Flow NodeToolbar features
+
+## Props
+
+### `<Toolbar />`
+
+| Prop        | Type                                 | Default | Description                                                                                   |
+| ----------- | ------------------------------------ | ------- | --------------------------------------------------------------------------------------------- |
+| `className` | `string`                             | -       | Additional CSS classes to apply to the toolbar.                                               |
+| `...props`  | `ComponentProps<typeof NodeToolbar>` | -       | Any other props from @xyflow/react NodeToolbar component (position, offset, isVisible, etc.). |

package/dist/templates/claude-config/app/.agents/skills/ai-elements/references/transcription.md

@@ -0,0 +1,120 @@
+# Transcription
+
+A composable component for displaying interactive, synchronized transcripts from AI SDK transcribe() results with click-to-seek functionality.
+
+The `Transcription` component provides a flexible render props interface for displaying audio transcripts with synchronized playback. It automatically highlights the current segment based on playback time and supports click-to-seek functionality for interactive navigation.
+
+See `scripts/transcription.tsx` for this example.
+
+## Installation
+
+```bash
+npx ai-elements@latest add transcription
+```
+
+## Features
+
+- Render props pattern for maximum flexibility
+- Automatic segment highlighting based on current time
+- Click-to-seek functionality for interactive navigation
+- Controlled and uncontrolled component patterns
+- Automatic filtering of empty segments
+- Visual state indicators (active, past, future)
+- Built on Radix UI's `useControllableState` for flexible state management
+- Full TypeScript support with AI SDK transcription types
+
+## Props
+
+### `<Transcription />`
+
+Root component that provides context and manages transcript state. Uses render props pattern for rendering segments.
+
+| Prop          | Type                                                          | Default | Description                                                           |
+| ------------- | ------------------------------------------------------------- | ------- | --------------------------------------------------------------------- |
+| `segments`    | `TranscriptionSegment[]`                                      | -       | Array of transcription segments from AI SDK transcribe() function.    |
+| `currentTime` | `number`                                                      | `0`     | Current playback time in seconds (controlled).                        |
+| `onSeek`      | `(time: number) => void`                                      | -       | Callback fired when a segment is clicked or when currentTime changes. |
+| `children`    | `(segment: TranscriptionSegment, index: number) => ReactNode` | -       | Render function that receives each segment and its index.             |
+| `...props`    | `Omit<React.ComponentProps<`                                  | -       | Any other props are spread to the root div element.                   |
+
+### `<TranscriptionSegment />`
+
+Individual segment button with automatic state styling and click-to-seek functionality.
+
+| Prop       | Type                    | Default | Description                                       |
+| ---------- | ----------------------- | ------- | ------------------------------------------------- |
+| `segment`  | `TranscriptionSegment`  | -       | The transcription segment data.                   |
+| `index`    | `number`                | -       | The segment index.                                |
+| `...props` | `React.ComponentProps<` | -       | Any other props are spread to the button element. |
+
+## Behavior
+
+### Render Props Pattern
+
+The component uses a render props pattern where the `children` prop is a function that receives each segment and its index. This provides maximum flexibility for custom rendering while still benefiting from automatic state management and context.
+
+### Segment Highlighting
+
+Segments are automatically styled based on their relationship to the current playback time:
+
+- **Active** (`isActive`): When `currentTime` is within the segment's time range. Styled with primary color.
+- **Past** (`isPast`): When `currentTime` is after the segment's end time. Styled with muted foreground.
+- **Future**: When `currentTime` is before the segment's start time. Styled with dimmed muted foreground.
+
+### Click-to-Seek
+
+When `onSeek` is provided, segments become interactive buttons. Clicking a segment calls `onSeek` with the segment's start time, allowing your audio/video player to seek to that position.
+
+### Empty Segment Filtering
+
+The component automatically filters out segments with empty or whitespace-only text to avoid rendering unnecessary elements.
+
+### State Management
+
+Uses Radix UI's `useControllableState` hook to support both controlled and uncontrolled patterns. When `currentTime` is provided, the component operates in controlled mode. Otherwise, it maintains its own internal state.
+
+## Data Format
+
+The component expects segments from the AI SDK `transcribe()` function:
+
+```ts
+type TranscriptionSegment = {
+  text: string;
+  startSecond: number;
+  endSecond: number;
+};
+```
+
+## Styling
+
+The component uses data attributes for custom styling:
+
+- `data-slot="transcription"`: Root container
+- `data-slot="transcription-segment"`: Individual segment button
+- `data-active`: Present on the currently playing segment
+- `data-index`: The segment's index in the array
+
+Default segment appearance:
+
+- Active segment: `text-primary` (primary brand color)
+- Past segments: `text-muted-foreground`
+- Future segments: `text-muted-foreground/60` (dimmed)
+- Interactive segments: `cursor-pointer hover:text-foreground`
+- Non-interactive segments: `cursor-default`
+
+## Accessibility
+
+- Uses semantic `<button>` elements for interactive segments
+- Full keyboard navigation support
+- Proper button semantics for screen readers
+- `data-active` attribute for assistive technology
+- Hover and focus states for keyboard users
+
+## Notes
+
+- Empty or whitespace-only segments are automatically filtered out
+- The component uses `flex-wrap` for responsive text flow
+- Segments maintain inline layout with `gap-1` spacing
+- `text-sm` and `leading-relaxed` provide comfortable reading
+- Click events on segments still fire the `onClick` handler if provided
+- The `onSeek` callback is called both when segments are clicked and when controlled `currentTime` changes

package/dist/templates/claude-config/app/.agents/skills/ai-elements/references/voice-selector.md

@@ -0,0 +1,241 @@
+# Voice Selector
+
+A composable dialog component for selecting AI voices with metadata display and search functionality.
+
+The `VoiceSelector` component provides a flexible and composable interface for selecting AI voices. Built on shadcn/ui's Dialog and Command components, it features a searchable voice list with support for metadata display (gender, accent, age), grouping, and customizable layouts. The component includes a context provider for accessing voice selection state from any nested component.
+
+See `scripts/voice-selector.tsx` for this example.
+
+## Installation
+
+```bash
+npx ai-elements@latest add voice-selector
+```
+
+## Features
+
+- Fully composable architecture with granular control components
+- Built on shadcn/ui Dialog and Command components
+- React Context API for accessing state in nested components
+- Searchable voice list with real-time filtering
+- Support for voice metadata with icons and emojis (gender icons, accent flags, age)
+- Voice preview button with play/pause/loading states
+- Voice grouping with separators and bullet dividers
+- Keyboard navigation support
+- Controlled and uncontrolled component patterns
+- Full TypeScript support with proper types for all components
+
+## Props
+
+### `<VoiceSelector />`
+
+Root Dialog component that provides context for all child components. Manages both voice selection and dialog open states.
+
+| Prop            | Type                                  | Default             | Description                                                                 |
+| --------------- | ------------------------------------- | ------------------- | --------------------------------------------------------------------------- | ----------------------------------------------- |
+| `value`         | `string`                              | -                   | The selected voice ID (controlled).                                         |
+| `defaultValue`  | `string`                              | -                   | The default selected voice ID (uncontrolled).                               |
+| `onValueChange` | `(value: string                       | undefined) => void` | -                                                                           | Callback fired when the selected voice changes. |
+| `defaultOpen`   | `boolean`                             | `false`             | The default open state (uncontrolled).                                      |
+| `open`          | `boolean`                             | -                   | The open state (controlled).                                                |
+| `onOpenChange`  | `(open: boolean) => void`             | -                   | Callback fired when the open state changes.                                 |
+| `modal`         | `boolean`                             | `true`              | Whether the dialog is modal (blocks interaction with the rest of the page). |
+| `...props`      | `React.ComponentProps<typeof Dialog>` | -                   | Any other props are spread to the Dialog component.                         |
+
+### `<VoiceSelectorTrigger />`
+
+Button or element that opens the voice selector dialog.
+
+| Prop       | Type                                         | Default | Description                                                                                          |
+| ---------- | -------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------- |
+| `asChild`  | `boolean`                                    | `false` | Change the default rendered element for the one passed as a child, merging their props and behavior. |
+| `...props` | `React.ComponentProps<typeof DialogTrigger>` | -       | Any other props are spread to the DialogTrigger component.                                           |
+
+### `<VoiceSelectorContent />`
+
+Container for the Command component and voice list, rendered inside the dialog.
+
+| Prop        | Type                                         | Default | Description                                                                             |
+| ----------- | -------------------------------------------- | ------- | --------------------------------------------------------------------------------------- |
+| `title`     | `ReactNode`                                  | -       | The title for screen readers. Hidden visually but accessible to assistive technologies. |
+| `className` | `string`                                     | -       | Additional CSS classes to apply to the dialog content.                                  |
+| `...props`  | `React.ComponentProps<typeof DialogContent>` | -       | Any other props are spread to the DialogContent component.                              |
+
+### `<VoiceSelectorDialog />`
+
+Alternative dialog implementation using CommandDialog for a full-screen command palette style.
+
+| Prop       | Type                                         | Default | Description                                                |
+| ---------- | -------------------------------------------- | ------- | ---------------------------------------------------------- |
+| `...props` | `React.ComponentProps<typeof CommandDialog>` | -       | Any other props are spread to the CommandDialog component. |
+
+### `<VoiceSelectorInput />`
+
+Search input for filtering voices.
+
+| Prop          | Type                                        | Default | Description                                               |
+| ------------- | ------------------------------------------- | ------- | --------------------------------------------------------- |
+| `placeholder` | `string`                                    | -       | Placeholder text for the search input.                    |
+| `className`   | `string`                                    | -       | Additional CSS classes to apply.                          |
+| `...props`    | `React.ComponentProps<typeof CommandInput>` | -       | Any other props are spread to the CommandInput component. |
+
+### `<VoiceSelectorList />`
+
+Scrollable container for voice items and groups.
+
+| Prop       | Type                                       | Default | Description                                              |
+| ---------- | ------------------------------------------ | ------- | -------------------------------------------------------- |
+| `...props` | `React.ComponentProps<typeof CommandList>` | -       | Any other props are spread to the CommandList component. |
+
+### `<VoiceSelectorEmpty />`
+
+Message shown when no voices match the search query.
+
+| Prop       | Type                                        | Default | Description                                               |
+| ---------- | ------------------------------------------- | ------- | --------------------------------------------------------- |
+| `children` | `ReactNode`                                 | -       | The message to display.                                   |
+| `...props` | `React.ComponentProps<typeof CommandEmpty>` | -       | Any other props are spread to the CommandEmpty component. |
+
+### `<VoiceSelectorGroup />`
+
+Groups related voices together with an optional heading.
+
+| Prop       | Type                                        | Default | Description                                               |
+| ---------- | ------------------------------------------- | ------- | --------------------------------------------------------- |
+| `heading`  | `string`                                    | -       | The heading text for the group.                           |
+| `...props` | `React.ComponentProps<typeof CommandGroup>` | -       | Any other props are spread to the CommandGroup component. |
+
+### `<VoiceSelectorItem />`
+
+Selectable item representing a voice.
+
+| Prop       | Type                                       | Default | Description                                                      |
+| ---------- | ------------------------------------------ | ------- | ---------------------------------------------------------------- |
+| `value`    | `string`                                   | -       | The unique identifier for this voice. Used for search filtering. |
+| `onSelect` | `(value: string) => void`                  | -       | Callback fired when the voice is selected.                       |
+| `...props` | `React.ComponentProps<typeof CommandItem>` | -       | Any other props are spread to the CommandItem component.         |
+
+### `<VoiceSelectorSeparator />`
+
+Visual separator between voice groups.
+
+| Prop       | Type                                            | Default | Description                                                   |
+| ---------- | ----------------------------------------------- | ------- | ------------------------------------------------------------- |
+| `...props` | `React.ComponentProps<typeof CommandSeparator>` | -       | Any other props are spread to the CommandSeparator component. |
+
+### `<VoiceSelectorName />`
+
+Displays the voice name with proper styling.
+
+| Prop        | Type                    | Default | Description                                     |
+| ----------- | ----------------------- | ------- | ----------------------------------------------- |
+| `className` | `string`                | -       | Additional CSS classes to apply.                |
+| `...props`  | `React.ComponentProps<` | -       | Any other props are spread to the span element. |
+
+### `<VoiceSelectorGender />`
+
+Displays the voice gender metadata with icons from Lucide. Supports multiple gender identities with corresponding icons.
+
+| Prop        | Type                    | Default | Description                                                               |
+| ----------- | ----------------------- | ------- | ------------------------------------------------------------------------- |
+| `value`     | `unknown`               | -       | The gender value that determines which icon to display. Supported values: |
+| `className` | `string`                | -       | Additional CSS classes to apply.                                          |
+| `children`  | `ReactNode`             | -       | Override the icon with custom content.                                    |
+| `...props`  | `React.ComponentProps<` | -       | Any other props are spread to the span element.                           |
+
+### `<VoiceSelectorAccent />`
+
+Displays the voice accent metadata with emoji flags representing different countries/regions.
+
+| Prop        | Type                    | Default | Description                                                                                            |
+| ----------- | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------ |
+| `value`     | `unknown`               | -       | The accent value that determines which flag emoji to display. Supports 27 different accents including: |
+| `className` | `string`                | -       | Additional CSS classes to apply.                                                                       |
+| `children`  | `ReactNode`             | -       | Override the flag emoji with custom content.                                                           |
+| `...props`  | `React.ComponentProps<` | -       | Any other props are spread to the span element.                                                        |
+
+### `<VoiceSelectorAge />`
+
+Displays the voice age metadata with muted styling and tabular numbers for consistent alignment.
+
+| Prop        | Type                    | Default | Description                                     |
+| ----------- | ----------------------- | ------- | ----------------------------------------------- |
+| `className` | `string`                | -       | Additional CSS classes to apply.                |
+| `...props`  | `React.ComponentProps<` | -       | Any other props are spread to the span element. |
+
+### `<VoiceSelectorDescription />`
+
+Displays a description for the voice with muted styling.
+
+| Prop        | Type                    | Default | Description                                     |
+| ----------- | ----------------------- | ------- | ----------------------------------------------- |
+| `className` | `string`                | -       | Additional CSS classes to apply.                |
+| `...props`  | `React.ComponentProps<` | -       | Any other props are spread to the span element. |
+
+### `<VoiceSelectorAttributes />`
+
+Container for grouping voice attributes (gender, accent, age) together. Use with `VoiceSelectorBullet` for separation.
+
+| Prop        | Type                    | Default | Description                                    |
+| ----------- | ----------------------- | ------- | ---------------------------------------------- |
+| `className` | `string`                | -       | Additional CSS classes to apply.               |
+| `...props`  | `React.ComponentProps<` | -       | Any other props are spread to the div element. |
+
+### `<VoiceSelectorBullet />`
+
+Displays a bullet separator (•) between voice attributes. Hidden from screen readers via `aria-hidden`.
+
+| Prop        | Type                    | Default | Description                                     |
+| ----------- | ----------------------- | ------- | ----------------------------------------------- |
+| `className` | `string`                | -       | Additional CSS classes to apply.                |
+| `...props`  | `React.ComponentProps<` | -       | Any other props are spread to the span element. |
+
+### `<VoiceSelectorShortcut />`
+
+Displays keyboard shortcuts for voice items.
+
+| Prop       | Type                                           | Default | Description                                                  |
+| ---------- | ---------------------------------------------- | ------- | ------------------------------------------------------------ |
+| `...props` | `React.ComponentProps<typeof CommandShortcut>` | -       | Any other props are spread to the CommandShortcut component. |
+
+### `<VoiceSelectorPreview />`
+
+A button that allows users to preview/play a voice sample before selecting it. Shows play, pause, or loading icons based on state.
+
+| Prop        | Type                         | Default | Description                                                                          |
+| ----------- | ---------------------------- | ------- | ------------------------------------------------------------------------------------ |
+| `playing`   | `boolean`                    | -       | Whether the voice is currently playing. Shows pause icon when true.                  |
+| `loading`   | `boolean`                    | -       | Whether the voice preview is loading. Shows loading spinner and disables the button. |
+| `onPlay`    | `() => void`                 | -       | Callback fired when the preview button is clicked.                                   |
+| `className` | `string`                     | -       | Additional CSS classes to apply.                                                     |
+| `...props`  | `Omit<React.ComponentProps<` | -       | Any other props are spread to the button element.                                    |
+
+## Hooks
+
+### `useVoiceSelector()`
+
+A custom hook for accessing the voice selector context. This hook allows you to access and control the voice selection state from any component nested within `VoiceSelector`.
+
+```tsx
+import { useVoiceSelector } from "@repo/elements/voice-selector";
+
+export default function CustomVoiceDisplay() {
+  const { value, setValue, open, setOpen } = useVoiceSelector();
+
+  return (
+    <div>
+      <p>Selected voice: {value ?? "None"}</p>
+      <button onClick={() => setOpen(!open)}>Toggle Dialog</button>
+    </div>
+  );
+}
+```
+
+#### Return Value
+
+| Prop       | Type                      | Default             | Description                                |
+| ---------- | ------------------------- | ------------------- | ------------------------------------------ | ----------------------------------------- |
+| `value`    | `string                   | undefined`          | -                                          | The currently selected voice ID.          |
+| `setValue` | `(value: string           | undefined) => void` | -                                          | Function to update the selected voice ID. |
+| `open`     | `boolean`                 | -                   | Whether the dialog is currently open.      |
+| `setOpen`  | `(open: boolean) => void` | -                   | Function to control the dialog open state. |