@particle-academy/react-fancy 1.7.1 → 1.7.2

package/docs/DatePicker.md

@@ -0,0 +1,64 @@
+# DatePicker
+
+Date input using native browser date/datetime pickers, supporting single dates and date ranges.
+
+## Import
+
+```tsx
+import { DatePicker } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<DatePicker label="Start date" onValueChange={(date) => console.log(date)} />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `range` | `boolean` | `false` | Enable range mode (renders two inputs with "to" separator) |
+| `includeTime` | `boolean` | `false` | Use `datetime-local` instead of `date` |
+| `min` | `string` | - | Minimum date (ISO format, e.g. `"2024-01-01"`) |
+| `max` | `string` | - | Maximum date |
+| `value` | `string` (single) / `[string, string]` (range) | - | Controlled value |
+| `defaultValue` | `string` / `[string, string]` | `""` / `["", ""]` | Default value (uncontrolled) |
+| `onValueChange` | `(value) => void` | - | Callback when value changes |
+| `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 sizing |
+| `dirty` | `boolean` | `false` | Amber ring |
+| `required` | `boolean` | `false` | Native required attribute + red asterisk |
+| `disabled` | `boolean` | `false` | Disables the input(s) |
+| `name` | `string` | - | Form field name. In range mode, generates `name_start` and `name_end`. |
+| `className` | `string` | - | Additional CSS classes |
+
+## Examples
+
+### Date with time
+
+```tsx
+<DatePicker
+  label="Event start"
+  includeTime
+  min="2024-01-01T00:00"
+  onValueChange={setEventStart}
+/>
+```
+
+### Date range
+
+```tsx
+const [range, setRange] = useState<[string, string]>(["", ""]);
+
+<DatePicker
+  label="Vacation"
+  range
+  value={range}
+  onValueChange={setRange}
+  min="2024-01-01"
+  max="2025-12-31"
+/>
+```

package/docs/Diagram.md

@@ -0,0 +1,119 @@
+# Diagram
+
+A high-level ERD/flowchart diagram built on top of Canvas. Accepts a schema of entities and relations, auto-layouts positions, and supports drag-to-move, export, and import.
+
+## Import
+
+```tsx
+import { Diagram } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage (Schema-driven)
+
+```tsx
+const schema = {
+  entities: [
+    {
+      name: "users",
+      fields: [
+        { name: "id", type: "bigint", primary: true },
+        { name: "name", type: "varchar" },
+        { name: "email", type: "varchar" },
+      ],
+    },
+    {
+      name: "posts",
+      fields: [
+        { name: "id", type: "bigint", primary: true },
+        { name: "user_id", type: "bigint", foreign: true },
+        { name: "title", type: "varchar" },
+        { name: "body", type: "text", nullable: true },
+      ],
+    },
+  ],
+  relations: [
+    { from: "users", to: "posts", type: "one-to-many" },
+  ],
+};
+
+<Diagram schema={schema} className="h-[600px]" downloadable minimap />
+```
+
+## Props
+
+### Diagram (root)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| schema | `DiagramSchema` | - | Declarative schema of entities and relations |
+| type | `"erd" \| "flowchart" \| "general"` | `"general"` | Diagram type (affects relation rendering) |
+| viewport | `ViewportState` | - | Controlled viewport |
+| defaultViewport | `ViewportState` | - | Default viewport (auto-computed from schema if omitted) |
+| onViewportChange | `(viewport: ViewportState) => void` | - | Viewport change callback |
+| downloadable | `boolean` | `false` | Enable download toolbar action |
+| importable | `boolean` | `false` | Enable import toolbar action |
+| exportFormats | `ExportFormat[]` | `["erd"]` | Export format options: `"erd"`, `"uml"`, `"dfd"` |
+| onImport | `(schema: DiagramSchema) => void` | - | Callback when a schema is imported |
+| minimap | `boolean` | `false` | Show minimap overlay |
+| className | `string` | - | Additional CSS classes |
+
+### Diagram.Entity
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| id | `string` | - | Unique identifier (defaults to `name`) |
+| name | `string` | - | Entity name (required) |
+| x | `number` | - | X position |
+| y | `number` | - | Y position |
+| color | `string` | - | Header color |
+| draggable | `boolean` | - | Allow drag-to-move |
+| onPositionChange | `(x: number, y: number) => void` | - | Drag callback |
+| children | `ReactNode` | - | Field children |
+| className | `string` | - | Additional CSS classes |
+
+### Diagram.Field
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| name | `string` | - | Field name (required) |
+| type | `string` | - | Data type label |
+| primary | `boolean` | - | Primary key indicator |
+| foreign | `boolean` | - | Foreign key indicator |
+| nullable | `boolean` | - | Nullable indicator |
+| className | `string` | - | Additional CSS classes |
+
+### Diagram.Relation
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| from | `string` | - | Source entity id (required) |
+| to | `string` | - | Target entity id (required) |
+| fromField | `string` | - | Source field name |
+| toField | `string` | - | Target field name |
+| type | `RelationType` | - | `"one-to-one"`, `"one-to-many"`, or `"many-to-many"` (required) |
+| label | `string` | - | Edge label |
+| className | `string` | - | Additional CSS classes |
+
+### Diagram.Toolbar
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | `string` | - | Additional CSS classes |
+
+## Declarative Children
+
+You can also compose entities and relations as JSX children instead of (or alongside) the schema prop:
+
+```tsx
+<Diagram type="erd" className="h-[500px]">
+  <Diagram.Entity name="categories" x={0} y={0} draggable>
+    <Diagram.Field name="id" type="int" primary />
+    <Diagram.Field name="name" type="varchar" />
+  </Diagram.Entity>
+  <Diagram.Entity name="products" x={300} y={0} draggable>
+    <Diagram.Field name="id" type="int" primary />
+    <Diagram.Field name="category_id" type="int" foreign />
+  </Diagram.Entity>
+  <Diagram.Relation from="categories" to="products" type="one-to-many" />
+</Diagram>
+```

package/docs/Dropdown.md

@@ -0,0 +1,79 @@
+# Dropdown
+
+A click-triggered dropdown menu with keyboard navigation, floating positioning, and item states.
+
+## Import
+
+```tsx
+import { Dropdown } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Dropdown>
+  <Dropdown.Trigger>
+    <button>Options</button>
+  </Dropdown.Trigger>
+  <Dropdown.Items>
+    <Dropdown.Item onClick={() => console.log("edit")}>Edit</Dropdown.Item>
+    <Dropdown.Item onClick={() => console.log("copy")}>Copy</Dropdown.Item>
+    <Dropdown.Separator />
+    <Dropdown.Item danger onClick={() => console.log("delete")}>Delete</Dropdown.Item>
+  </Dropdown.Items>
+</Dropdown>
+```
+
+## Props
+
+### Dropdown (root)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| placement | `Placement` | `"bottom-start"` | Position relative to trigger |
+| offset | `number` | `4` | Pixel offset from the trigger |
+
+### Dropdown.Trigger
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Trigger element |
+
+### Dropdown.Items
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Menu items |
+| className | `string` | - | Additional CSS classes |
+
+### Dropdown.Item
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Item content |
+| onClick | `() => void` | - | Click handler |
+| disabled | `boolean` | - | Disable the item |
+| danger | `boolean` | - | Destructive action styling (red) |
+| className | `string` | - | Additional CSS classes |
+
+### Dropdown.Separator
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | `string` | - | Additional CSS classes |
+
+## Example with Placement
+
+```tsx
+<Dropdown placement="bottom-end" offset={8}>
+  <Dropdown.Trigger>
+    <button>More actions</button>
+  </Dropdown.Trigger>
+  <Dropdown.Items>
+    <Dropdown.Item onClick={handleRename}>Rename</Dropdown.Item>
+    <Dropdown.Item disabled>Archive</Dropdown.Item>
+    <Dropdown.Separator />
+    <Dropdown.Item danger onClick={handleDelete}>Delete</Dropdown.Item>
+  </Dropdown.Items>
+</Dropdown>
+```

package/docs/Editor.md

@@ -0,0 +1,84 @@
+# Editor
+
+A rich text editor built on `contentEditable` with a configurable toolbar, HTML or Markdown output, and support for render extensions.
+
+## Import
+
+```tsx
+import { Editor } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Editor defaultValue="<p>Hello world</p>" onChange={(html) => console.log(html)}>
+  <Editor.Toolbar />
+  <Editor.Content />
+</Editor>
+```
+
+## Props
+
+### Editor (root)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | `string` | - | Controlled content value |
+| defaultValue | `string` | `""` | Default content (uncontrolled) |
+| onChange | `(value: string) => void` | - | Callback when content changes |
+| outputFormat | `"html" \| "markdown"` | `"html"` | Output format for the onChange value |
+| lineSpacing | `number` | `1.6` | Line height for content area |
+| placeholder | `string` | - | Placeholder text |
+| extensions | `RenderExtension[]` | - | Per-instance render extensions (merged with global) |
+| className | `string` | - | Additional CSS classes |
+
+### Editor.Toolbar
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| actions | `EditorAction[]` | - | Custom toolbar actions |
+| onAction | `(command: string) => void` | - | Custom action handler |
+| children | `ReactNode` | - | Custom toolbar content |
+| className | `string` | - | Additional CSS classes |
+
+#### EditorAction
+
+| Field | Type | Description |
+|-------|------|-------------|
+| icon | `ReactNode` | Action icon element |
+| label | `string` | Tooltip label |
+| command | `string` | `document.execCommand` command name |
+| commandArg | `string` | Optional command argument |
+| active | `boolean` | Whether the action is currently active |
+
+### Editor.Toolbar.Separator
+
+A visual separator between toolbar groups. No props.
+
+### Editor.Content
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | `string` | - | Additional CSS classes |
+
+## Markdown Output
+
+```tsx
+<Editor outputFormat="markdown" onChange={(md) => console.log(md)}>
+  <Editor.Toolbar />
+  <Editor.Content />
+</Editor>
+```
+
+## Custom Toolbar
+
+```tsx
+<Editor defaultValue="">
+  <Editor.Toolbar>
+    <button onClick={() => exec("bold")}>B</button>
+    <Editor.Toolbar.Separator />
+    <button onClick={() => exec("italic")}>I</button>
+  </Editor.Toolbar>
+  <Editor.Content />
+</Editor>
+```

package/docs/Emoji.md

@@ -0,0 +1,40 @@
+# Emoji
+
+Renders an emoji character by name slug or direct emoji string.
+
+## Import
+
+```tsx
+import { Emoji } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Emoji name="rocket" />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| name | `string` | - | Emoji slug resolved via the built-in emoji utils |
+| emoji | `string` | - | Direct emoji character (takes precedence over `name` resolution) |
+| size | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | Display size. Maps to: sm=text-base, md=text-2xl, lg=text-4xl, xl=text-6xl |
+| className | `string` | - | Additional CSS classes |
+
+Returns `null` if neither `emoji` nor `name` resolves to a character.
+
+## Examples
+
+### By name
+
+```tsx
+<Emoji name="fire" size="lg" />
+```
+
+### Direct emoji character
+
+```tsx
+<Emoji emoji="👋" size="xl" />
+```

package/docs/EmojiSelect.md

@@ -0,0 +1,47 @@
+# EmojiSelect
+
+A dropdown picker for selecting an emoji, with search filtering and category grouping.
+
+## Import
+
+```tsx
+import { EmojiSelect } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<EmojiSelect onChange={(emoji) => console.log(emoji)} />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | `string` | - | Controlled selected emoji character |
+| defaultValue | `string` | `""` | Default selected emoji (uncontrolled) |
+| onChange | `(emoji: string) => void` | - | Callback when an emoji is selected |
+| placeholder | `string` | `"Search emojis..."` | Search input placeholder text |
+| className | `string` | - | Additional CSS classes |
+
+Supports both controlled (`value` + `onChange`) and uncontrolled (`defaultValue`) usage.
+
+## Examples
+
+### Controlled
+
+```tsx
+const [emoji, setEmoji] = useState("");
+
+<EmojiSelect value={emoji} onChange={setEmoji} />
+```
+
+### With custom placeholder
+
+```tsx
+<EmojiSelect
+  defaultValue="🎉"
+  placeholder="Find an emoji..."
+  onChange={(e) => console.log("Selected:", e)}
+/>
+```

package/docs/Field.md

@@ -0,0 +1,48 @@
+# Field
+
+Form wrapper that adds a label, description, and error message around any input.
+
+## Import
+
+```tsx
+import { Field } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Field label="Email" error={errors.email} required>
+  <input type="email" />
+</Field>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | - | Label text displayed above the children |
+| `description` | `string` | - | Helper text shown below children (hidden when `error` is set) |
+| `error` | `string` | - | Error message shown below children in red |
+| `required` | `boolean` | `false` | Appends a red asterisk to the label |
+| `htmlFor` | `string` | - | Connects the label to an input via `id` |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Controls label text size |
+| `children` | `ReactNode` | **required** | The input element(s) to wrap |
+| `className` | `string` | - | Additional CSS classes on the outer `div` |
+
+## Examples
+
+### With description
+
+```tsx
+<Field label="Username" description="Must be 3-20 characters.">
+  <Input name="username" />
+</Field>
+```
+
+### With error
+
+```tsx
+<Field label="Password" error="Password is required." required>
+  <Input type="password" name="password" />
+</Field>
+```

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