### Install Typed Utils with bun

Source: https://typedora-ui.netlify.app/docs/utils/typed-utils

Installs the typed-utils package using bun. This command is part of the shadcn/ui installation process for Typedora UI components.

```bash
bunx --bun shadcn@latest add https://typedora-ui.netlify.app/r/typed-utils.json
```

--------------------------------

### Install Typed Utils with npm

Source: https://typedora-ui.netlify.app/docs/utils/typed-utils

Installs the typed-utils package using npm. This command is part of the shadcn/ui installation process for Typedora UI components.

```bash
npx shadcn@latest add https://typedora-ui.netlify.app/r/typed-utils.json
```

--------------------------------

### Install TypedSelect using bun

Source: https://typedora-ui.netlify.app/docs

Installs the TypedSelect component into your project using the shadcn CLI with bun. This command fetches the component definition from the Typedora UI Netlify deployment.

```bash
bunx --bun shadcn@latest add https://typedora-ui.netlify.app/r/typed-select.json
```

--------------------------------

### Install TypedSelect using npm

Source: https://typedora-ui.netlify.app/docs

Installs the TypedSelect component into your project using the shadcn CLI with npm. This command fetches the component definition from the Typedora UI Netlify deployment.

```bash
npx shadcn@latest add https://typedora-ui.netlify.app/r/typed-select.json
```

--------------------------------

### Install TypedCombobox with npm, pnpm, or bun

Source: https://typedora-ui.netlify.app/docs/components/typed-combobox

Instructions for installing the TypedCombobox component using package managers like npm, pnpm, and bun. This command adds the component to your project.

```bash
npx shadcn@latest add https://typedora-ui.netlify.app/r/typed-combobox.json
```

```bash
pnpm dlx shadcn@latest add https://typedora-ui.netlify.app/r/typed-combobox.json
```

```bash
bunx --bun shadcn@latest add https://typedora-ui.netlify.app/r/typed-combobox.json
```

--------------------------------

### Install Typed Utils with pnpm

Source: https://typedora-ui.netlify.app/docs/utils/typed-utils

Installs the typed-utils package using pnpm. This command is part of the shadcn/ui installation process for Typedora UI components.

```bash
pnpm dlx shadcn@latest add https://typedora-ui.netlify.app/r/typed-utils.json
```

--------------------------------

### Install TypedSelect using npm, pnpm, or bun

Source: https://typedora-ui.netlify.app/docs/components/typed-select

Instructions for installing the TypedSelect component using various package managers like npm, pnpm, and bun. This command adds the component's configuration to your project.

```bash
npx shadcn@latest add https://typedora-ui.netlify.app/r/typed-select.json

```

```bash
pnpm dlx shadcn@latest add https://typedora-ui.netlify.app/r/typed-select.json

```

```bash
bunx --bun shadcn@latest add https://typedora-ui.netlify.app/r/typed-select.json

```

--------------------------------

### Install TypedSelect using pnpm

Source: https://typedora-ui.netlify.app/docs

Installs the TypedSelect component into your project using the shadcn CLI with pnpm. This command fetches the component definition from the Typedora UI Netlify deployment.

```bash
pnpm dlx shadcn@latest add https://typedora-ui.netlify.app/r/typed-select.json
```

--------------------------------

### Install TypedRadioGroup using npm, pnpm, or bun

Source: https://typedora-ui.netlify.app/docs/components/typed-radio-group

Instructions for installing the TypedRadioGroup component using package managers like npm, pnpm, and bun. This command fetches the component's JSON definition for integration.

```bash
npx shadcn@latest add https://typedora-ui.netlify.app/r/typed-radio-group.json
```

```bash
pnpm dlx shadcn@latest add https://typedora-ui.netlify.app/r/typed-radio-group.json
```

```bash
bunx --bun shadcn@latest add https://typedora-ui.netlify.app/r/typed-radio-group.json
```

--------------------------------

### Real-world Example: Type-Safe State with TypedSelect (TypeScript)

Source: https://typedora-ui.netlify.app/docs/utils/typed-utils

Illustrates a practical application of `ExtractOptionValue` within a React component using `TypedSelect`. It shows how to create type-safe state for a filter based on option values.

```typescript
import { useState } from "react";
import type { ExtractOptionValue } from "@/lib/typed-utils";
import { TypedSelect } from "@/components/typed-select";

const statusOptions = [
  { value: "pending", label: "Pending", color: "yellow" },
  { value: "approved", label: "Approved", color: "green" },
  { value: "rejected", label: "Rejected", color: "red" },
] as const;

// Type-safe state
type Status = ExtractOptionValue<typeof statusOptions, "value">

function StatusFilter() {
  const [status, setStatus] = useState<Status | undefined>();

  // status is typed as "pending" | "approved" | "rejected" | undefined

  return (
    <TypedSelect
      options={statusOptions}
      value={status}
      onValueChange={setStatus}
      placeholder="Filter by status"
    />
  );
}

```

--------------------------------

### Custom Item Rendering for TypedCombobox in React

Source: https://typedora-ui.netlify.app/docs/components/typed-combobox

Demonstrates advanced customization of the TypedCombobox item rendering. This example uses render props to display user information including an avatar, name, and email, along with a checkmark for selected items. It requires the `lucide-react` and `cn` utility.

```tsx
import { CheckIcon } from "lucide-react";
import { TypedCombobox } from "@/components/typed-combobox";
import { cn } from "@/lib/utils";

const users = [
  { id: 1, name: "John Doe", email: "john@example.com", avatar: "JD" },
  { id: 2, name: "Jane Smith", email: "jane@example.com", avatar: "JS" },
  { id: 3, name: "Bob Johnson", email: "bob@example.com", avatar: "BJ" },
] as const;

export function CustomItem() {
  return (
    <TypedCombobox
      placeholder="Select a user..."
      searchPlaceholder="Search users..."
      options={users}
      valueKey="id"
      labelKey="name"
      popoverWidth={300}
      renderItem={({ option, isSelected, itemProps, Item }) => (
        <Item {...itemProps} className="flex items-center gap-3 px-2 py-2">
          <div className="flex h-8 w-8 items-center justify-center rounded-full bg-primary/10 text-sm font-medium">
            {option.avatar}
          </div>
          <div className="flex-1 min-w-0">
            <div className="font-medium truncate">{option.name}</div>
            <div className="text-xs text-muted-foreground truncate">
              {option.email}
            </div>
          </div>
          <CheckIcon
            className={cn(
              "h-4 w-4 shrink-0",
              isSelected ? "opacity-100" : "opacity-0",
            )}
          />
        </Item>
      )}
      onValueChange={(value) => {
        console.log(value);
      }}
    />
  );
}
```

--------------------------------

### TypedSelect with Custom Keys (React)

Source: https://typedora-ui.netlify.app/docs/components/typed-select

Shows how to customize the key names used for options in TypedSelect. Instead of the default 'value' and 'label', this example uses 'id' and 'name' to map data. It also demonstrates custom rendering of list items to display additional information like email.

```typescript
"use client";

import { useState } from "react";
import { TypedSelect } from "@/components/typed-select";

// Example data using id/name keys instead of value/label

type User = {
  id: number;
  name: string;
  email: string;
};

const users: User[] = [
  { id: 1, name: "John Doe", email: "john@example.com" },
  { id: 2, name: "Jane Smith", email: "jane@example.com" },
  { id: 3, name: "Bob Johnson", email: "bob@example.com" },
];

export function CustomKeys() {
  const [selectedId, setSelectedId] = useState<User["id"]>();

  return (
    <div className="space-y-4">
      <TypedSelect
        placeholder="Select a user"
        options={users}
        valueKey="id"
        labelKey="name"
        value={selectedId}
        onValueChange={setSelectedId}
        renderItem={({ option, itemProps, Item }) => (
          <Item {...itemProps} className="flex flex-col items-start py-2">
            <span className="font-medium">{option.name}</span>
            <span className="text-sm text-muted-foreground">
              {option.email}
            </span>
          </Item>
        )}
      />
      {selectedId && (
        <p className="text-sm text-muted-foreground">
          Selected user ID: <strong>{selectedId}</strong>
        </p>
      )}
    </div>
  );
}

```

--------------------------------

### TypedCombobox with Number Values in React

Source: https://typedora-ui.netlify.app/docs/components/typed-combobox

Illustrates how to use TypedCombobox with number-based options. This example sets up a priority selection where the selected value is a number. Type inference ensures the `onValueChange` callback receives a number.

```tsx
import { TypedCombobox } from "@/components/typed-combobox";

export function NumberValues() {
  return (
    <TypedCombobox
      placeholder="Select priority..."
      searchPlaceholder="Search priorities..."
      options={
        [
          { label: "Low", value: 1 },
          { label: "Medium", value: 2 },
          { label: "High", value: 3 },
          { label: "Critical", value: 4 },
        ] as const
      }
      onValueChange={(value) => {
                      
value: 1 | 2 | 3 | 4
        console.log(value);
      }}
    />
  );
}
```

--------------------------------

### Basic TypedCombobox Usage in React

Source: https://typedora-ui.netlify.app/docs/components/typed-combobox

Demonstrates the basic usage of the TypedCombobox component with string options. It shows how to set placeholders and handle value changes. The component infers the type of the selected value.

```tsx
import { TypedCombobox } from "@/components/typed-combobox";

export function BasicUsage() {
  return (
    <TypedCombobox
      placeholder="Select a framework..."
      searchPlaceholder="Search frameworks..."
      options={
        [
          { label: "Next.js", value: "nextjs" },
          { label: "Remix", value: "remix" },
          { label: "Astro", value: "astro" },
          { label: "SvelteKit", value: "sveltekit" },
          { label: "Nuxt", value: "nuxt" },
        ] as const
      }
      onValueChange={(value) => {
                      
value: "nextjs" | "remix" | "astro" | "sveltekit" | "nuxt"
        console.log(value);
      }}
    />
  );
}
```

--------------------------------

### Basic TypedSelect Usage in TypeScript

Source: https://typedora-ui.netlify.app/docs/components/typed-select

Demonstrates the basic implementation of the TypedSelect component with string values. It shows how to define options and handle value changes, ensuring type safety for the selected string.

```typescript
import { TypedSelect } from "@/components/typed-select";

export function BasicUsage() {
  return (
    <div>
      <TypedSelect
        options={
          [
            { label: "Apple", value: "apple" },
            { label: "Banana", value: "banana" },
            { label: "Orange", value: "orange" },
          ] as const
        }
        onValueChange={(value) => {
                        
value: "apple" | "banana" | "orange"
        }}
      />
    </div>
  );
}

```

--------------------------------

### Using `as const` for Type Inference (TypeScript)

Source: https://typedora-ui.netlify.app/docs/utils/typed-utils

Demonstrates the correct usage of `as const` for defining options arrays to preserve literal types, ensuring precise type inference. Using `as const` prevents type widening to generic types like `string`.

```typescript
// Good - literal types preserved
const options = [
  { value: "a", label: "A" },
  { value: "b", label: "B" },
] as const;

// Bad - types widened to string
const options = [
  { value: "a", label: "A" },
  { value: "b", label: "B" },
];
```

--------------------------------

### Extract Option and Value Types from Grouped Options (TypeScript)

Source: https://typedora-ui.netlify.app/docs/utils/typed-utils

Demonstrates the seamless integration of `ExtractOption` and `ExtractOptionValue` with grouped option arrays, showing how to extract both individual option types and specific value types.

```typescript
import type { ExtractOption, ExtractOptionValue } from "@/lib/typed-utils";

const countryOptions = [
  {
    label: "Asia",
    options: [
      { value: "jp", label: "Japan" },
      { value: "kr", label: "South Korea" },
      { value: "vn", label: "Vietnam" },
    ],
  },
  {
    label: "Europe",
    options: [
      { value: "de", label: "Germany" },
      { value: "fr", label: "France" },
      { value: "uk", label: "United Kingdom" },
    ],
  },
] as const;

// Extracts the individual option (not the group)
type Country = ExtractOption<typeof countryOptions>;

// Expected type:
type Country = {
    readonly value: "jp";
    readonly label: "Japan";
} | {
    readonly value: "kr";
    readonly label: "South Korea";
} | {
    readonly value: "vn";
    readonly label: "Vietnam";
} | {
    readonly value: "de";
    readonly label: "Germany";
} | {
    readonly value: "fr";
    readonly label: "France";
} | {
    readonly value: "uk";
    readonly label: "United Kingdom";
}

// Extracts just the value type
// Expected type: type CountryCode = "jp" | "kr" | "vn" | "de" | "fr" | "uk"
CountryCode = ExtractOptionValue<typeof countryOptions, "value">

```

--------------------------------

### TypedRadioGroup Basic Usage with String Values (TypeScript)

Source: https://typedora-ui.netlify.app/docs/components/typed-radio-group

Demonstrates the basic usage of the TypedRadioGroup component with string values. It takes an array of options with 'label' and 'value' properties and handles value changes via a callback function.

```tsx
import { TypedRadioGroup } from "@/components/typed-radio-group";

export function BasicUsage() {
  return (
    <div>
      <TypedRadioGroup
        options={[
          { label: "Apple", value: "apple" },
          { label: "Banana", value: "banana" },
          { label: "Orange", value: "orange" },
        ]}
        onValueChange={(value) => {
                        
value: string
        }}
      />
    </div>
  );
}
```

--------------------------------

### With Search Filter

Source: https://typedora-ui.netlify.app/docs/components/typed-select

Illustrates how to integrate a search input with the TypedSelect component to filter options dynamically.

```APIDOC
## Search Filter Example

### Description
This example demonstrates how to add a search input to filter the options displayed in the `TypedSelect` component. The `renderContent` prop is used to inject a custom search input, and event handlers prevent interference with the select's behavior.

### Component
`TypedSelect`

### Usage
```typescript
import { useState } from "react";
import { TypedSelect } from "@/components/typed-select";
import { Input } from "@/components/ui/input";

export function SearchFilter() {
  const [search, setSearch] = useState("");

  const allOptions = [
    { label: "Apple", value: "apple" },
    { label: "Banana", value: "banana" },
    { label: "Cherry", value: "cherry" },
  ];

  const filteredOptions = allOptions.filter((opt) =>
    opt.label.toLowerCase().includes(search.toLowerCase()),
  );

  return (
    <TypedSelect
      options={filteredOptions}
      renderContent={({ children, Content }) => (
        <Content
          // Prevent Select from closing when clicking inside the search input
          onPointerDownOutside={(e) => {
            const target = e.target as HTMLElement;
            if (target.closest("input")) {
              e.preventDefault();
            }
          }}
        >
          <div className="p-2 border-b" onKeyDown={(e) => e.stopPropagation()}>
            <Input
              placeholder="Search..."
              value={search}
              onChange={(e) => setSearch(e.target.value)}
              // Prevent focus management interference from Radix
              onPointerDown={(e) => e.stopPropagation()}
            />
          </div>
          {children}
        </Content>
      )}
    />
  );
}
```

### Props Used
- `options`: The array of options to display (filtered in this example).
- `renderContent`: A function to customize the content wrapper of the select dropdown, used here to add a search input.
```

--------------------------------

### TypedSelect Component Usage in React

Source: https://typedora-ui.netlify.app/docs

Demonstrates how to use the TypedSelect component in a React application. It shows importing the component, defining options with a specific type, and handling value changes with type inference.

```typescript
import { TypedSelect } from "@/components/typed-select";

const fruits = [
  { value: "apple", label: "Apple" },
  { value: "banana", label: "Banana" },
  { value: "orange", label: "Orange" },
] as const;

<TypedSelect
  options={fruits}
  onValueChange={(value) => {
                  
value: "apple" | "banana" | "orange"
  }}
/>
```

--------------------------------

### Defining Options Outside Components (TypeScript)

Source: https://typedora-ui.netlify.app/docs/utils/typed-utils

Illustrates the best practice of defining options arrays outside of React components to ensure stable type inference and prevent unnecessary re-creations on each render. This maintains referential equality.

```typescript
// Good - defined outside
const options = [...] as const;

function MyComponent() {
  return <TypedSelect options={options} />;
}

// Avoid - recreated on each render
function MyComponent() {
  const options = [...] as const; // recreated
  return <TypedSelect options={options} />;
}
```

--------------------------------

### shadcn/ui Select (Type Unsafe)

Source: https://typedora-ui.netlify.app/index

Demonstrates the type-unsafe nature of the standard shadcn/ui Select component. It shows how numeric IDs must be converted to strings for the `value` prop and how `onValueChange` returns a string, losing original type information and potentially causing runtime errors.

```typescript
// Your data has number IDs
const users: Users = [
  { id: 1, name: "Alice" },
  { id: 2, name: "Bob" },
];

<SelectItem
  key={user.id}
  value={String(user.id)} // "1", "2"
>
  {user.name}
</SelectItem>

onValueChange={(value) => {
  // value: string - type info lost!
  const userId = Number(value);
  // Could be NaN, no type error!
}}
```

--------------------------------

### TypedSelect Component Props

Source: https://typedora-ui.netlify.app/docs/components/typed-select

Detailed reference of the props available for the TypedSelect component and their types.

```APIDOC
## TypedSelect Component API

### Props

| Prop | Type | Description |
|---|---|---|
| `options` | `array` | An array of options for the select component. |
| `valueKey?` | `TValueKey` | The key to use for the option's value. Defaults to `value`. |
| `labelKey?` | `TLabelKey` | The key to use for the option's label. Defaults to `label`. |
| `value?` | `ExtractOptionValue<TOption, TValueKey>` | The current selected value. |
| `defaultValue?` | `ExtractOptionValue<TOption, TValueKey>` | The default selected value when the component first mounts. |
| `onValueChange?` | `function` | Callback function that is called when the selected value changes. |
| `placeholder?` | `string` | Placeholder text to display when no option is selected. |
| `renderTrigger?` | `function` | Function to customize the rendering of the trigger element. |
| `renderItem?` | `function` | Function to customize the rendering of each item in the dropdown. |
| `renderGroup?` | `function` | Function to customize the rendering of option groups. |
| `renderContent?` | `function` | Function to customize the rendering of the dropdown content wrapper. |
| `disabled?` | `boolean` | Whether the select component is disabled. |
| `open?` | `boolean` | Controls whether the dropdown is open or closed. |
| `onOpenChange?` | `function` | Callback function called when the open state changes. |
| `name?` | `string` | The name attribute for the select input. |
| `required?` | `boolean` | Whether the select component is required. |

### Helper Types

#### `SelectOption`

| Prop | Type | Description |
|---|---|---|
| `value` | `T` | The value of the option. |
| `label` | `string` | The display label of the option. |
| `disabled?` | `boolean` | Whether the option is disabled. |

#### `SelectOptionGroup`

| Prop | Type | Description |
|---|---|---|
| `label` | `string` | The label for the option group. |
| `options` | `array` | An array of options within the group. |

#### `SelectTriggerRenderProps`

| Prop | Type | Description |
|---|---|---|
| `selectedOption` | `TOption | undefined` | The currently selected option. |
| `placeholder` | `string` | The placeholder text. |
| `open` | `boolean` | Indicates if the dropdown is open. |
| `disabled` | `boolean` | Indicates if the component is disabled. |
| `Trigger` | `function` | A component to render the trigger. |
| `Value` | `function` | A component to render the selected value. |

#### `SelectItemRenderProps`

| Prop | Type | Description |
|---|---|---|
| `option` | `TOption` | The option being rendered. |
| `isSelected` | `boolean` | Indicates if the option is currently selected. |
| `isDisabled` | `boolean` | Indicates if the option is disabled. |
| `group` | `SelectOptionGroup<TOption> | undefined` | The group the option belongs to, if any. |
| `itemProps` | `object` | Props to be spread onto the rendered item. |
| `Item` | `function` | A component to render the item. |

#### `SelectGroupRenderProps`

| Prop | Type | Description |
|---|---|---|
| `group` | `SelectOptionGroup<TOption>` | The option group being rendered. |
| `children` | `ReactNode` | The rendered options within the group. |
| `Group` | `function` | A component to render the group wrapper. |
| `Label` | `function` | A component to render the group label. |
```

--------------------------------

### TypedRadioGroup Card Style Customization (TypeScript)

Source: https://typedora-ui.netlify.app/docs/components/typed-radio-group

Demonstrates advanced customization of TypedRadioGroup using the `renderItem` prop to create a card-like selection interface. Includes conditional styling based on selection state and custom content like descriptions.

```tsx
import { CheckIcon } from "lucide-react";
import { TypedRadioGroup } from "@/components/typed-radio-group";
import { cn } from "@/lib/utils";

export function CardStyle() {
  return (
    <div className="not-prose">
      <TypedRadioGroup
        defaultValue="free"
        className="grid grid-cols-3 gap-4"
        options={[
          { value: "free", label: "Free", description: "Basic features" },
          { value: "pro", label: "Pro", description: "Advanced features" },
          { value: "team", label: "Team", description: "For teams" },
        ]}
        renderItem={({ option, isSelected, itemProps, Item }) => (
          <label
            htmlFor={itemProps.id}
            className={cn(
              "relative flex flex-col p-4 border rounded-lg cursor-pointer",
              isSelected ? "border-primary bg-primary/5" : "border-border",
            )}
          >
            <Item {...itemProps} className="sr-only" />
            {isSelected && (
              <CheckIcon className="absolute top-3 right-3 size-4 text-primary" />
            )}
            <div className="grid grow gap-2">
              <p className="font-semibold">{option.label}</p>
              <p
                className="text-muted-foreground text-xs"
                id={`${itemProps.id}-description`}
              >
                {option.description}
              </p>
            </div>
          </label>
        )}
      />
    </div>
  );
}
```

--------------------------------

### Grouped Options with Typed Combobox (TypeScript/React)

Source: https://typedora-ui.netlify.app/docs/components/typed-combobox

Demonstrates how to use the Typed Combobox to display options categorized into groups, such as 'Frontend' and 'Backend' technologies. It utilizes a predefined array of objects with 'label' and 'options' properties. The component supports placeholder text and search functionality.

```tsx
import { TypedCombobox } from "@/components/typed-combobox";

const groupedOptions = [
  {
    label: "Frontend",
    options: [
      { label: "React", value: "react" },
      { label: "Vue", value: "vue" },
      { label: "Svelte", value: "svelte" },
    ],
  },
  {
    label: "Backend",
    options: [
      { label: "Node.js", value: "nodejs" },
      { label: "Python", value: "python" },
      { label: "Go", value: "go" },
    ],
  },
] as const;

export function GroupedOptions() {
  return (
    <TypedCombobox
      placeholder="Select a technology..."
      searchPlaceholder="Search technologies..."
      options={groupedOptions}
      popoverWidth={250}
      onValueChange={(value) => {
                      
value: "react" | "vue" | "svelte" | "nodejs" | "python" | "go"
        console.log(value);
      }}
    />
  );
}
```

--------------------------------

### Custom Keys (id/name)

Source: https://typedora-ui.netlify.app/docs/components/typed-select

Explains how to customize the keys used for values and labels in the TypedSelect component.

```APIDOC
## Custom Keys Example

### Description
This example demonstrates how to use the `valueKey` and `labelKey` props to specify custom property names for the value and label of each option in the `TypedSelect` component. It also shows how to customize the rendering of individual items.

### Component
`TypedSelect`

### Usage
```typescript
import { useState } from "react";
import { TypedSelect } from "@/components/typed-select";

// Example data using id/name keys instead of value/label

type User = {
  id: number;
  name: string;
  email: string;
};

const users: User[] = [
  { id: 1, name: "John Doe", email: "john@example.com" },
  { id: 2, name: "Jane Smith", email: "jane@example.com" },
  { id: 3, name: "Bob Johnson", email: "bob@example.com" },
];

export function CustomKeys() {
  const [selectedId, setSelectedId] = useState<User["id"]>();

  return (
    <div className="space-y-4">
      <TypedSelect
        placeholder="Select a user"
        options={users}
        valueKey="id"
        labelKey="name"
        value={selectedId}
        onValueChange={setSelectedId}
        renderItem={({ option, itemProps, Item }) => (
          <Item {...itemProps} className="flex flex-col items-start py-2">
            <span className="font-medium">{option.name}</span>
            <span className="text-sm text-muted-foreground">
              {option.email}
            </span>
          </Item>
        )}
      />
      {selectedId && (
        <p className="text-sm text-muted-foreground">
          Selected user ID: <strong>{selectedId}</strong>
        </p>
      )}
    </div>
  );
}
```

### Props Used
- `placeholder`: Text to display when no option is selected.
- `options`: An array of user objects.
- `valueKey`: Set to "id" to use the `id` property as the option value.
- `labelKey`: Set to "name" to use the `name` property as the option label.
- `value`: The state variable holding the selected user's ID.
- `onValueChange`: Function to update the `selectedId` state.
- `renderItem`: Function to customize how each selectable item is rendered, displaying name and email.
```

--------------------------------

### Controlled Component

Source: https://typedora-ui.netlify.app/docs/components/typed-select

Demonstrates how to use the TypedSelect component in a controlled manner, managing the selected value with React's useState hook.

```APIDOC
## Controlled Component Example

### Description
This example shows how to manage the selected value of the `TypedSelect` component using the `useState` hook. The `value` prop is controlled by the component's state, and `onValueChange` updates this state.

### Component
`TypedSelect`

### Usage
```typescript
import { useState } from "react";
import { TypedSelect } from "@/components/typed-select";

type User = {
  id: string;
  name: string;
};

const users: User[] = [
  { id: "1", name: "Alice" },
  { id: "2", name: "Bob" },
  { id: "3", name: "Charlie" },
];

export function Controlled() {
  const [value, setValue] = useState<User["id"]>(users[0].id);

  return (
    <div className="space-y-4">
      <TypedSelect
        value={value}
        options={users}
        valueKey="id"
        labelKey="name"
        onValueChange={setValue}
      />
      <p>Selected: {value}</p>
    </div>
  );
}
```

### Props Used
- `value`: The currently selected value.
- `options`: An array of selectable items.
- `valueKey`: The key in the option objects that represents the value.
- `labelKey`: The key in the option objects that represents the display label.
- `onValueChange`: Callback function triggered when the selected value changes.
```

--------------------------------

### Custom Keys in TypedRadioGroup (TypeScript)

Source: https://typedora-ui.netlify.app/docs/components/typed-radio-group

Demonstrates how to customize the value and label keys for TypedRadioGroup using `valueKey` and `labelKey` props. This allows using different key names (e.g., 'id', 'name') in the options data instead of the default 'value' and 'label'.

```typescript
"use client";

import { useState } from "react";
import { TypedRadioGroup } from "@/components/typed-radio-group";
import { Label } from "@/components/ui/label";

// Example data using id/name keys instead of value/label
const roles = [
  {
    id: "admin",
    name: "Administrator",
    description: "Full access to all features",
  },
  { id: "editor", name: "Editor", description: "Can edit content" },
  { id: "viewer", name: "Viewer", description: "Read-only access" },
] as const;

export function CustomKeys() {
  const [selectedId, setSelectedId] = useState<(typeof roles)[number]["id"]>();

  return (
    <div className="space-y-4">
      <Label>Select Role</Label>
      <TypedRadioGroup
        options={roles}
        valueKey="id"
        labelKey="name"
        value={selectedId}
        onValueChange={setSelectedId}
        renderItem={({ option, itemProps, Item, Indicator }) => (
          <label
            htmlFor={itemProps.id}
            className="flex items-start gap-3 cursor-pointer p-3 rounded-lg border hover:bg-accent"
          >
            <Item {...itemProps} className="mt-1">
              <Indicator />
            </Item>
            <div className="flex flex-col">
              <span className="font-medium">{option.name}</span>
              <span className="text-sm text-muted-foreground">
                {option.description}
              </span>
            </div>
          </label>
        )}
      />
      {selectedId && (
        <p className="text-sm text-muted-foreground">
          Selected role: <strong>{selectedId}</strong>
        </p>
      )}
    </div>
  );
}

```

--------------------------------

### Custom Keys with Typed Combobox (TypeScript/React)

Source: https://typedora-ui.netlify.app/docs/components/typed-combobox

Explains how to customize the keys used for identifying and displaying options in the Typed Combobox. By using 'valueKey' and 'labelKey' props, you can map different property names from your option objects (e.g., 'id' and 'name') to the component's expected 'value' and 'label' fields.

```tsx
import { TypedCombobox } from "@/components/typed-combobox";

const users = [
  { id: 1, name: "John Doe", email: "john@example.com" },
  { id: 2, name: "Jane Smith", email: "jane@example.com" },
  { id: 3, name: "Bob Johnson", email: "bob@example.com" },
] as const;

export function CustomKeys() {
  return (
    <TypedCombobox
      placeholder="Select a user..."
      searchPlaceholder="Search users..."
      options={users}
      valueKey="id"
      labelKey="name"
      popoverWidth={250}
      onValueChange={(value) => {
                      
value: 1 | 2 | 3
        console.log(value);
      }}
    />
  );
}
```

--------------------------------

### Custom Item Rendering in TypedSelect (TypeScript)

Source: https://typedora-ui.netlify.app/docs/components/typed-select

Demonstrates advanced customization of TypedSelect items using the `renderItem` prop. This allows for richer item displays including descriptions, while maintaining type safety.

```typescript
import { TypedSelect } from "@/components/typed-select";

export function CustomItem() {
  return (
    <div>
      <TypedSelect
        placeholder="Select a plan"
        options={[
          { label: "Free", value: "free", description: "For personal use" },
          { label: "Pro", value: "pro", description: "For professionals" },
          { label: "Team", value: "team", description: "For small teams" },
        ]}
        renderItem={({ option, itemProps, Item }) => (
          <Item {...itemProps} className="flex flex-col items-start py-2">
            <span className="font-medium">{option.label}</span>
            <span className="text-sm text-muted-foreground">
              {option.description}
            </span>
          </Item>
        )}
      />
    </div>
  );
}

```

--------------------------------

### Extract Option Type from Flat Array (TypeScript)

Source: https://typedora-ui.netlify.app/docs/utils/typed-utils

Demonstrates using the `ExtractOption` utility type to extract the type of individual options from a flat, 'as const' array. This is useful for strongly typing individual option objects.

```typescript
import type { ExtractOption } from "@/lib/typed-utils";

// Flat options
const fruits = [
  { value: "apple", label: "Apple" },
  { value: "banana", label: "Banana" },
] as const;

type Fruit = ExtractOption<typeof fruits>;
     
// Expected type: 
type Fruit = {
    readonly value: "apple";
    readonly label: "Apple";
} | {
    readonly value: "banana";
    readonly label: "Banana";
}

```

--------------------------------

### TypedRadioGroup Usage with Number Values (TypeScript)

Source: https://typedora-ui.netlify.app/docs/components/typed-radio-group

Illustrates how to use TypedRadioGroup with number values. Options are defined with numeric 'value' properties, and the `onValueChange` callback receives a number.

```tsx
import { TypedRadioGroup } from "@/components/typed-radio-group";

export function NumberValues() {
  return (
    <div>
      <TypedRadioGroup
        options={[
          { label: "Small", value: 1 },
          { label: "Medium", value: 2 },
          { label: "Large", value: 3 },
        ]}
        onValueChange={(value) => {
                        
value: number
        }}
      />
    </div>
  );
}
```

--------------------------------

### Extract Option Value Type by Key (TypeScript)

Source: https://typedora-ui.netlify.app/docs/utils/typed-utils

Demonstrates using the `ExtractOptionValue` utility type to extract the type of a specific value property (e.g., 'value' or 'id') from an options array. This is useful for typing state variables that hold selected values.

```typescript
import type { ExtractOptionValue } from "@/lib/typed-utils";

// With default "value" key
const fruits = [
  { value: "apple", label: "Apple" },
  { value: "banana", label: "Banana" },
  { value: "orange", label: "Orange" },
] as const;

type FruitValue = ExtractOptionValue<typeof fruits, "value">;
// Expected type: type FruitValue = "apple" | "banana" | "orange"


// With custom "id" key
const users = [
  { id: 1, name: "Alice" },
  { id: 2, name: "Bob" },
  { id: 3, name: "Charlie" },
] as const;

type UserId = ExtractOptionValue<typeof users, "id">;
// Expected type: type UserId = 3 | 1 | 2

```

--------------------------------

### TypedSelect (Type Safe)

Source: https://typedora-ui.netlify.app/index

Illustrates the type-safe usage of TypedSelect. It allows direct use of data with number IDs without manual string conversion. The `onValueChange` callback correctly receives the original data type, preserving type information and preventing runtime errors.

```typescript
// Same data structure
const users: Users = [
  { id: 1, name: "Alice" },
  { id: 2, name: "Bob" },
];

<TypedSelect
  options={users}
  valueKey="id"
  labelKey="name"
  onValueChange={setUserId}
/>

onValueChange={(valuevalue: number) => {
  ...
}}
```

--------------------------------

### Extract Option Type from Grouped Array (TypeScript)

Source: https://typedora-ui.netlify.app/docs/utils/typed-utils

Demonstrates using the `ExtractOption` utility type to extract the type of individual options from a grouped, 'as const' array. It correctly flattens the structure to provide the option types.

```typescript
import type { ExtractOption } from "@/lib/typed-utils";

// Grouped options 
const groupedFruits = [
  {
    label: "Tropical",
    options: [
      { value: "mango", label: "Mango" },
      { value: "pineapple", label: "Pineapple" },
    ],
  },
] as const;

type GroupedFruit = ExtractOption<typeof groupedFruits>;

// Expected type:
type GroupedFruit = {
    readonly value: "mango";
    readonly label: "Mango";
} | {
    readonly value: "pineapple";
    readonly label: "Pineapple";
}

```

--------------------------------

### Extract Option Value by Key (TypeScript)

Source: https://typedora-ui.netlify.app/docs/utils/typed-utils

Extracts the type of a specific value from options within an options array, based on a provided key. It first extracts the option type using ExtractOption and then accesses the specified key. The input array must be readonly, and the key must be a string literal.

```typescript
type ExtractOptionValue<TOptions, TValueKey extends string> = ExtractOption<TOptions> extends infer O
  ? O extends Record<string, unknown>
    ? TValueKey extends keyof O
      ? O[TValueKey] & {}
      : never
    : never
  : never;
```

--------------------------------

### TypedRadioGroup Usage with Boolean Values (TypeScript)

Source: https://typedora-ui.netlify.app/docs/components/typed-radio-group

Shows the implementation of TypedRadioGroup using boolean values for options. The `onValueChange` handler will receive a boolean value upon selection.

```tsx
import { TypedRadioGroup } from "@/components/typed-radio-group";

export function BooleanValues() {
  return (
    <div>
      <TypedRadioGroup
        options={[
          { label: "Yes", value: true },
          { label: "No", value: false },
        ]}
        onValueChange={(value) => {
                        
value: boolean
        }}
      />
    </div>
  );
}
```

--------------------------------

### Controlled Component with Typed Combobox (TypeScript/React)

Source: https://typedora-ui.netlify.app/docs/components/typed-combobox

Shows how to manage the state of the Typed Combobox as a controlled component. The 'value' prop is bound to a state variable, and 'onValueChange' updates this state. This allows for programmatic control over the selected option and displaying the current selection.

```tsx
"use client";

import { useState } from "react";
import { TypedCombobox } from "@/components/typed-combobox";

const frameworks = [
  { label: "Next.js", value: "nextjs" },
  { label: "Remix", value: "remix" },
  { label: "Astro", value: "astro" },
  { label: "SvelteKit", value: "sveltekit" },
] as const;

type FrameworkValue = (typeof frameworks)[number]["value"];

export function Controlled() {
  const [value, setValue] = useState<FrameworkValue>("nextjs");

  return (
    <div className="space-y-4">
      <TypedCombobox
        placeholder="Select a framework..."
        searchPlaceholder="Search..."
        options={frameworks}
        value={value}
        onValueChange={setValue}
      />
      <p className="text-sm text-muted-foreground">
        Selected: <code className="font-mono">{value}</code>
      </p>
    </div>
  );
}
```

--------------------------------

### TypedSelect with Grouped Options in TypeScript

Source: https://typedora-ui.netlify.app/docs/components/typed-select

Shows how to organize options within groups in TypedSelect. The component correctly infers the selected value type from all options across all groups, ensuring comprehensive type safety.

```typescript
import { TypedSelect } from "@/components/typed-select";

export function GroupedOptions() {
  return (
    <div>
      <TypedSelect
        options={
          [
            {
              label: "Fruits",
              options: [
                { label: "Apple", value: "apple" },
                { label: "Banana", value: "banana" },
              ],
            },
            {
              label: "Vegetables",
              options: [
                { label: "Carrot", value: "carrot" },
                { label: "Broccoli", value: "broccoli" },
              ],
            },
          ] as const
        }
        onValueChange={(value) => {
                        
value: "apple" | "banana" | "carrot" | "broccoli"
        }}
      />
    </div>
  );
}

```

--------------------------------

### Controlled TypedRadioGroup Component (TypeScript)

Source: https://typedora-ui.netlify.app/docs/components/typed-radio-group

Illustrates how to implement a controlled TypedRadioGroup component. The component's selected value is managed by React's `useState` hook, and the `onValueChange` prop is used to update this state, providing full control over the component's behavior.

```typescript
"use client";

import { useState } from "react";
import { TypedRadioGroup } from "@/components/typed-radio-group";

export function Controlled() {
  const [value, setValue] = useState<"apple" | "banana">("apple");

  return (
    <div className="space-y-4">
      <TypedRadioGroup
        value={value}
        options={
          [
            { label: "Apple", value: "apple" },
            { label: "Banana", value: "banana" },
          ] as const
        }
        onValueChange={setValue}
      />
      <p>Selected: {value}</p>
    </div>
  );
}

```

--------------------------------

### Controlled TypedSelect Component (React)

Source: https://typedora-ui.netlify.app/docs/components/typed-select

Demonstrates how to use TypedSelect as a controlled component in React. It manages the selected value using the useState hook and passes it to the TypedSelect component, along with options and a callback for value changes. The selected value is displayed below the select input.

```typescript
"use client";

import { useState } from "react";
import { TypedSelect } from "@/components/typed-select";

type User = {
  id: string;
  name: string;
};

const users: User[] = [
  { id: "1", name: "Alice" },
  { id: "2", name: "Bob" },
  { id: "3", name: "Charlie" },
];

export function Controlled() {
  const [value, setValue] = useState<User["id"]>(users[0].id);

  return (
    <div className="space-y-4">
      <TypedSelect
        value={value}
        options={users}
        valueKey="id"
        labelKey="name"
        onValueChange={setValue}
      />
      <p>Selected: {value}</p>
    </div>
  );
}

```

--------------------------------

### Custom Filter Function with Typed Combobox (TypeScript/React)

Source: https://typedora-ui.netlify.app/docs/components/typed-combobox

Demonstrates customizing the search behavior of Typed Combobox using the 'filterFn' prop. This allows searching across multiple fields of an option object, such as name, email, and role, providing a more flexible search experience. It requires 'options' and 'onValueChange' props.

```tsx
import { TypedCombobox } from "@/components/typed-combobox";

const users = [
  { id: 1, name: "John Doe", email: "john@example.com", role: "admin" },
  { id: 2, name: "Jane Smith", email: "jane@example.com", role: "user" },
  { id: 3, name: "Bob Johnson", email: "bob@example.com", role: "admin" },
  { id: 4, name: "Alice Brown", email: "alice@example.com", role: "user" },
] as const;

export function CustomFilter() {
  return (
    <TypedCombobox
      placeholder="Search by name, email, or role..."
      searchPlaceholder="Type to search..."
      options={users}
      valueKey="id"
      labelKey="name"
      popoverWidth={300}
      filterFn={(option, query) => {
        const q = query.toLowerCase();
        return (
          option.name.toLowerCase().includes(q) ||
          option.email.toLowerCase().includes(q) ||
          option.role.toLowerCase().includes(q)
        );
      }}
      onValueChange={(value) => {
        console.log(value);
      }}
    />
  );
}
```

--------------------------------

### Extract Option Type from Array (TypeScript)

Source: https://typedora-ui.netlify.app/docs/utils/typed-utils

Extracts the inner option type from a given options array. It handles both flat and grouped options (where options are nested under an 'options' property). Requires the input array to be a readonly tuple.

```typescript
type ExtractOption<TOptions> = TOptions extends readonly (infer T)[]
  ? T extends { options: readonly (infer O)[] } 
    ? O
    : T
  : never;
```