@particle-academy/react-fancy 1.7.0 → 1.7.2

package/README.md

@@ -56,109 +56,103 @@ npx vite build                      # Build demo app (verifies imports work)
 
 ### Core
 
-| Component | Description |
-|-----------|-------------|
-| Action | Button with colors, states, icons, emoji, avatar, badge, sort control |
-| Carousel | Slide carousel with directional/wizard variants, autoplay, loop |
-| ColorPicker | Native color input with swatch preview, hex display, presets |
-| Emoji | Emoji renderer from slugs |
-| EmojiSelect | Emoji search and selection dropdown |
-| Table | Data table with sorting, pagination, search, and tray |
+| Component | Description | Docs |
+|-----------|-------------|------|
+| Action | Button with colors, states, icons, emoji, avatar, badge, sort control | [docs](docs/Action.md) |
+| Carousel | Slide carousel with directional/wizard variants, autoplay, loop | [docs](docs/Carousel.md) |
+| ColorPicker | Native color input with swatch preview, hex display, presets | [docs](docs/ColorPicker.md) |
+| Emoji | Emoji renderer from slugs | [docs](docs/Emoji.md) |
+| EmojiSelect | Emoji search and selection dropdown | [docs](docs/EmojiSelect.md) |
+| Table | Data table with sorting, pagination, search, and tray | [docs](docs/Table.md) |
 
 ### Form Inputs
 
-| Component | Description |
-|-----------|-------------|
-| Field | Form field wrapper with label and error display |
-| Input | Text input |
-| Textarea | Multi-line text input |
-| Select | Dropdown select |
-| Checkbox / CheckboxGroup | Checkbox inputs |
-| RadioGroup | Radio button group |
-| Switch | Toggle switch |
-| Slider | Range slider (single and range modes) |
-| MultiSwitch | Segmented toggle between multiple options |
-| DatePicker | Date selection (single and range modes) |
-| Autocomplete | Input with filtered dropdown suggestions, async search, keyboard nav |
-| Pillbox | Tag/pill input with add/remove, backspace delete |
-| OtpInput | Single-digit OTP code input with auto-advance and paste support |
-| FileUpload | Drag-and-drop file upload with dropzone and file list |
-| TimePicker | Hour/minute/AM-PM time selection |
-| Calendar | Month grid with single, range, and multi-select modes |
+| Component | Description | Docs |
+|-----------|-------------|------|
+| Field | Form field wrapper with label and error display | [docs](docs/Field.md) |
+| Input | Text input | [docs](docs/Input.md) |
+| Textarea | Multi-line text input | [docs](docs/Textarea.md) |
+| Select | Native and listbox dropdown with multi-select support | [docs](docs/Select.md) |
+| Checkbox / CheckboxGroup | Checkbox inputs | [docs](docs/Checkbox.md) |
+| RadioGroup | Radio button group | [docs](docs/RadioGroup.md) |
+| Switch | Toggle switch | [docs](docs/Switch.md) |
+| Slider | Range slider (single and range modes) | [docs](docs/Slider.md) |
+| MultiSwitch | Segmented toggle between multiple options | [docs](docs/MultiSwitch.md) |
+| DatePicker | Date selection (single and range modes) | [docs](docs/DatePicker.md) |
+| Autocomplete | Input with filtered dropdown suggestions, async search, keyboard nav | [docs](docs/Autocomplete.md) |
+| Pillbox | Tag/pill input with add/remove, backspace delete | [docs](docs/Pillbox.md) |
+| OtpInput | Single-digit OTP code input with auto-advance and paste support | [docs](docs/OtpInput.md) |
+| FileUpload | Drag-and-drop file upload with dropzone and file list | [docs](docs/FileUpload.md) |
+| TimePicker | Hour/minute/AM-PM time selection | [docs](docs/TimePicker.md) |
+| Calendar | Month grid with single, range, and multi-select modes | [docs](docs/Calendar.md) |
 
 ### Display
 
-| Component | Description |
-|-----------|-------------|
-| Heading | Semantic heading (`h1`–`h6`) with size and weight props |
-| Text | Paragraph/span with size, color, weight, and `as` prop |
-| Separator | Horizontal/vertical divider with optional label |
-| Badge | Inline label with color, variant, size, and dot indicator |
-| Icon | Size wrapper around icon ReactNode |
-| Avatar | Image with fallback initials, size variants, status indicator |
-| Skeleton | Animated placeholder (rect, circle, text), pulse animation |
-| Progress | Bar and circular variants, indeterminate mode |
-| Brand | Logo + text lockup |
-| Profile | Avatar + name + subtitle layout |
-| Card | Container with Header, Body, Footer compound slots |
-| Callout | Alert/info box with icon, color, and dismissible support |
-| Timeline | Stacked, alternating, and horizontal timeline with data-driven or compound API |
+| Component | Description | Docs |
+|-----------|-------------|------|
+| Heading | Semantic heading (`h1`–`h6`) with size and weight props | [docs](docs/Heading.md) |
+| Text | Paragraph/span with size, color, weight, and `as` prop | [docs](docs/Text.md) |
+| Separator | Horizontal/vertical divider with optional label | [docs](docs/Separator.md) |
+| Badge | Inline label with color, variant, size, and dot indicator | [docs](docs/Badge.md) |
+| Icon | Size wrapper around icon ReactNode | [docs](docs/Icon.md) |
+| Avatar | Image with fallback initials, size variants, status indicator | [docs](docs/Avatar.md) |
+| Skeleton | Animated placeholder (rect, circle, text), pulse animation | [docs](docs/Skeleton.md) |
+| Progress | Bar and circular variants, indeterminate mode | [docs](docs/Progress.md) |
+| Brand | Logo + text lockup | [docs](docs/Brand.md) |
+| Profile | Avatar + name + subtitle layout | [docs](docs/Profile.md) |
+| Card | Container with Header, Body, Footer compound slots | [docs](docs/Card.md) |
+| Callout | Alert/info box with icon, color, and dismissible support | [docs](docs/Callout.md) |
+| Timeline | Stacked, alternating, and horizontal timeline with data-driven or compound API | [docs](docs/Timeline.md) |
 
 ### Overlay & Floating
 
-| Component | Description |
-|-----------|-------------|
-| Tooltip | Hover/focus tooltip with arrow and placement control |
-| Popover | Click-triggered floating panel |
-| Dropdown | Popover with keyboard-navigable menu items |
-| ContextMenu | Right-click triggered dropdown |
-| Modal | Full-screen backdrop dialog with focus trap and scroll lock |
-| Toast | Notification stack with auto-dismiss, variants, and position options |
-| Command | `Cmd+K` command palette with search and keyboard navigation |
+| Component | Description | Docs |
+|-----------|-------------|------|
+| Tooltip | Hover/focus tooltip with arrow and placement control | [docs](docs/Tooltip.md) |
+| Popover | Click or hover floating panel | [docs](docs/Popover.md) |
+| Dropdown | Popover with keyboard-navigable menu items | [docs](docs/Dropdown.md) |
+| ContextMenu | Right-click triggered dropdown | [docs](docs/ContextMenu.md) |
+| Modal | Full-screen backdrop dialog with focus trap and scroll lock | [docs](docs/Modal.md) |
+| Toast | Notification stack with auto-dismiss, variants, and position options | [docs](docs/Toast.md) |
+| Command | `Cmd+K` command palette with search and keyboard navigation | [docs](docs/Command.md) |
 
 ### Navigation & Layout
 
-| Component | Description |
-|-----------|-------------|
-| Tabs | Tabbed content with underline, pills, and boxed variants |
-| Accordion | Collapsible content sections (single/multiple mode) |
-| Breadcrumbs | Navigation breadcrumb trail with separator |
-| Navbar | Responsive navigation bar with hamburger collapse |
-| Pagination | Page navigation with prev/next and ellipsis |
+| Component | Description | Docs |
+|-----------|-------------|------|
+| Tabs | Tabbed content with underline, pills, and boxed variants | [docs](docs/Tabs.md) |
+| Accordion | Collapsible content sections (single/multiple mode) | [docs](docs/Accordion.md) |
+| Breadcrumbs | Navigation breadcrumb trail with separator | [docs](docs/Breadcrumbs.md) |
+| Navbar | Responsive navigation bar with hamburger collapse | [docs](docs/Navbar.md) |
+| Pagination | Page navigation with prev/next and ellipsis | [docs](docs/Pagination.md) |
 
 ### Rich Content
 
-| Component | Description |
-|-----------|-------------|
-| Composer | Chat-style message input composing textarea + actions |
-| Chart | SVG-based Bar and Donut charts |
-| Editor | Toolbar chrome wrapper for contentEditable |
-| Kanban | Drag-and-drop board with columns and cards |
-| Canvas | Interactive node canvas with pan, zoom, and connections |
-| Diagram | Entity-relationship diagram with draggable nodes and relation lines |
-| ContentRenderer | Markdown/HTML content renderer |
+| Component | Description | Docs |
+|-----------|-------------|------|
+| Composer | Chat-style message input composing textarea + actions | [docs](docs/Composer.md) |
+| Chart | SVG-based Bar, Line, Area, Pie, Donut, and Sparkline charts | [docs](docs/Chart.md) |
+| Editor | Toolbar chrome wrapper for contentEditable | [docs](docs/Editor.md) |
+| Kanban | Drag-and-drop board with columns and cards | [docs](docs/Kanban.md) |
+| Canvas | Interactive node canvas with pan, zoom, and connections | [docs](docs/Canvas.md) |
+| Diagram | Entity-relationship diagram with draggable nodes and relation lines | [docs](docs/Diagram.md) |
+| ContentRenderer | Markdown/HTML content renderer | [docs](docs/ContentRenderer.md) |
 
 ### Menus & Navigation
 
-| Component | Description |
-|-----------|-------------|
-| Menu | Hierarchical menu with nested items |
-| Sidebar | Collapsible sidebar navigation |
-| MobileMenu | Responsive mobile navigation overlay |
+| Component | Description | Docs |
+|-----------|-------------|------|
+| Menu | Hierarchical menu with nested items | [docs](docs/Menu.md) |
+| Sidebar | Collapsible sidebar navigation | [docs](docs/Sidebar.md) |
+| MobileMenu | Responsive mobile navigation overlay | [docs](docs/MobileMenu.md) |
 
 ### Utilities & Hooks
 
-| Export | Description |
-|--------|-------------|
-| Portal | `createPortal` wrapper with automatic dark mode propagation |
-| `cn()` | `clsx` + `tailwind-merge` for conditional class composition |
-| `useControllableState` | Controlled/uncontrolled state management |
-| `useFloatingPosition` | Anchor-relative positioning for floating elements |
-| `useOutsideClick` | Close on click outside handler |
-| `useEscapeKey` | Close on Escape key handler |
-| `useFocusTrap` | Tab-cycle focus within container |
-| `useAnimation` | Enter/exit CSS transitions with unmount |
-| `useId` | Stable ID generation |
+| Export | Description | Docs |
+|--------|-------------|------|
+| Portal | `createPortal` wrapper with automatic dark mode propagation | [docs](docs/Portal.md) |
+| `cn()` | `clsx` + `tailwind-merge` for conditional class composition | [docs](docs/utilities.md) |
+| Hooks | useControllableState, useFloatingPosition, useOutsideClick, useEscapeKey, useFocusTrap, useAnimation, useId, usePanZoom | [docs](docs/hooks.md) |
 
 ## Customization
 

package/docs/Accordion.md

@@ -0,0 +1,78 @@
+# Accordion
+
+A collapsible content panel supporting single or multiple open items simultaneously.
+
+## Import
+
+```tsx
+import { Accordion } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Accordion>
+  <Accordion.Item value="item-1">
+    <Accordion.Trigger>What is React Fancy?</Accordion.Trigger>
+    <Accordion.Content>
+      A headless-ish UI component library for React.
+    </Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="item-2">
+    <Accordion.Trigger>Is it accessible?</Accordion.Trigger>
+    <Accordion.Content>
+      Yes, it follows WAI-ARIA patterns.
+    </Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```
+
+## Props
+
+### Accordion (root)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| type | `"single" \| "multiple"` | `"single"` | Whether one or multiple items can be open |
+| defaultOpen | `string[]` | `[]` | Values of items that start open |
+| className | `string` | - | Additional CSS classes |
+
+### Accordion.Item
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | `string` | - | Unique item identifier (required) |
+| className | `string` | - | Additional CSS classes |
+
+### Accordion.Trigger
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Clickable header content |
+| className | `string` | - | Additional CSS classes |
+
+### Accordion.Content
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Collapsible content |
+| className | `string` | - | Additional CSS classes |
+
+## Multiple Open Items
+
+```tsx
+<Accordion type="multiple" defaultOpen={["faq-1", "faq-3"]}>
+  <Accordion.Item value="faq-1">
+    <Accordion.Trigger>First question</Accordion.Trigger>
+    <Accordion.Content>First answer</Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="faq-2">
+    <Accordion.Trigger>Second question</Accordion.Trigger>
+    <Accordion.Content>Second answer</Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="faq-3">
+    <Accordion.Trigger>Third question</Accordion.Trigger>
+    <Accordion.Content>Third answer</Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```

package/docs/Action.md

@@ -0,0 +1,76 @@
+# Action
+
+A versatile button component with support for icons, emojis, avatars, badges, loading states, and color variants.
+
+## Import
+
+```tsx
+import { Action } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Action>Click me</Action>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| variant | `"default" \| "circle"` | `"default"` | Shape variant |
+| color | `ActionColor` | - | Standalone color (overrides state colors). One of: `"blue"`, `"emerald"`, `"amber"`, `"red"`, `"violet"`, `"indigo"`, `"sky"`, `"rose"`, `"orange"`, `"zinc"` |
+| size | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Button size |
+| active | `boolean` | - | Active state (blue highlight) |
+| checked | `boolean` | - | Checked state (emerald highlight) |
+| warn | `boolean` | - | Warning state (amber highlight) |
+| alert | `boolean` | - | Pulsing animation on the entire button |
+| icon | `string` | - | Leading icon slug resolved via the Icon component |
+| iconTrailing | `string` | - | Trailing icon slug |
+| iconPlace | `string` | `"left"` | Icon placement. Supports: `"left"`, `"right"`, `"top"`, `"bottom"`, and compound positions like `"top left"`, `"bottom right"` |
+| alertIcon | `string` | - | Pulsing alert icon slug |
+| alertIconTrailing | `boolean` | - | Position alert icon on trailing side |
+| emoji | `string` | - | Leading emoji slug |
+| emojiTrailing | `string` | - | Trailing emoji slug |
+| avatar | `string` | - | Avatar image URL |
+| avatarTrailing | `boolean` | - | Position avatar on trailing side |
+| badge | `string` | - | Badge text |
+| badgeTrailing | `boolean` | - | Position badge on trailing side |
+| sort | `string` | `"eiab"` | Sort order of decorative elements: `e`=emoji, `i`=icon, `a`=avatar, `b`=badge |
+| loading | `boolean` | `false` | Show loading spinner (disables the button) |
+| disabled | `boolean` | - | Disable the button |
+| href | `string` | - | Render as an anchor tag instead of a button |
+
+Also extends all native `<button>` HTML attributes (except `color`).
+
+## Examples
+
+### Icon button with color
+
+```tsx
+<Action icon="pencil" color="blue" size="lg">
+  Edit
+</Action>
+```
+
+### Circle icon button
+
+```tsx
+<Action variant="circle" icon="plus" color="emerald" />
+```
+
+### Loading state with badge
+
+```tsx
+<Action loading badge="3" badgeTrailing>
+  Messages
+</Action>
+```
+
+### Link button with trailing icon
+
+```tsx
+<Action href="/docs" iconTrailing="arrow-right">
+  Read docs
+</Action>
+```

package/docs/Autocomplete.md

@@ -0,0 +1,74 @@
+# Autocomplete
+
+Text input with a filterable dropdown of suggestions, supporting async search and keyboard navigation.
+
+## Import
+
+```tsx
+import { Autocomplete } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Autocomplete
+  options={[
+    { value: "react", label: "React" },
+    { value: "vue", label: "Vue" },
+    { value: "angular", label: "Angular" },
+  ]}
+  placeholder="Search frameworks..."
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `options` | `AutocompleteOption[]` | **required** | `{ value: string; label: string; disabled?: boolean }` |
+| `value` | `string` | - | Controlled selected value |
+| `defaultValue` | `string` | `""` | Default value (uncontrolled) |
+| `onChange` | `(value: string) => void` | - | Callback when an option is selected |
+| `onSearch` | `(query: string) => void` | - | Callback fired as the user types (for async fetching) |
+| `placeholder` | `string` | - | Input placeholder |
+| `loading` | `boolean` | `false` | Show a loading indicator in the dropdown |
+| `emptyMessage` | `ReactNode` | `"No results found."` | Message when no options match |
+| `disabled` | `boolean` | `false` | Disables the input |
+| `className` | `string` | - | Additional CSS classes |
+
+Matching text in dropdown options is automatically highlighted in bold.
+
+## Examples
+
+### Async search
+
+```tsx
+const [options, setOptions] = useState([]);
+const [loading, setLoading] = useState(false);
+
+<Autocomplete
+  options={options}
+  loading={loading}
+  placeholder="Search users..."
+  onSearch={async (query) => {
+    setLoading(true);
+    const results = await fetchUsers(query);
+    setOptions(results.map((u) => ({ value: u.id, label: u.name })));
+    setLoading(false);
+  }}
+  onChange={(userId) => console.log("Selected:", userId)}
+/>
+```
+
+### Controlled
+
+```tsx
+const [city, setCity] = useState("");
+
+<Autocomplete
+  options={cities}
+  value={city}
+  onChange={setCity}
+  placeholder="Pick a city"
+/>
+```

package/docs/Avatar.md

@@ -0,0 +1,40 @@
+# Avatar
+
+A circular avatar component with image, fallback initials, and optional online status indicator.
+
+## Import
+
+```tsx
+import { Avatar } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Avatar src="/photo.jpg" alt="Jane Doe" />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| src | `string` | - | Image source URL |
+| alt | `string` | `""` | Alt text for the image |
+| fallback | `string` | - | Fallback initials when no image is provided |
+| size | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Avatar size |
+| status | `"online" \| "offline" \| "busy" \| "away"` | - | Online status indicator dot |
+| className | `string` | - | Additional CSS classes |
+
+## Examples
+
+### With fallback initials and status
+
+```tsx
+<Avatar fallback="JD" size="lg" status="online" />
+```
+
+### Small avatar with image
+
+```tsx
+<Avatar src="/avatar.png" alt="User" size="sm" status="busy" />
+```

package/docs/Badge.md

@@ -0,0 +1,42 @@
+# Badge
+
+An inline badge/tag component with color, variant, and optional dot indicator.
+
+## Import
+
+```tsx
+import { Badge } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Badge>Default</Badge>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| color | `"zinc" \| "red" \| "blue" \| "green" \| "amber" \| "violet" \| "rose"` | `"zinc"` | Badge color |
+| variant | `"solid" \| "outline" \| "soft"` | `"soft"` | Visual variant |
+| size | `"sm" \| "md" \| "lg"` | `"md"` | Badge size |
+| dot | `boolean` | `false` | Show a small dot indicator before text |
+
+Also extends all native `<span>` HTML attributes.
+
+## Examples
+
+### Status badge with dot
+
+```tsx
+<Badge color="green" dot>Active</Badge>
+```
+
+### Solid colored badge
+
+```tsx
+<Badge color="red" variant="solid" size="sm">
+  3 errors
+</Badge>
+```

package/docs/Brand.md

@@ -0,0 +1,44 @@
+# Brand
+
+A branding component that displays a logo, name, and tagline side by side.
+
+## Import
+
+```tsx
+import { Brand } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Brand name="Acme Inc." />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| logo | `ReactNode` | - | Logo element (image, icon, SVG, etc.) |
+| name | `string` | - | Brand name text |
+| tagline | `string` | - | Tagline or subtitle text |
+| size | `"sm" \| "md" \| "lg"` | `"md"` | Overall size |
+| className | `string` | - | Additional CSS classes |
+
+## Examples
+
+### Full brand with logo
+
+```tsx
+<Brand
+  logo={<img src="/logo.svg" alt="" className="h-8 w-8" />}
+  name="Acme Inc."
+  tagline="Build amazing things"
+  size="lg"
+/>
+```
+
+### Name only
+
+```tsx
+<Brand name="My App" size="sm" />
+```

package/docs/Breadcrumbs.md

@@ -0,0 +1,51 @@
+# Breadcrumbs
+
+A navigation trail with configurable separators, a shrinkable mode that collapses intermediate items to "...", and an automatic mobile dropdown.
+
+## Import
+
+```tsx
+import { Breadcrumbs } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Breadcrumbs>
+  <Breadcrumbs.Item href="/">Home</Breadcrumbs.Item>
+  <Breadcrumbs.Item href="/products">Products</Breadcrumbs.Item>
+  <Breadcrumbs.Item active>Widget</Breadcrumbs.Item>
+</Breadcrumbs>
+```
+
+## Props
+
+### Breadcrumbs (root)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| separator | `ReactNode` | `<ChevronRight />` | Custom separator element between items |
+| shrink | `boolean` | - | Collapse intermediate items to "..." (expand on hover/click) |
+| className | `string` | - | Additional CSS classes |
+
+### Breadcrumbs.Item
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Item label |
+| href | `string` | - | Link URL (renders an anchor when provided) |
+| active | `boolean` | - | Mark as the current page (no link) |
+| className | `string` | - | Additional CSS classes |
+
+## Shrinkable Breadcrumbs
+
+When `shrink` is enabled, only the "..." button and the last item are shown. Hovering or clicking "..." expands the full trail.
+
+```tsx
+<Breadcrumbs shrink>
+  <Breadcrumbs.Item href="/">Home</Breadcrumbs.Item>
+  <Breadcrumbs.Item href="/docs">Docs</Breadcrumbs.Item>
+  <Breadcrumbs.Item href="/docs/components">Components</Breadcrumbs.Item>
+  <Breadcrumbs.Item active>Breadcrumbs</Breadcrumbs.Item>
+</Breadcrumbs>
+```

package/docs/Calendar.md

@@ -0,0 +1,72 @@
+# Calendar
+
+Inline calendar widget supporting single date, multiple date, and date range selection.
+
+## Import
+
+```tsx
+import { Calendar } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Calendar onChange={(date) => console.log(date)} />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `mode` | `"single" \| "range" \| "multiple"` | `"single"` | Selection mode |
+| `value` | `Date \| Date[] \| DateRange \| null` | - | Controlled value (type depends on mode) |
+| `onChange` | `(value: Date \| Date[] \| DateRange \| null) => void` | - | Callback when selection changes |
+| `minDate` | `Date` | - | Earliest selectable date |
+| `maxDate` | `Date` | - | Latest selectable date |
+| `disabledDates` | `Date[]` | `[]` | Specific dates to disable |
+| `className` | `string` | - | Additional CSS classes |
+
+### DateRange type
+
+```ts
+interface DateRange {
+  start: Date | null;
+  end: Date | null;
+}
+```
+
+**Behavior:**
+- Month navigation via chevron buttons.
+- Today is visually emphasized with bold text.
+- In `"range"` mode, hovering previews the range highlight before the second click.
+- Out-of-month days are dimmed but still clickable.
+
+## Examples
+
+### Date range selection
+
+```tsx
+const [range, setRange] = useState<DateRange>({ start: null, end: null });
+
+<Calendar
+  mode="range"
+  value={range}
+  onChange={setRange}
+  minDate={new Date()}
+/>
+```
+
+### Multiple dates with constraints
+
+```tsx
+const [dates, setDates] = useState<Date[]>([]);
+
+<Calendar
+  mode="multiple"
+  value={dates}
+  onChange={setDates}
+  minDate={new Date(2024, 0, 1)}
+  maxDate={new Date(2024, 11, 31)}
+  disabledDates={[new Date(2024, 6, 4)]}
+/>
+```