@particle-academy/react-fancy 1.7.0 → 1.7.2

package/docs/OtpInput.md

@@ -0,0 +1,48 @@
+# OtpInput
+
+One-time password input with individual digit cells, auto-advance, and paste support.
+
+## Import
+
+```tsx
+import { OtpInput } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<OtpInput length={6} onChange={(code) => console.log(code)} />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `length` | `number` | `6` | Number of digit cells |
+| `value` | `string` | - | Controlled value |
+| `onChange` | `(value: string) => void` | - | Callback with the full OTP string |
+| `disabled` | `boolean` | `false` | Disables all inputs |
+| `autoFocus` | `boolean` | `false` | Auto-focus the first cell on mount |
+| `className` | `string` | - | Additional CSS classes on the container |
+
+**Behavior:**
+- Only numeric digits are accepted.
+- Focus advances to the next cell after input.
+- **Backspace** clears the current cell, or moves to the previous cell if already empty.
+- **Arrow keys** move focus between cells.
+- **Paste** fills cells from the clipboard (non-numeric characters are stripped).
+
+## Examples
+
+### 4-digit code with auto-focus
+
+```tsx
+const [code, setCode] = useState("");
+
+<OtpInput
+  length={4}
+  autoFocus
+  value={code}
+  onChange={setCode}
+/>
+```

package/docs/Pagination.md

@@ -0,0 +1,48 @@
+# Pagination
+
+A page navigation component with previous/next buttons, page numbers, and ellipsis for large ranges.
+
+## Import
+
+```tsx
+import { Pagination } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Pagination page={1} totalPages={10} onPageChange={setPage} />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| page | `number` | **required** | Current active page (1-based) |
+| onPageChange | `(page: number) => void` | **required** | Callback when a page is selected |
+| totalPages | `number` | **required** | Total number of pages |
+| siblingCount | `number` | `1` | Number of sibling pages shown around the current page |
+| className | `string` | - | Additional CSS classes |
+
+Renders `null` when `totalPages <= 1`. Automatically inserts ellipsis when the page count exceeds the visible slot count.
+
+## Examples
+
+### Basic pagination
+
+```tsx
+const [page, setPage] = useState(1);
+
+<Pagination page={page} totalPages={20} onPageChange={setPage} />
+```
+
+### More visible siblings
+
+```tsx
+<Pagination
+  page={page}
+  totalPages={50}
+  onPageChange={setPage}
+  siblingCount={2}
+/>
+```

package/docs/Pillbox.md

@@ -0,0 +1,53 @@
+# Pillbox
+
+Tag/pill input that lets users type free-text values and manage them as removable pills.
+
+## Import
+
+```tsx
+import { Pillbox } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Pillbox placeholder="Add tags..." onChange={(tags) => console.log(tags)} />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string[]` | - | Controlled list of items |
+| `defaultValue` | `string[]` | `[]` | Default items (uncontrolled) |
+| `onChange` | `(values: string[]) => void` | - | Callback when items change |
+| `placeholder` | `string` | `"Type and press Enter..."` | Placeholder (shown only when no items exist) |
+| `maxItems` | `number` | - | Maximum number of items allowed |
+| `disabled` | `boolean` | `false` | Disables input and removal |
+| `className` | `string` | - | Additional CSS classes |
+
+**Behavior:**
+- Press **Enter** to add the current text as a pill. Duplicates and empty strings are ignored.
+- Press **Backspace** on an empty input to remove the last pill.
+- Click the **X** on any pill to remove it.
+
+## Examples
+
+### With max items
+
+```tsx
+<Pillbox
+  placeholder="Add up to 5 skills..."
+  maxItems={5}
+  defaultValue={["React", "TypeScript"]}
+  onChange={setSkills}
+/>
+```
+
+### Controlled
+
+```tsx
+const [emails, setEmails] = useState<string[]>([]);
+
+<Pillbox value={emails} onChange={setEmails} placeholder="Add email addresses..." />
+```

package/docs/Popover.md

@@ -0,0 +1,82 @@
+# Popover
+
+A floating content panel anchored to a trigger element. Supports click and hover activation with configurable placement.
+
+## Import
+
+```tsx
+import { Popover } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Popover>
+  <Popover.Trigger>
+    <button>Open popover</button>
+  </Popover.Trigger>
+  <Popover.Content>
+    <p>Popover content here</p>
+  </Popover.Content>
+</Popover>
+```
+
+## Props
+
+### Popover (root)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| open | `boolean` | - | Controlled open state |
+| defaultOpen | `boolean` | `false` | Default open state (uncontrolled) |
+| onOpenChange | `(open: boolean) => void` | - | Callback when open state changes |
+| placement | `Placement` | `"bottom"` | Position relative to trigger. One of: `"top"`, `"bottom"`, `"left"`, `"right"`, `"top-start"`, `"top-end"`, `"bottom-start"`, `"bottom-end"` |
+| offset | `number` | `8` | Pixel offset from the trigger |
+| hover | `boolean` | `false` | Open on hover instead of click |
+| hoverDelay | `number` | `200` | Delay in ms before opening on hover |
+| hoverCloseDelay | `number` | `300` | Delay in ms before closing after hover leaves |
+
+### Popover.Trigger
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Trigger element |
+| className | `string` | - | Additional CSS classes |
+
+### Popover.Content
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Content to display |
+| className | `string` | - | Additional CSS classes |
+
+## Hover Mode
+
+The `hover` prop switches from click-to-toggle to hover-to-open behavior. When enabled, the popover opens after `hoverDelay` ms and closes after `hoverCloseDelay` ms once the cursor leaves both the trigger and content. Moving from the trigger into the content keeps the popover open.
+
+```tsx
+<Popover hover hoverDelay={100} hoverCloseDelay={400}>
+  <Popover.Trigger>
+    <button>Hover me</button>
+  </Popover.Trigger>
+  <Popover.Content>
+    <p>Tooltip-like popover</p>
+  </Popover.Content>
+</Popover>
+```
+
+## Controlled Example
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Popover open={open} onOpenChange={setOpen} placement="right">
+  <Popover.Trigger>
+    <button>Info</button>
+  </Popover.Trigger>
+  <Popover.Content className="p-4 w-64">
+    <h3>Details</h3>
+    <p>Some additional information.</p>
+  </Popover.Content>
+</Popover>
+```

package/docs/Portal.md

@@ -0,0 +1,40 @@
+# Portal
+
+Renders children into a DOM node outside the React component tree using `createPortal`, with automatic dark mode propagation.
+
+## Import
+
+```tsx
+import { Portal } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Portal>
+  <div className="fixed inset-0 z-50 bg-black/50">Modal overlay</div>
+</Portal>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | **required** | Content to render in the portal |
+| container | `HTMLElement` | `document.body` | Target DOM element to portal into |
+
+Portal wraps children in a `<div style="display: contents">` that automatically syncs the `dark` class from `<html>`, ensuring Tailwind `dark:` utilities work correctly inside portals.
+
+Returns `null` during SSR (when `document` is undefined).
+
+## Examples
+
+### Custom container
+
+```tsx
+const container = document.getElementById("modal-root")!;
+
+<Portal container={container}>
+  <div>Rendered inside #modal-root</div>
+</Portal>
+```

package/docs/Profile.md

@@ -0,0 +1,52 @@
+# Profile
+
+A profile display component that combines an Avatar with a name and optional subtitle.
+
+## Import
+
+```tsx
+import { Profile } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Profile name="Jane Doe" />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| src | `string` | - | Avatar image URL |
+| alt | `string` | - | Avatar alt text (falls back to `name`) |
+| fallback | `string` | - | Fallback initials for the avatar |
+| name | `string` | **required** | Display name |
+| subtitle | `string` | - | Secondary text (role, email, etc.) |
+| size | `"sm" \| "md" \| "lg"` | `"md"` | Overall size |
+| status | `"online" \| "offline" \| "busy" \| "away"` | - | Status indicator on the avatar |
+| className | `string` | - | Additional CSS classes |
+
+## Examples
+
+### With avatar and status
+
+```tsx
+<Profile
+  src="/photo.jpg"
+  name="Jane Doe"
+  subtitle="Product Designer"
+  status="online"
+/>
+```
+
+### Fallback initials
+
+```tsx
+<Profile
+  fallback="AB"
+  name="Alice Brown"
+  subtitle="alice@example.com"
+  size="lg"
+/>
+```

package/docs/Progress.md

@@ -0,0 +1,42 @@
+# Progress
+
+A progress indicator available as a horizontal bar or circular ring, with optional percentage display.
+
+## Import
+
+```tsx
+import { Progress } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Progress value={60} />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | `number` | `0` | Current progress value |
+| max | `number` | `100` | Maximum value |
+| variant | `"bar" \| "circular"` | `"bar"` | Visual variant |
+| size | `"sm" \| "md" \| "lg"` | `"md"` | Component size |
+| color | `"blue" \| "green" \| "amber" \| "red" \| "violet" \| "zinc"` | `"blue"` | Progress color |
+| indeterminate | `boolean` | `false` | Show indeterminate/loading animation |
+| showValue | `boolean` | `false` | Display percentage text |
+| className | `string` | - | Additional CSS classes |
+
+## Examples
+
+### Bar with percentage
+
+```tsx
+<Progress value={75} showValue color="green" />
+```
+
+### Circular indeterminate
+
+```tsx
+<Progress variant="circular" indeterminate size="lg" color="violet" />
+```

package/docs/RadioGroup.md

@@ -0,0 +1,69 @@
+# RadioGroup
+
+Radio button group for single-value selection from a list of options.
+
+## Import
+
+```tsx
+import { RadioGroup } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<RadioGroup
+  label="Plan"
+  list={["Free", "Pro", "Enterprise"]}
+  onValueChange={(plan) => console.log(plan)}
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `list` | `InputOption[]` | **required** | Options as strings or `{ value, label, disabled?, description? }` |
+| `value` | `V` | - | Controlled selected value |
+| `defaultValue` | `V` | - | Default selected value (uncontrolled) |
+| `onValueChange` | `(value: V) => void` | - | Callback when selection changes |
+| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` | Layout direction |
+| `label` | `string` | - | Group label (wraps in `Field`) |
+| `description` | `string` | - | Helper text |
+| `error` | `string` | - | Error message |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Radio button size |
+| `dirty` | `boolean` | `false` | Amber ring on all radios |
+| `required` | `boolean` | `false` | Red asterisk on label |
+| `disabled` | `boolean` | `false` | Disables all radios |
+| `name` | `string` | auto-generated | HTML `name` attribute for the radio group |
+| `className` | `string` | - | Additional CSS classes |
+
+## Examples
+
+### Horizontal layout with descriptions
+
+```tsx
+<RadioGroup
+  label="Priority"
+  orientation="horizontal"
+  list={[
+    { value: "low", label: "Low", description: "No rush" },
+    { value: "medium", label: "Medium" },
+    { value: "high", label: "High", description: "Urgent" },
+  ]}
+  defaultValue="medium"
+  onValueChange={setPriority}
+/>
+```
+
+### Controlled
+
+```tsx
+const [color, setColor] = useState("blue");
+
+<RadioGroup
+  label="Theme color"
+  list={["red", "blue", "green"]}
+  value={color}
+  onValueChange={setColor}
+/>
+```

package/docs/Select.md

@@ -0,0 +1,122 @@
+# Select
+
+Dropdown select with two variants: a native `<select>` element and a custom listbox with search, multi-select, and indicator support.
+
+## Import
+
+```tsx
+import { Select } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Select
+  label="Country"
+  list={["USA", "Canada", "Mexico"]}
+  placeholder="Choose a country"
+/>
+```
+
+## Variants
+
+- **`"native"`** (default for single-select) -- Renders a standard `<select>` element. Best for simple use cases and mobile.
+- **`"listbox"`** (default when `multiple` is set) -- Renders a custom dropdown with keyboard navigation, optional search, and selection indicators.
+
+The variant is auto-selected based on the `multiple` prop, or set it explicitly with `variant`.
+
+## Props
+
+Extends native `<select>` attributes (except `size`, `prefix`, `multiple`).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `list` | `InputOption[] \| InputOptionGroup[]` | **required** | Options as strings or `{ value, label, disabled?, description? }`. Groups via `{ label, options }`. |
+| `variant` | `"native" \| "listbox"` | `"native"` (auto `"listbox"` if `multiple`) | Rendering variant |
+| `placeholder` | `string` | `"Select..."` (listbox) | Placeholder text |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Controls sizing |
+| `label` | `string` | - | Wraps in a `Field` with this label |
+| `description` | `string` | - | Helper text below the select |
+| `error` | `string` | - | Error message |
+| `required` | `boolean` | `false` | Red asterisk on label |
+| `dirty` | `boolean` | `false` | Amber ring |
+| `disabled` | `boolean` | `false` | Disables the select |
+| `onValueChange` | `(value: string) => void` | - | Callback for single-select value changes |
+| **Listbox-only props** | | | |
+| `multiple` | `boolean` | `false` | Enable multi-select (forces listbox variant) |
+| `values` | `string[]` | - | Controlled multi-select values |
+| `defaultValues` | `string[]` | - | Default multi-select values (uncontrolled) |
+| `onValuesChange` | `(values: string[]) => void` | - | Callback for multi-select changes |
+| `searchable` | `boolean` | `false` | Show search/filter input in the dropdown |
+| `selectedSuffix` | `string` | `"selected"` | Suffix for the count display (e.g. "3 selected") |
+| `indicator` | `"check" \| "checkbox"` | `"check"` | Selection indicator style |
+| `prefix` | `ReactNode` | - | Affix before the select |
+| `suffix` | `ReactNode` | - | Affix after the select |
+
+### InputOption type
+
+```ts
+type InputOption = string | { value: string; label: string; disabled?: boolean; description?: string };
+```
+
+### InputOptionGroup type
+
+```ts
+type InputOptionGroup = { label: string; options: InputOption[] };
+```
+
+## Examples
+
+### Native with option objects
+
+```tsx
+<Select
+  label="Role"
+  list={[
+    { value: "admin", label: "Administrator" },
+    { value: "editor", label: "Editor" },
+    { value: "viewer", label: "Viewer", disabled: true },
+  ]}
+  onValueChange={(role) => console.log(role)}
+/>
+```
+
+### Listbox with search
+
+```tsx
+<Select
+  variant="listbox"
+  label="Framework"
+  searchable
+  list={["React", "Vue", "Angular", "Svelte", "Solid"]}
+  onValueChange={setFramework}
+/>
+```
+
+### Multi-select with checkbox indicator
+
+```tsx
+const [selected, setSelected] = useState<string[]>([]);
+
+<Select
+  label="Toppings"
+  multiple
+  searchable
+  indicator="checkbox"
+  list={["Pepperoni", "Mushrooms", "Onions", "Olives", "Peppers"]}
+  values={selected}
+  onValuesChange={setSelected}
+/>
+```
+
+### Option groups (native)
+
+```tsx
+<Select
+  label="Vehicle"
+  list={[
+    { label: "Cars", options: ["Sedan", "SUV", "Truck"] },
+    { label: "Bikes", options: ["Sport", "Cruiser"] },
+  ]}
+/>
+```

package/docs/Separator.md

@@ -0,0 +1,41 @@
+# Separator
+
+A horizontal or vertical divider line with optional centered label text.
+
+## Import
+
+```tsx
+import { Separator } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Separator />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| orientation | `"horizontal" \| "vertical"` | `"horizontal"` | Separator direction |
+| label | `string` | - | Optional centered label text (horizontal only) |
+| className | `string` | - | Additional CSS classes |
+
+## Examples
+
+### Horizontal with label
+
+```tsx
+<Separator label="or" />
+```
+
+### Vertical separator
+
+```tsx
+<div className="flex h-8 items-center gap-4">
+  <span>Left</span>
+  <Separator orientation="vertical" />
+  <span>Right</span>
+</div>
+```

package/docs/Sidebar.md

@@ -0,0 +1,88 @@
+# Sidebar
+
+A collapsible sidebar navigation with icon-only or letter-abbreviated collapsed mode, submenus, groups, and a toggle button.
+
+## Import
+
+```tsx
+import { Sidebar } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Sidebar>
+  <Sidebar.Item href="/" icon={<HomeIcon />} active>Home</Sidebar.Item>
+  <Sidebar.Item href="/settings" icon={<GearIcon />}>Settings</Sidebar.Item>
+  <Sidebar.Group label="Projects">
+    <Sidebar.Item href="/project-a">Project A</Sidebar.Item>
+    <Sidebar.Item href="/project-b">Project B</Sidebar.Item>
+  </Sidebar.Group>
+  <Sidebar.Toggle />
+</Sidebar>
+```
+
+## Props
+
+### Sidebar (root)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| collapsed | `boolean` | - | Controlled collapsed state |
+| defaultCollapsed | `boolean` | `false` | Default collapsed state (uncontrolled) |
+| onCollapsedChange | `(collapsed: boolean) => void` | - | Callback when collapsed state changes |
+| collapseMode | `"icons" \| "letters"` | `"icons"` | How items display when collapsed: icons only, or first 3 letters |
+| className | `string` | - | Additional CSS classes |
+
+### Sidebar.Item
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Item label |
+| href | `string` | - | Link URL |
+| icon | `ReactNode` | - | Leading icon |
+| active | `boolean` | - | Active state highlight |
+| disabled | `boolean` | - | Disable the item |
+| badge | `ReactNode` | - | Trailing badge element |
+| onClick | `() => void` | - | Click handler |
+| className | `string` | - | Additional CSS classes |
+
+### Sidebar.Group
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Grouped items |
+| label | `string` | - | Group heading |
+| className | `string` | - | Additional CSS classes |
+
+### Sidebar.Submenu
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Submenu items |
+| label | `string` | - | Submenu trigger label (required) |
+| icon | `ReactNode` | - | Leading icon |
+| defaultOpen | `boolean` | - | Whether the submenu starts open |
+| className | `string` | - | Additional CSS classes |
+
+### Sidebar.Toggle
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | `string` | - | Additional CSS classes |
+
+## Collapsible Sidebar
+
+```tsx
+const [collapsed, setCollapsed] = useState(false);
+
+<Sidebar collapsed={collapsed} onCollapsedChange={setCollapsed} collapseMode="icons">
+  <Sidebar.Item icon={<HomeIcon />}>Dashboard</Sidebar.Item>
+  <Sidebar.Item icon={<UsersIcon />}>Users</Sidebar.Item>
+  <Sidebar.Submenu label="Reports" icon={<ChartIcon />} defaultOpen>
+    <Sidebar.Item>Monthly</Sidebar.Item>
+    <Sidebar.Item>Yearly</Sidebar.Item>
+  </Sidebar.Submenu>
+  <Sidebar.Toggle />
+</Sidebar>
+```