@particle-academy/react-fancy 1.7.0 → 1.7.2

package/docs/FileUpload.md

@@ -0,0 +1,81 @@
+# FileUpload
+
+Compound file upload component with drag-and-drop dropzone and file list display (list or thumbnail mode).
+
+## Import
+
+```tsx
+import { FileUpload } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<FileUpload onChange={(files) => console.log(files)}>
+  <FileUpload.Dropzone />
+  <FileUpload.List />
+</FileUpload>
+```
+
+## Components
+
+### `FileUpload` (root)
+
+Provides file state context to its children.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | **required** | Must contain `Dropzone` and/or `List` |
+| `value` | `File[]` | - | Controlled file list |
+| `onChange` | `(files: File[]) => void` | - | Callback when files change |
+| `accept` | `string` | - | Accepted file types (e.g. `"image/*,.pdf"`) |
+| `multiple` | `boolean` | `true` | Allow multiple files |
+| `maxFiles` | `number` | - | Maximum number of files |
+| `maxSize` | `number` | - | Maximum file size in bytes (files exceeding this are silently filtered) |
+| `disabled` | `boolean` | `false` | Disables upload and removal |
+| `className` | `string` | - | Additional CSS classes on the wrapper |
+
+### `FileUpload.Dropzone`
+
+Drag-and-drop area that also opens a file picker on click.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | Default upload icon + text | Custom dropzone content |
+| `className` | `string` | - | Additional CSS classes |
+
+### `FileUpload.List`
+
+Displays the uploaded files with remove buttons.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `thumbnail` | `boolean` | `false` | Show image thumbnails in a grid instead of a file list |
+| `className` | `string` | - | Additional CSS classes |
+
+## Examples
+
+### With file constraints
+
+```tsx
+<FileUpload
+  accept="image/*"
+  maxFiles={5}
+  maxSize={5 * 1024 * 1024}
+  onChange={setFiles}
+>
+  <FileUpload.Dropzone>
+    <p>Drop images here (max 5MB each)</p>
+  </FileUpload.Dropzone>
+  <FileUpload.List thumbnail />
+</FileUpload>
+```
+
+### List mode
+
+```tsx
+<FileUpload onChange={handleUpload}>
+  <FileUpload.Dropzone />
+  <FileUpload.List />
+</FileUpload>
+```

package/docs/Heading.md

@@ -0,0 +1,43 @@
+# Heading
+
+A heading component that renders semantic heading elements with configurable size and weight.
+
+## Import
+
+```tsx
+import { Heading } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Heading>Page Title</Heading>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| as | `"h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6"` | `"h2"` | Which heading element to render |
+| size | `"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `"lg"` | Text size |
+| weight | `"normal" \| "medium" \| "semibold" \| "bold"` | `"bold"` | Font weight |
+
+Also extends all native `<h1>`-`<h6>` HTML attributes.
+
+## Examples
+
+### Page title
+
+```tsx
+<Heading as="h1" size="2xl">
+  Welcome
+</Heading>
+```
+
+### Section heading
+
+```tsx
+<Heading as="h3" size="md" weight="semibold">
+  Settings
+</Heading>
+```

package/docs/Icon.md

@@ -0,0 +1,75 @@
+# Icon
+
+An icon container that resolves icon names from registered icon sets (Lucide by default).
+
+## Import
+
+```tsx
+import { Icon, registerIconSet, configureIcons } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Icon name="rocket" />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| name | `string` | - | Icon name to resolve from the registered icon set (e.g., `"rocket"`, `"arrow-right"`) |
+| size | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Icon container size. Maps to: xs=12px, sm=16px, md=20px, lg=24px, xl=32px |
+| iconSet | `string` | - | Which registered icon set to use (defaults to the configured default) |
+
+Also extends all native `<span>` HTML attributes. When `children` are provided, they render instead of the resolved icon.
+
+## Icon Configuration
+
+### registerIconSet
+
+Register a custom icon set by name.
+
+```tsx
+import { registerIconSet } from "@particle-academy/react-fancy";
+
+registerIconSet("custom", {
+  resolve: (name) => MyCustomIconMap[name] ?? null,
+});
+```
+
+The `IconSet` interface requires a single `resolve` method:
+
+```ts
+interface IconSet {
+  resolve: (name: string) => ComponentType<{ className?: string; size?: number }> | null;
+}
+```
+
+### configureIcons
+
+Set the default icon set used when `iconSet` is not specified on `<Icon>`.
+
+```tsx
+import { configureIcons } from "@particle-academy/react-fancy";
+
+configureIcons({ defaultSet: "custom" });
+```
+
+The built-in default is `"lucide"`, which resolves kebab-case names (e.g., `"arrow-right"`) to Lucide React icons.
+
+## Examples
+
+### Different sizes
+
+```tsx
+<Icon name="star" size="xs" />
+<Icon name="star" size="md" />
+<Icon name="star" size="xl" />
+```
+
+### Using a specific icon set
+
+```tsx
+<Icon name="home" iconSet="custom" size="lg" />
+```

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.