@particle-academy/react-fancy 1.7.1 → 1.7.3

package/docs/Input.md

@@ -0,0 +1,73 @@
+# Input
+
+Text input with built-in label, error, prefix/suffix, and leading/trailing icon support.
+
+## Import
+
+```tsx
+import { Input } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Input label="Email" type="email" placeholder="you@example.com" />
+```
+
+## Props
+
+Extends all native `<input>` attributes (except `size`, `type`, `prefix`).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `"text" \| "email" \| "password" \| "number" \| "tel" \| "url" \| "search"` | `"text"` | Input type |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Controls input height and text size |
+| `label` | `string` | - | Wraps input in a `Field` with this label |
+| `description` | `string` | - | Helper text below the input |
+| `error` | `string` | - | Error message (red text below input, red border) |
+| `required` | `boolean` | `false` | Red asterisk on label, sets native `required` |
+| `dirty` | `boolean` | `false` | Amber ring to indicate unsaved changes |
+| `disabled` | `boolean` | `false` | Disables the input |
+| `leading` | `ReactNode` | - | Icon/element positioned inside the input on the left |
+| `trailing` | `ReactNode` | - | Icon/element positioned inside the input on the right |
+| `prefix` | `ReactNode` | - | Affix rendered before the input |
+| `suffix` | `ReactNode` | - | Affix rendered after the input |
+| `prefixPosition` | `"inside" \| "outside"` | - | Whether prefix renders inside or outside the input border |
+| `suffixPosition` | `"inside" \| "outside"` | - | Whether suffix renders inside or outside the input border |
+| `onValueChange` | `(value: string) => void` | - | Convenience callback with the string value directly |
+| `className` | `string` | - | Additional CSS classes on the `<input>` element |
+
+## Examples
+
+### With leading icon
+
+```tsx
+import { Search } from "lucide-react";
+
+<Input
+  label="Search"
+  type="search"
+  leading={<Search size={16} />}
+  placeholder="Search..."
+/>
+```
+
+### With prefix and suffix
+
+```tsx
+<Input prefix="https://" suffix=".com" placeholder="yoursite" />
+```
+
+### Controlled with onValueChange
+
+```tsx
+const [email, setEmail] = useState("");
+
+<Input
+  label="Email"
+  type="email"
+  value={email}
+  onValueChange={setEmail}
+  error={email ? undefined : "Required"}
+/>
+```

package/docs/Kanban.md

@@ -0,0 +1,79 @@
+# Kanban
+
+A drag-and-drop kanban board using the HTML5 Drag and Drop API. Cards can be moved between columns.
+
+## Import
+
+```tsx
+import { Kanban } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Kanban onCardMove={(cardId, from, to) => console.log(`${cardId}: ${from} -> ${to}`)}>
+  <Kanban.Column id="todo" title="To Do">
+    <Kanban.Card id="task-1">Design homepage</Kanban.Card>
+    <Kanban.Card id="task-2">Write tests</Kanban.Card>
+  </Kanban.Column>
+  <Kanban.Column id="in-progress" title="In Progress">
+    <Kanban.Card id="task-3">Build API</Kanban.Card>
+  </Kanban.Column>
+  <Kanban.Column id="done" title="Done">
+    <Kanban.Card id="task-4">Setup CI/CD</Kanban.Card>
+  </Kanban.Column>
+</Kanban>
+```
+
+## Props
+
+### Kanban (root)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| onCardMove | `(cardId: string, fromColumn: string, toColumn: string) => void` | - | Callback when a card is dropped into a different column |
+| className | `string` | - | Additional CSS classes |
+
+### Kanban.Column
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| id | `string` | - | Unique column identifier (required) |
+| title | `string` | - | Column header text |
+| className | `string` | - | Additional CSS classes |
+
+### Kanban.Card
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| id | `string` | - | Unique card identifier (required) |
+| children | `ReactNode` | - | Card content |
+| className | `string` | - | Additional CSS classes |
+
+## Stateful Example
+
+```tsx
+const [columns, setColumns] = useState({
+  todo: ["task-1", "task-2"],
+  doing: ["task-3"],
+  done: [],
+});
+
+function handleMove(cardId: string, from: string, to: string) {
+  setColumns((prev) => ({
+    ...prev,
+    [from]: prev[from].filter((id) => id !== cardId),
+    [to]: [...prev[to], cardId],
+  }));
+}
+
+<Kanban onCardMove={handleMove}>
+  {Object.entries(columns).map(([colId, cards]) => (
+    <Kanban.Column key={colId} id={colId} title={colId}>
+      {cards.map((id) => (
+        <Kanban.Card key={id} id={id}>{id}</Kanban.Card>
+      ))}
+    </Kanban.Column>
+  ))}
+</Kanban>
+```

package/docs/Menu.md

@@ -0,0 +1,71 @@
+# Menu
+
+A navigation menu supporting horizontal/vertical orientation, nested submenus, grouped items, icons, and badges.
+
+## Import
+
+```tsx
+import { Menu } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Menu>
+  <Menu.Item href="/" active>Home</Menu.Item>
+  <Menu.Item href="/about">About</Menu.Item>
+  <Menu.Submenu label="Products" icon={<BoxIcon />}>
+    <Menu.Item href="/products/widgets">Widgets</Menu.Item>
+    <Menu.Item href="/products/gadgets">Gadgets</Menu.Item>
+  </Menu.Submenu>
+</Menu>
+```
+
+## Props
+
+### Menu (root)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| orientation | `"horizontal" \| "vertical"` | `"vertical"` | Layout direction |
+| className | `string` | - | Additional CSS classes |
+
+### Menu.Item
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Item content |
+| 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 |
+
+### Menu.Submenu
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| label | `ReactNode` | - | Submenu trigger label (required) |
+| icon | `ReactNode` | - | Leading icon |
+| defaultOpen | `boolean` | - | Whether the submenu starts open |
+| className | `string` | - | Additional CSS classes |
+
+### Menu.Group
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Grouped items |
+| label | `string` | - | Group heading |
+| className | `string` | - | Additional CSS classes |
+
+## Horizontal Menu
+
+```tsx
+<Menu orientation="horizontal">
+  <Menu.Item href="/" active>Home</Menu.Item>
+  <Menu.Item href="/docs">Docs</Menu.Item>
+  <Menu.Item href="/pricing" badge={<span>New</span>}>Pricing</Menu.Item>
+</Menu>
+```

package/docs/MobileMenu.md

@@ -0,0 +1,69 @@
+# MobileMenu
+
+Mobile navigation components with two variants: a slide-out flyout panel and a fixed bottom tab bar.
+
+## Import
+
+```tsx
+import { MobileMenu } from "@particle-academy/react-fancy";
+```
+
+## Flyout
+
+A slide-out panel from the left or right edge.
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<button onClick={() => setOpen(true)}>Menu</button>
+
+<MobileMenu.Flyout open={open} onClose={() => setOpen(false)} side="left" title="Menu">
+  <MobileMenu.Item href="/" icon={<HomeIcon />} active>Home</MobileMenu.Item>
+  <MobileMenu.Item href="/about" icon={<InfoIcon />}>About</MobileMenu.Item>
+  <MobileMenu.Item href="/contact" icon={<MailIcon />}>Contact</MobileMenu.Item>
+</MobileMenu.Flyout>
+```
+
+## Bottom Bar
+
+A fixed bottom navigation bar for mobile.
+
+```tsx
+<MobileMenu.BottomBar>
+  <MobileMenu.Item href="/" icon={<HomeIcon />} active>Home</MobileMenu.Item>
+  <MobileMenu.Item href="/search" icon={<SearchIcon />}>Search</MobileMenu.Item>
+  <MobileMenu.Item href="/profile" icon={<UserIcon />}>Profile</MobileMenu.Item>
+</MobileMenu.BottomBar>
+```
+
+## Props
+
+### MobileMenu.Flyout
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| open | `boolean` | - | Whether the flyout is visible (required) |
+| onClose | `() => void` | - | Callback to close the flyout (required) |
+| side | `"left" \| "right"` | - | Which edge the panel slides from |
+| title | `string` | - | Optional header title |
+| className | `string` | - | Additional CSS classes |
+
+### MobileMenu.BottomBar
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Menu items |
+| className | `string` | - | Additional CSS classes |
+
+### MobileMenu.Item
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Item label |
+| href | `string` | - | Link URL |
+| icon | `ReactNode` | - | Icon element |
+| active | `boolean` | - | Active state highlight |
+| disabled | `boolean` | - | Disable the item |
+| badge | `ReactNode` | - | Badge element |
+| onClick | `() => void` | - | Click handler |
+| className | `string` | - | Additional CSS classes |

package/docs/Modal.md

@@ -0,0 +1,74 @@
+# Modal
+
+A dialog overlay with backdrop, focus trapping, escape-to-close, and body scroll locking. Renders via a portal.
+
+## Import
+
+```tsx
+import { Modal } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<button onClick={() => setOpen(true)}>Open Modal</button>
+
+<Modal open={open} onClose={() => setOpen(false)}>
+  <Modal.Header>Confirm Action</Modal.Header>
+  <Modal.Body>
+    <p>Are you sure you want to proceed?</p>
+  </Modal.Body>
+  <Modal.Footer>
+    <button onClick={() => setOpen(false)}>Cancel</button>
+    <button onClick={handleConfirm}>Confirm</button>
+  </Modal.Footer>
+</Modal>
+```
+
+## Props
+
+### Modal (root)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| open | `boolean` | - | Whether the modal is visible (required) |
+| onClose | `() => void` | - | Callback to close the modal (required) |
+| size | `"sm" \| "md" \| "lg" \| "xl" \| "full"` | `"md"` | Max width of the modal panel |
+| className | `string` | - | Additional CSS classes for the panel |
+
+### Modal.Header
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Header content |
+| className | `string` | - | Additional CSS classes |
+
+### Modal.Body
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Body content |
+| className | `string` | - | Additional CSS classes |
+
+### Modal.Footer
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Footer content (typically action buttons) |
+| className | `string` | - | Additional CSS classes |
+
+## Large Modal
+
+```tsx
+<Modal open={open} onClose={() => setOpen(false)} size="xl">
+  <Modal.Header>Large Content</Modal.Header>
+  <Modal.Body>
+    <p>This modal uses the xl size variant for wider content.</p>
+  </Modal.Body>
+  <Modal.Footer>
+    <button onClick={() => setOpen(false)}>Close</button>
+  </Modal.Footer>
+</Modal>
+```

package/docs/MultiSwitch.md

@@ -0,0 +1,64 @@
+# MultiSwitch
+
+Segmented control that allows selecting one value from a set of options, with an animated sliding indicator.
+
+## Import
+
+```tsx
+import { MultiSwitch } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<MultiSwitch
+  list={["Daily", "Weekly", "Monthly"]}
+  defaultValue="Weekly"
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `list` | `InputOption[]` | **required** | Options as strings or `{ value, label, disabled? }` |
+| `value` | `V` | - | Controlled selected value |
+| `defaultValue` | `V` | first option | Default selected value (uncontrolled) |
+| `onValueChange` | `(value: V) => void` | - | Callback when selection changes |
+| `linear` | `boolean` | `false` | When true, clicking any button cycles to the next option instead of selecting the clicked one |
+| `label` | `string` | - | Wraps in a `Field` with this label |
+| `description` | `string` | - | Helper text |
+| `error` | `string` | - | Error message |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Controls padding and text size |
+| `dirty` | `boolean` | `false` | Amber ring |
+| `disabled` | `boolean` | `false` | Disables all options |
+| `name` | `string` | - | Form field name (renders a hidden input) |
+| `className` | `string` | - | Additional CSS classes |
+
+## Examples
+
+### Controlled with label
+
+```tsx
+const [interval, setInterval] = useState("monthly");
+
+<MultiSwitch
+  label="Billing interval"
+  list={[
+    { value: "monthly", label: "Monthly" },
+    { value: "yearly", label: "Yearly" },
+  ]}
+  value={interval}
+  onValueChange={setInterval}
+/>
+```
+
+### Linear cycling
+
+```tsx
+<MultiSwitch
+  linear
+  list={["Off", "Low", "Medium", "High"]}
+  defaultValue="Off"
+/>
+```

package/docs/Navbar.md

@@ -0,0 +1,65 @@
+# Navbar
+
+A top navigation bar with brand slot, navigation items, and a mobile hamburger toggle.
+
+## Import
+
+```tsx
+import { Navbar } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Navbar>
+  <Navbar.Brand>
+    <a href="/">MyApp</a>
+  </Navbar.Brand>
+  <Navbar.Items>
+    <Navbar.Item href="/" active>Home</Navbar.Item>
+    <Navbar.Item href="/about">About</Navbar.Item>
+    <Navbar.Item href="/contact">Contact</Navbar.Item>
+  </Navbar.Items>
+  <Navbar.Toggle />
+</Navbar>
+```
+
+## Props
+
+### Navbar (root)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Brand, items, toggle children |
+| className | `string` | - | Additional CSS classes |
+
+### Navbar.Brand
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Logo or brand element |
+| className | `string` | - | Additional CSS classes |
+
+### Navbar.Items
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Navigation items |
+| className | `string` | - | Additional CSS classes |
+
+### Navbar.Item
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Item content |
+| href | `string` | - | Link URL |
+| active | `boolean` | - | Active/current page indicator |
+| className | `string` | - | Additional CSS classes |
+
+### Navbar.Toggle
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | `string` | - | Additional CSS classes |
+
+The Navbar manages a `mobileOpen` state internally. `Navbar.Toggle` toggles the mobile navigation drawer, and `Navbar.Items` responds to that state.

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..." />
+```