### Install Dependencies

Source: https://github.com/ncdai/react-wheel-picker/blob/main/CONTRIBUTING.md

Install all project dependencies using pnpm.

```bash
pnpm install
```

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

### Run Documentation Locally

Source: https://github.com/ncdai/react-wheel-picker/blob/main/CONTRIBUTING.md

Start the documentation development server for the 'web' workspace.

```bash
pnpm --filter=web dev
```

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

### Install React Wheel Picker Primitives

Source: https://github.com/ncdai/react-wheel-picker/blob/main/apps/web/src/content/docs/getting-started.mdx

Use this command to install the core React Wheel Picker package if you are not using shadcn/ui.

```bash
npm install @ncdai/react-wheel-picker
```

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

### Complete Configuration Example

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/configuration.md

A comprehensive example demonstrating how to configure all WheelPicker props, including options, default value, infinite scrolling, visible count, sensitivities, item height, and custom class names. It also includes importing necessary components and CSS.

```tsx
import { WheelPicker, WheelPickerWrapper } from "@ncdai/react-wheel-picker";
import "@ncdai/react-wheel-picker/style.css";
import "./custom-picker.css";

export function FullyConfiguredPicker() {
  const numbers = Array.from({ length: 100 }, (_, i) => ({
    label: String(i).padStart(3, "0"),
    value: i,
    disabled: i % 10 === 0, // Every 10th item is disabled
  }));

  return (
    <WheelPickerWrapper className="demo-wrapper">
      <WheelPicker
        options={numbers}
        defaultValue={50}
        infinite={true}
        visibleCount={12}
        optionItemHeight={36}
        dragSensitivity={2}
        scrollSensitivity={4}
        onValueChange={(val) => console.log("Selected:", val)}
        classNames={{
          optionItem: "number-item",
          highlightWrapper: "number-highlight-zone",
          highlightItem: "number-highlight-value",
        }}
      />
    </WheelPickerWrapper>
  );
}
```

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

### Run Development Server with Bun

Source: https://github.com/ncdai/react-wheel-picker/blob/main/apps/web/README.md

Use this command to start the Next.js development server using Bun.

```bash
bun dev
```

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

### Minimal Wheel Picker Example

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/README.md

A basic example demonstrating how to use the WheelPicker component with options and an onValueChange handler. Ensure the CSS is imported.

```tsx
import { WheelPicker } from "@ncdai/react-wheel-picker";
import "@ncdai/react-wheel-picker/style.css";

export function App() {
  const options = [
    { label: "Option A", value: "a" },
    { label: "Option B", value: "b" },
    { label: "Option C", value: "c" },
  ];

  return (
    <WheelPicker
      options={options}
      defaultValue="a"
      onValueChange={(value) => console.log("Selected:", value)}
    />
  );
}
```

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

### Run Development Server with npm

Source: https://github.com/ncdai/react-wheel-picker/blob/main/apps/web/README.md

Use this command to start the Next.js development server using npm.

```bash
npm run dev
```

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

### Multiple Pickers with Navigation Example

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/api-reference/wheel-picker-wrapper.md

Illustrates using WheelPickerWrapper to group multiple WheelPicker components (e.g., for a time picker). This setup enables keyboard navigation between pickers using ArrowLeft and ArrowRight keys.

```tsx
import { WheelPicker, WheelPickerWrapper } from "@ncdai/react-wheel-picker";
import "@ncdai/react-wheel-picker/style.css";

export function MultiPickerExample() {
  const hours = Array.from({ length: 24 }, (_, i) => ({
    label: String(i).padStart(2, "0"),
    value: i,
  }));

  const minutes = Array.from({ length: 60 }, (_, i) => ({
    label: String(i).padStart(2, "0"),
    value: i,
  }));

  const seconds = Array.from({ length: 60 }, (_, i) => ({
    label: String(i).padStart(2, "0"),
    value: i,
  }));

  return (
    <WheelPickerWrapper className="time-picker">
      <WheelPicker options={hours} defaultValue={0} />
      <WheelPicker options={minutes} defaultValue={0} />
      <WheelPicker options={seconds} defaultValue={0} />
    </WheelPickerWrapper>
  );
}

Navigate between pickers using ArrowLeft/ArrowRight keys.
```

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

### Run Development Server with pnpm

Source: https://github.com/ncdai/react-wheel-picker/blob/main/apps/web/README.md

Use this command to start the Next.js development server using pnpm.

```bash
pnpm dev
```

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

### Install shadcn/ui Wheel Picker

Source: https://github.com/ncdai/react-wheel-picker/blob/main/apps/web/src/content/docs/getting-started.mdx

Use this command to add the wheel picker component to your shadcn/ui project.

```bash
npx shadcn add @ncdai/wheel-picker
```

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

### Run Development Server with Yarn

Source: https://github.com/ncdai/react-wheel-picker/blob/main/apps/web/README.md

Use this command to start the Next.js development server using Yarn.

```bash
yarn dev
```

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

### Multi-Picker with Status Display and Navigation Hint

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/api-reference/use-wheel-picker-group.md

An example showcasing a multi-picker setup (hours and minutes) within a WheelPickerWrapper. It includes a custom PickerNavigationHint component that uses useWheelPickerGroup to display navigation instructions (e.g., 'Use ← → to navigate') when multiple pickers are present. This component should be rendered as a child of WheelPickerWrapper.

```tsx
import { WheelPicker, WheelPickerWrapper } from "@ncdai/react-wheel-picker";
import { useWheelPickerGroup } from "@ncdai/react-wheel-picker";
import "@ncdai/react-wheel-picker/style.css";

function PickerNavigationHint() {
  const group = useWheelPickerGroup();

  if (!group) return null;

  const indices = group.getPickerIndices();
  const currentPos = indices.indexOf(group.activeIndex);
  const hasMultiple = indices.length > 1;

  return (
    <div style={{ marginTop: "10px", fontSize: "12px", color: "#666" }}>
      {hasMultiple && (
        <p>
          Picker {currentPos + 1} of {indices.length} · Use ← → to navigate
        </p>
      )}
    </div>
  );
}

export function DateTimePickerWithHint() {
  const hours = Array.from({ length: 24 }, (_, i) => ({
    label: String(i).padStart(2, "0"),
    value: i,
  }));

  const minutes = Array.from({ length: 60 }, (_, i) => ({
    label: String(i).padStart(2, "0"),
    value: i,
  }));

  return (
    <WheelPickerWrapper className="datetime-picker">
      <WheelPicker options={hours} defaultValue={12} />
      <WheelPicker options={minutes} defaultValue={0} />
      <PickerNavigationHint />
    </WheelPickerWrapper>
  );
}
```

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

### WheelPickerWrapper Usage Example

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/types.md

Demonstrates how to use the WheelPickerWrapper component with and without custom styling. The CSS example shows how to apply custom styles to the wrapper.

```tsx
<WheelPickerWrapper className="time-picker-container">
  <WheelPicker options={hours} defaultValue={12} />
  <WheelPicker options={minutes} defaultValue={0} />
</WheelPickerWrapper>
```

```tsx
<WheelPickerWrapper className="custom-picker">
  <WheelPicker options={options1} defaultValue={value1} />
  <WheelPicker options={options2} defaultValue={value2} />
</WheelPickerWrapper>
```

```css
.custom-picker {
  gap: 20px;
  padding: 20px;
  background: white;
  border-radius: 8px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}
```

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

### WheelPicker Option Type Examples

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/types.md

Illustrates how to define `WheelPickerOption` types for string and number values, and provides examples of using `WheelPicker` with different generic type parameters for string and number options.

```tsx
// String values (default)
type StringPicker = WheelPickerOption<string>;

// Number values
type NumberPicker = WheelPickerOption<number>;

// Using the component
<WheelPicker<"red" | "green" | "blue">
  options={colorOptions}
/>

<WheelPicker<1 | 2 | 3 | 4 | 5>
  options={ratingOptions}
/>
```

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

### Basic Primitives Wheel Picker Usage

Source: https://github.com/ncdai/react-wheel-picker/blob/main/apps/web/src/content/docs/getting-started.mdx

Demonstrates the basic setup for the Wheel Picker component using primitives.

```tsx
import {
  WheelPicker,
  WheelPickerWrapper,
  type WheelPickerOption,
} from "@ncdai/react-wheel-picker";
```

```tsx
const options: WheelPickerOption[] = [
  {
    label: "Next.js",
    value: "nextjs",
  },
  {
    label: "Vite",
    value: "vite",
  },
  // ...
];

export function WheelPickerDemo() {
  const [value, setValue] = useState("nextjs");

  return (
    <WheelPickerWrapper>
      <WheelPicker options={options} value={value} onValueChange={setValue} />
    </WheelPickerWrapper>
  );
}
```

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

### Minimal Setup for Wheel Picker

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/exports.md

Import the WheelPicker component and its CSS for basic usage. Ensure you provide options and a default value.

```tsx
import { WheelPicker } from "@ncdai/react-wheel-picker";
import "@ncdai/react-wheel-picker/style.css";

const options = [
  { label: "Option 1", value: "opt1" },
  { label: "Option 2", value: "opt2" },
];

<WheelPicker options={options} defaultValue="opt1" />;
```

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

### Single Picker Example

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/api-reference/wheel-picker-wrapper.md

Demonstrates how to use WheelPickerWrapper with a single WheelPicker component. Ensure to import the necessary components and the CSS file.

```tsx
import { WheelPicker, WheelPickerWrapper } from "@ncdai/react-wheel-picker";
import "@ncdai/react-wheel-picker/style.css";

export function SinglePickerExample() {
  const options = [
    { label: "Option A", value: "a" },
    { label: "Option B", value: "b" },
  ];

  return (
    <WheelPickerWrapper className="my-picker-wrapper">
      <WheelPicker options={options} defaultValue="a" />
    </WheelPickerWrapper>
  );
}
```

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

### Usage of WheelPickerWrapper Component

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/exports.md

Example demonstrating the use of WheelPickerWrapper to group multiple WheelPicker instances.

```tsx
<WheelPickerWrapper className="my-picker-group">
  <WheelPicker options={options1} />
  <WheelPicker options={options2} />
</WheelPickerWrapper>
```

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

### Usage of WheelPicker Component

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/exports.md

Example of how to use the WheelPicker component with options, a value, and a change handler.

```tsx
<WheelPicker
  options={options}
  value={selected}
  onValueChange={setSelected}
/>
```

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

### WheelPicker Component Usage Examples

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/types.md

Illustrates different ways to use the WheelPicker component, including uncontrolled, controlled, and customized configurations.

```tsx
type Options = "small" | "medium" | "large";

const options: WheelPickerOption<Options>[] = [
  { label: "Small", value: "small" },
  { label: "Medium", value: "medium" },
  { label: "Large", value: "large" },
];

// Uncontrolled
<WheelPicker
  options={options}
  defaultValue="medium"
  onValueChange={(value) => console.log("Selected:", value)}
/>

// Controlled
const [size, setSize] = useState<Options>("medium");
<WheelPicker
  options={options}
  value={size}
  onValueChange={setSize}
/>

// With customization
<WheelPicker
  options={options}
  defaultValue="medium"
  infinite={false}
  visibleCount={8}
  optionItemHeight={40}
  dragSensitivity={2}
  scrollSensitivity={3}
  classNames={{
    optionItem: "size-option",
    highlightWrapper: "size-highlight",
    highlightItem: "size-label",
  }}
/>
```

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

### Multi-Picker Group Example

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/INDEX.md

Shows how to group multiple WheelPicker components using WheelPickerWrapper to create a composite picker, such as a date picker.

```tsx
<WheelPickerWrapper className="date-picker">
  <WheelPicker options={months} defaultValue={1} />
  <WheelPicker options={days} defaultValue={15} />
  <WheelPicker options={years} defaultValue={2025} />
</WheelPickerWrapper>
```

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

### WheelPickerOption Usage Example

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/types.md

Demonstrates how to define an array of WheelPickerOption objects, including string values, ReactNode labels, and disabled options.

```tsx
const options: WheelPickerOption<string>[] = [
  {
    value: "opt1",
    label: "Option 1",
    textValue: "option one", // For search
  },
  {
    value: "opt2",
    label: <span style={{ color: "red" }}>Option 2 (Highlighted)</span>,
    textValue: "option two",
  },
  {
    value: "opt3",
    label: "Option 3 (Disabled)",
    disabled: true,
  },
];
```

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

### Complete Custom Styling Example

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/configuration.md

Apply custom themes to the wheel picker by importing a custom CSS file and using the `classNames` prop to map component parts to your theme's styles. This allows for full visual customization.

```tsx
// Component
import { WheelPicker, WheelPickerWrapper } from "@ncdai/react-wheel-picker";
import "@ncdai/react-wheel-picker/style.css";
import "./theme.css";

export function ThemedPicker() {
  return (
    <WheelPickerWrapper className="theme-dark">
      <WheelPicker
        options={options}
        classNames={{
          optionItem: "theme-option",
          highlightWrapper: "theme-highlight",
          highlightItem: "theme-selected",
        }}
      />
    </WheelPickerWrapper>
  );
}
```

```css
/* theme.css */

.theme-dark {
  background: #1a1a1a;
  border-radius: 12px;
  padding: 10px 0;
}

.theme-option {
  color: #888;
  font-size: 14px;
  transition: color 0.2s;
}

.theme-option:hover {
  color: #ccc;
}

.theme-highlight {
  border-top: 1px solid #444;
  border-bottom: 1px solid #444;
  background: rgba(0, 122, 255, 0.1);
}

.theme-selected {
  color: #fff;
  font-weight: 600;
  font-size: 16px;
}

.theme-dark [data-rwp-option][data-disabled],
.theme-dark [data-rwp-highlight-item][data-disabled] {
  color: #333;
  opacity: 0.3;
}
```

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

### Basic Multi-Picker Group Setup

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/api-reference/wheel-picker-group-provider.md

Demonstrates how to group two WheelPicker components (hours and minutes) within a WheelPickerWrapper to create a time picker. The WheelPickerWrapper internally uses WheelPickerGroupProvider, enabling navigation between pickers using ArrowLeft/ArrowRight keys.

```tsx
import { WheelPicker, WheelPickerWrapper } from "@ncdai/react-wheel-picker";

export function TimePickerGroup() {
  const hours = Array.from({ length: 24 }, (_, i) => ({
    label: String(i).padStart(2, "0"),
    value: i,
  }));

  const minutes = Array.from({ length: 60 }, (_, i) => ({
    label: String(i).padStart(2, "0"),
    value: i,
  }));

  return (
    <WheelPickerWrapper>
      <WheelPicker options={hours} defaultValue={12} />
      <WheelPicker options={minutes} defaultValue={0} />
    </WheelPickerWrapper>
  );
}
```

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

### Uncontrolled Usage Example

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/api-reference/use-controllable-state.md

Demonstrates how to use `useControllableState` in an uncontrolled manner, where the component manages its own state initialized by `defaultProp`.

```APIDOC
### Example: Uncontrolled Usage

```tsx
import { useControllableState } from "@ncdai/react-wheel-picker";

export function MyComponent() {
  const [value, setValue] = useControllableState({
    defaultProp: "initial",
    onChange: (newValue) => console.log("Changed to:", newValue),
  });

  return (
    <div>
      <p>Value: {value}</p>
      <button onClick={() => setValue("new value")}>Update</button>
    </div>
  );
}
```
```

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

### Custom CSS for Wheel Picker Elements

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/types.md

Provides example CSS rules to style the wheel picker components when custom class names are applied.

```css
.wheel-option {
  padding: 5px;
  font-size: 14px;
}

.wheel-month {
  color: #333;
  font-weight: 500;
}

.highlight-wrapper {
  background: linear-gradient(
    to bottom,
    transparent,
    rgba(0, 0, 0, 0.1),
    transparent
  );
  border-top: 1px solid #ddd;
  border-bottom: 1px solid #ddd;
}

.highlight-item {
  color: #000;
  font-weight: bold;
}
```

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

### Uncontrolled Wheel Picker Example

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/README.md

Use the uncontrolled mode for simple cases. Provide a `defaultValue` and handle changes with `onValueChange`.

```tsx
<WheelPicker
  options={options}
  defaultValue="initial"
  onValueChange={(val) => console.log(val)}
/>
```

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

### Dynamic onChange Handler Example

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/api-reference/use-controllable-state.md

Demonstrates how `useControllableState` handles dynamic `onChange` handlers, ensuring the latest callback is always used due to internal `useCallbackRef`.

```APIDOC
### Example: Dynamic onChange Handler

```tsx
const [value, setValue] = useControllableState({
  prop: externalValue,
  onChange: (newValue) => {
    console.log("Changed to:", newValue);
    analytics.track("value_changed", { value: newValue });
  },
});

// Even if onChange function is recreated on every render,
// the hook correctly uses the latest version internally
```

The `useCallbackRef` wrapper ensures you can safely pass new function references without breaking the hook.
```

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

### Programmatically Focus Next Picker

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/api-reference/use-wheel-picker-group.md

Demonstrates how to programmatically focus the next picker in a group when a button is clicked. This involves getting picker indices, calculating the next picker's position, and using its ref to focus.

```tsx
import { WheelPicker, WheelPickerWrapper } from "@ncdai/react-wheel-picker";
import { useWheelPickerGroup } from "@ncdai/react-wheel-picker";
import { useRef, useCallback } from "react";

function FocusNextPickerButton() {
  const group = useWheelPickerGroup();

  const handleClick = useCallback(() => {
    if (!group) return;

    const indices = group.getPickerIndices();
    const currentPos = indices.indexOf(group.activeIndex);
    const nextPos = (currentPos + 1) % indices.length;
    const nextIndex = indices[nextPos];

    const nextRef = group.getPickerRef(nextIndex);
    if (nextRef) {
      group.setActiveIndex(nextIndex);
      nextRef.focus();
    }
  }, [group]);

  return (
    <button onClick={handleClick}>
      Focus Next Picker
    </button>
  );
}

export function PickerWithButton() {
  const options1 = [
    { label: "A", value: "a" },
    { label: "B", value: "b" },
  ];

  const options2 = [
    { label: "X", value: "x" },
    { label: "Y", value: "y" },
  ];

  return (
    <WheelPickerWrapper>
      <WheelPicker options={options1} defaultValue="a" />
      <WheelPicker options={options2} defaultValue="x" />
      <FocusNextPickerButton />
    </WheelPickerWrapper>
  );
}
```

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

### Uncontrolled Usage Example

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/api-reference/use-controllable-state.md

Demonstrates how to use useControllableState in uncontrolled mode. The initial state is set using `defaultProp`, and changes are logged via the `onChange` callback.

```tsx
import { useControllableState } from "@ncdai/react-wheel-picker";

export function MyComponent() {
  const [value, setValue] = useControllableState({
    defaultProp: "initial",
    onChange: (newValue) => console.log("Changed to:", newValue),
  });

  return (
    <div>
      <p>Value: {value}</p>
      <button onClick={() => setValue("new value")}>Update</button>
    </div>
  );
}
```

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

### Controlled Usage Example

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/api-reference/use-controllable-state.md

Illustrates how to use `useControllableState` in a controlled manner, where the state is managed by a parent component via the `prop` and `onChange` parameters.

```APIDOC
### Example: Controlled Usage

```tsx
import { useState } from "react";
import { useControllableState } from "@ncdai/react-wheel-picker";

export function ParentComponent() {
  const [selected, setSelected] = useState("default");

  return (
    <ControlledChild
      value={selected}
      onChange={setSelected}
    />
  );
}

function ControlledChild({ value, onChange }) {
  const [current, setCurrent] = useControllableState({
    prop: value,
    onChange,
  });

  return (
    <div>
      <p>Current: {current}</p>
      <button onClick={() => setCurrent("clicked")}>Click Me</button>
    </div>
  );
}
```

When button is clicked, `setValue` calls `onChange` with "clicked". Parent's `setSelected` updates `value` prop, which re-renders child with new prop value.
```

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

### Customize highlightItem CSS

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/configuration.md

Style the items that are currently within the highlight zone. This example makes the text black, bold, and slightly larger.

```tsx
<WheelPicker
  options={items}
  classNames={{
    highlightItem: "my-highlight-item"
  }}
/>
```

```css
.my-highlight-item {
  color: #000;
  font-weight: bold;
  font-size: 16px;
}
```

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

### Custom Styling Theme for Wheel Picker

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/README.md

Apply custom styles to the Wheel Picker and its wrapper using CSS classes. This example demonstrates theming for a dark appearance.

```tsx
// Component
<WheelPickerWrapper className="dark-theme">
  <WheelPicker
    options={options}
    classNames={{
      optionItem: "dark-option",
      highlightWrapper: "dark-highlight",
      highlightItem: "dark-selected",
    }}
  />
</WheelPickerWrapper>

// CSS
.dark-theme {
  background: #1a1a1a;
  border-radius: 8px;
}

.dark-option {
  color: #888;
  font-size: 14px;
}

.dark-highlight {
  border-top: 1px solid #444;
  border-bottom: 1px solid #444;
  background: rgba(0, 122, 255, 0.1);
}

.dark-selected {
  color: #fff;
  font-weight: bold;
  font-size: 16px;
}
```

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

### Controlled Wheel Picker Example

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/README.md

Use the controlled mode for complex state management. Manage the `value` state externally and update it via `onValueChange`.

```tsx
const [value, setValue] = useState("initial");
<WheelPicker
  options={options}
  value={value}
  onValueChange={setValue}
/>
```

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

### Functional Updates Example

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/api-reference/use-controllable-state.md

Shows how to use functional updates with the `setValue` function returned by `useControllableState`, similar to React's standard `setState`.

```tsx
const [count, setCount] = useControllableState({
  defaultProp: 0,
  onChange: (val) => console.log("Count:", val),
});

// Direct value update
setCount(5);

// Functional update (updater function)
setCount((prev) => (prev || 0) + 1);
```

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

### CSS Styling for WheelPickerWrapper

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/api-reference/wheel-picker-wrapper.md

Provides example CSS selectors to target the wrapper element and its child components for custom styling. This includes base styles for the wrapper, lists, and individual pickers.

```css
/* Target the wrapper directly */
[data-rwp-wrapper] {
  gap: 20px; /* Space between multiple pickers */
  padding: 10px;
  background: #f5f5f5;
}

/* Target all lists inside wrapper */
[data-rwp-wrapper] ul {
  margin: 0;
  padding: 0;
  list-style: none;
}

/* Target individual pickers */
[data-rwp-wrapper] [data-rwp] {
  border: 1px solid #ddd;
  border-radius: 8px;
}
```

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

### Get Picker DOM Reference from WheelPickerGroupProvider

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/api-reference/wheel-picker-group-provider.md

Illustrates how to retrieve the DOM element of a specific picker using its index. This is useful for programmatically focusing a picker, for example, during keyboard navigation.

```typescript
const ref = group.getPickerRef(0);
if (ref) ref.focus();
```

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

### Navigate to Project Directory

Source: https://github.com/ncdai/react-wheel-picker/blob/main/CONTRIBUTING.md

Change your current directory to the cloned project folder.

```bash
cd react-wheel-picker
```

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

### Initialize shadcn MCP Server

Source: https://github.com/ncdai/react-wheel-picker/blob/main/apps/web/src/content/docs/getting-started.mdx

Configure the shadcn MCP server to enable AI assistants to understand your component registry. This step is optional.

```bash
npx shadcn mcp init
```

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

### Basic shadcn/ui Wheel Picker Usage

Source: https://github.com/ncdai/react-wheel-picker/blob/main/apps/web/src/content/docs/getting-started.mdx

Demonstrates how to set up and render a basic Wheel Picker component with shadcn/ui.

```tsx
const options: WheelPickerOption[] = [
  {
    label: "Next.js",
    value: "nextjs",
  },
  {
    label: "Vite",
    value: "vite",
  },
  // ...
];

export function WheelPickerDemo() {
  const [value, setValue] = useState("nextjs");

  return (
    <WheelPickerWrapper>
      <WheelPicker options={options} value={value} onValueChange={setValue} />
    </WheelPickerWrapper>
  );
}
```

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

### Clone the Repository

Source: https://github.com/ncdai/react-wheel-picker/blob/main/CONTRIBUTING.md

Clone the react-wheel-picker repository to your local machine.

```bash
git clone https://github.com/your-username/react-wheel-picker.git
```

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

### Functional Updates Example

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/api-reference/use-controllable-state.md

Shows how `setValue` in `useControllableState` supports functional updates, similar to React's `useState`.

```APIDOC
### Example: Functional Updates

```tsx
const [count, setCount] = useControllableState({
  defaultProp: 0,
  onChange: (val) => console.log("Count:", val),
});

// Direct value update
setCount(5);

// Functional update (updater function)
setCount((prev) => (prev || 0) + 1);
```

Both forms work the same as standard React `setState`.
```

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

### Import Stylesheet

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/MANIFEST.txt

Import the default stylesheet for the wheel picker components.

```javascript
import "@ncdai/react-wheel-picker/style.css";
```

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

### Import Primitives Components

Source: https://github.com/ncdai/react-wheel-picker/blob/main/apps/web/src/content/docs/getting-started.mdx

Import necessary components for using the Wheel Picker as primitives.

```tsx
import {
  WheelPicker,
  WheelPickerWrapper,
  type WheelPickerOption,
} from "@ncdai/react-wheel-picker";
```

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

### Import Main Components

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/MANIFEST.txt

Import the primary WheelPicker and WheelPickerWrapper components from the library.

```javascript
import { WheelPicker, WheelPickerWrapper } from "@ncdai/react-wheel-picker";
```

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

### Import shadcn/ui Components

Source: https://github.com/ncdai/react-wheel-picker/blob/main/apps/web/src/content/docs/getting-started.mdx

Import necessary components for using the Wheel Picker with shadcn/ui.

```tsx
import {
  WheelPicker,
  WheelPickerWrapper,
  type WheelPickerOption,
} from "@/components/wheel-picker";
```

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

### Import Wheel Picker Components and Types

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/INDEX.md

Import the necessary components, types, and CSS for the Wheel Picker.

```typescript
import { WheelPicker, WheelPickerWrapper } from "@ncdai/react-wheel-picker";
import type { WheelPickerOption, WheelPickerProps } from "@ncdai/react-wheel-picker";
import "@ncdai/react-wheel-picker/style.css";
```

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

### Wheel Picker Component Anatomy

Source: https://github.com/ncdai/react-wheel-picker/blob/main/apps/web/src/content/docs/getting-started.mdx

This is a basic example showing the structure of the Wheel Picker component, consisting of a wrapper and multiple individual pickers.

```tsx
<WheelPickerWrapper>
  <WheelPicker />
  <WheelPicker />
  <WheelPicker />
</WheelPickerWrapper>
```

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

### Project File Organization

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/INDEX.md

Overview of the project's directory structure and the purpose of key files.

```text
/output/
├── README.md .......................... Overview and quick start
├── INDEX.md ........................... This file
├── types.md ........................... Type definitions
├── configuration.md ................... Props, styling, accessibility
├── exports.md ......................... Module exports and imports
└── api-reference/
    ├── wheel-picker.md ............... Main component
    ├── wheel-picker-wrapper.md ....... Wrapper component
    ├── wheel-picker-group-provider.md  Context provider
    ├── use-wheel-picker-group.md ..... Group context hook
    ├── use-controllable-state.md ..... State management hook
    └── use-typeahead-search.md ....... Type-ahead search hook
```

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

### Basic Wheel Picker Usage

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/INDEX.md

Demonstrates how to use the WheelPicker component with a simple list of options and a default value. The onValueChange callback logs the selected value.

```tsx
const options = [
  { label: "Option 1", value: "opt1" },
  { label: "Option 2", value: "opt2" },
];

<WheelPicker
  options={options}
  defaultValue="opt1"
  onValueChange={(value) => console.log(value)}
/>
```

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

### UseTypeaheadSearchOptions Type Definition

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/types.md

Defines the configuration options for the useTypeaheadSearch hook. It requires functions to get text value, current index, and handle matches.

```typescript
type UseTypeaheadSearchOptions<T> = {
  getTextValue: (option: T) => string
  getCurrentIndex: () => number
  onMatch: (index: number) => void
}
```

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

### Customize highlightWrapper CSS

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/configuration.md

Style the highlight wrapper, which is the area indicating the selected item. This example applies a gradient background, top/bottom borders, and an inset shadow.

```tsx
<WheelPicker
  options={items}
  classNames={{
    highlightWrapper: "my-highlight-wrapper"
  }}
/>
```

```css
.my-highlight-wrapper {
  background: linear-gradient(
    to bottom,
    transparent 0%,
    rgba(0, 0, 0, 0.05) 50%,
    transparent 100%
  );
  border-top: 2px solid #007AFF;
  border-bottom: 2px solid #007AFF;
  box-shadow: inset 0 0 10px rgba(0, 0, 0, 0.1);
}
```

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

### Styling Wheel Picker Options

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/INDEX.md

Illustrates how to apply custom class names to different parts of the WheelPicker for advanced styling. This allows for granular control over the appearance of options and selection highlights.

```tsx
<WheelPicker
  options={options}
  classNames={{
    optionItem: "my-option",
    highlightWrapper: "my-highlight",
    highlightItem: "my-selected",
  }}
/>
```

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

### Create Pickers with String and Number Options

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/README.md

Demonstrates creating WheelPicker components with string (default) and number options. Use the generic type parameter to specify the value type.

```tsx
// String values (default)
const fruitOptions: WheelPickerOption<string>[] = [
  { label: "Apple", value: "apple" },
  { label: "Banana", value: "banana" },
];

// Number values
const numberOptions: WheelPickerOption<number>[] = [
  { label: "1", value: 1 },
  { label: "2", value: 2 },
];

<WheelPicker<string> options={fruitOptions} />;
<WheelPicker<number> options={numberOptions} />;
```

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

### Tsup Build Configuration

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/exports.md

Configuration for the tsup build tool, specifying entry points, output formats, bundling, and type declaration generation.

```json
{
  "tsup": {
    "entry": ["src/index.tsx"],
    "format": ["esm", "cjs"],
    "bundle": true,
    "clean": true,
    "dts": true,
    "injectStyle": false,
    "outDir": "./dist"
  }
}
```

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

### Controlled Usage Example

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/api-reference/use-controllable-state.md

Illustrates using useControllableState in controlled mode. The `value` prop is managed by the parent component (`ParentComponent`), and changes are propagated back via the `onChange` callback.

```tsx
import { useState } from "react";
import { useControllableState } from "@ncdai/react-wheel-picker";

export function ParentComponent() {
  const [selected, setSelected] = useState("default");

  return (
    <ControlledChild
      value={selected}
      onChange={setSelected}
    />
  );
}

function ControlledChild({ value, onChange }) {
  const [current, setCurrent] = useControllableState({
    prop: value,
    onChange,
  });

  return (
    <div>
      <p>Current: {current}</p>
      <button onClick={() => setCurrent("clicked")}>Click Me</button>
    </div>
  );
}
```

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

### Customize optionItem CSS

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/configuration.md

Apply custom CSS to individual rotating items within the wheel. This example sets the color, font size, padding, and font weight for each option item.

```tsx
<WheelPicker
  options={items}
  classNames={{
    optionItem: "my-option-item"
  }}
/>
```

```css
.my-option-item {
  color: #333;
  font-size: 14px;
  padding: 5px;
  font-weight: 500;
}
```

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

### Basic Type-Ahead Search in a Dropdown

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/api-reference/use-typeahead-search.md

Demonstrates basic type-ahead search with string items in a dropdown-like interface. Handles single and multi-character input, with wrap-around behavior.

```tsx
import { useTypeaheadSearch } from "@ncdai/react-wheel-picker";
import { useState } from "react";

const items = ["Apple", "Apricot", "Avocado", "Banana", "Blueberry"];

export function TypeaheadDropdown() {
  const [selectedIndex, setSelectedIndex] = useState(0);

  const { handleTypeaheadSearch, resetTypeahead } = useTypeaheadSearch(
    items,
    {
      getTextValue: (item) => item,
      getCurrentIndex: () => selectedIndex,
      onMatch: (index) => setSelectedIndex(index),
    }
  );

  return (
    <div
      onKeyDown={(e) => {
        if (e.key.length === 1) {
          e.preventDefault();
          handleTypeaheadSearch(e.key);
        }
      }}
      onBlur={() => resetTypeahead()}
      tabIndex={0}
    >
      <p>Selected: {items[selectedIndex]}</p>
      <p>Type to search...</p>
    </div>
  );
}
```

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

### Get All Registered Picker Indices from WheelPickerGroupProvider

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/api-reference/wheel-picker-group-provider.md

Demonstrates how to obtain a sorted array of all currently registered picker indices. This is essential for implementing keyboard navigation logic, such as determining the previous or next picker.

```typescript
const indices = group.getPickerIndices();
// Returns: [0, 1, 2]
```

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

### Desktop-Friendly Wheel Picker Configuration

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/configuration.md

Displays more items with smaller targets and moderate sensitivity, suitable for desktop interfaces. Use this for desktop applications.

```tsx
<WheelPicker
  options={options}
  visibleCount={12}
  optionItemHeight={28}
  dragSensitivity={4}
  scrollSensitivity={3}
/>
```

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

### Import WheelPickerOption Type

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/exports.md

How to import the WheelPickerOption type for defining individual picker options.

```tsx
import type { WheelPickerOption } from "@ncdai/react-wheel-picker";
```

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

### Dynamic onChange Handler Example

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/api-reference/use-controllable-state.md

Demonstrates how `useControllableState` handles dynamic `onChange` handlers. The hook's internal `useCallbackRef` ensures the latest callback is always used, even if the function reference changes on re-renders.

```tsx
const [value, setValue] = useControllableState({
  prop: externalValue,
  onChange: (newValue) => {
    console.log("Changed to:", newValue);
    analytics.track("value_changed", { value: newValue });
  },
});

// Even if onChange function is recreated on every render,
// the hook correctly uses the latest version internally
```

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

### Fast/Responsive Wheel Picker Configuration

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/configuration.md

Features fewer, larger items with high sensitivity for quick selection. Use this when rapid interaction is prioritized.

```tsx
<WheelPicker
  options={options}
  visibleCount={6}
  optionItemHeight={50}
  dragSensitivity={5}
  scrollSensitivity={8}
/>
```

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

### Create a New Branch

Source: https://github.com/ncdai/react-wheel-picker/blob/main/CONTRIBUTING.md

Create a new branch for your feature or bug fix.

```bash
git checkout -b my-new-branch
```

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

### Public Type Re-exports

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/exports.md

Demonstrates how public types and components are re-exported from the main entry point, ensuring a consistent import path for consumers.

```typescript
export {
  WheelPicker,
  type WheelPickerOption,
  type WheelPickerProps,
  type WheelPickerValue,
  WheelPickerWrapper,
};

export { type WheelPickerClassNames } from "./types";
```

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

### Package Export Conditions

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/exports.md

Configuration in package.json defining conditional entry points for different module systems (ES Modules, CommonJS) and CSS imports.

```json
{
  "exports": {
    ".": {
      "import": {
        "types": "./dist/index.d.mts",
        "default": "./dist/index.mjs"
      },
      "require": {
        "types": "./dist/index.d.ts",
        "default": "./dist/index.js"
      },
      "default": "./dist/index.js"
    },
    "./style.css": "./dist/index.css"
  }
}
```

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

### Basic Uncontrolled Wheel Picker Usage

Source: https://github.com/ncdai/react-wheel-picker/blob/main/_autodocs/api-reference/wheel-picker.md

Demonstrates how to use the WheelPicker component with initial options and a default value. The component manages its own state.

```tsx
import { WheelPicker } from "@ncdai/react-wheel-picker";

export function MyPicker() {
  const options = [
    { label: "Option 1", value: "opt1" },
    { label: "Option 2", value: "opt2" },
    { label: "Option 3", value: "opt3" },
  ];

  return (
    <WheelPicker
      options={options}
      defaultValue="opt1"
      onValueChange={(value) => console.log("Selected:", value)}
    />
  );
}
```