@particle-academy/react-fancy 1.7.0 → 1.7.2

package/docs/Composer.md

@@ -0,0 +1,60 @@
+# Composer
+
+A chat-style message input with auto-growing textarea, Enter-to-submit, action slot, and controlled/uncontrolled value.
+
+## Import
+
+```tsx
+import { Composer } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Composer
+  onSubmit={(message) => console.log("Sent:", message)}
+  placeholder="Type a message..."
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | `string` | - | Controlled input value |
+| defaultValue | `string` | `""` | Default value (uncontrolled) |
+| onChange | `(value: string) => void` | - | Callback on input change |
+| onSubmit | `(value: string) => void` | - | Callback when Enter is pressed (without Shift) |
+| placeholder | `string` | `"Type a message..."` | Textarea placeholder |
+| actions | `ReactNode` | - | Custom action buttons rendered in the bottom toolbar |
+| disabled | `boolean` | `false` | Disable input and submit |
+| className | `string` | - | Additional CSS classes |
+
+## With Actions
+
+```tsx
+<Composer
+  onSubmit={handleSend}
+  actions={
+    <>
+      <button onClick={handleAttach}>Attach</button>
+      <button onClick={handleEmoji}>Emoji</button>
+    </>
+  }
+/>
+```
+
+## Controlled
+
+```tsx
+const [message, setMessage] = useState("");
+
+<Composer
+  value={message}
+  onChange={setMessage}
+  onSubmit={(val) => {
+    sendMessage(val);
+    setMessage("");
+  }}
+/>
+```

package/docs/ContentRenderer.md

@@ -0,0 +1,68 @@
+# ContentRenderer
+
+Renders HTML or Markdown strings as styled prose, with support for custom tag extensions.
+
+## Import
+
+```tsx
+import { ContentRenderer } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<ContentRenderer value="<h1>Hello</h1><p>World</p>" />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | `string` | - | HTML or Markdown string to render (required) |
+| format | `"html" \| "markdown" \| "auto"` | `"auto"` | Content format. `"auto"` detects based on content |
+| lineSpacing | `number` | `1.6` | Line height |
+| extensions | `RenderExtension[]` | - | Per-instance render extensions (merged with global) |
+| className | `string` | - | Additional CSS classes |
+
+## Render Extensions
+
+Extensions let you define custom tags that are rendered by React components. Register globally or pass per-instance:
+
+```tsx
+import { registerExtension } from "@particle-academy/react-fancy";
+
+registerExtension({
+  tag: "thinking",
+  component: ({ content }) => (
+    <details className="bg-zinc-100 p-3 rounded">
+      <summary>Thinking...</summary>
+      <div dangerouslySetInnerHTML={{ __html: content }} />
+    </details>
+  ),
+  block: true,
+});
+
+// Content with custom tags
+<ContentRenderer value="<thinking>Some internal reasoning</thinking><p>Final answer.</p>" />
+```
+
+### RenderExtension
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| tag | `string` | - | Tag name to match (case-insensitive) |
+| component | `ComponentType<RenderExtensionProps>` | - | React component to render the tag |
+| block | `boolean` | `true` | Block-level (`<div>`) vs inline (`<span>`) wrapping |
+
+### RenderExtensionProps
+
+| Prop | Type | Description |
+|------|------|-------------|
+| content | `string` | Inner content of the custom tag |
+| attributes | `Record<string, string>` | Parsed HTML attributes from the opening tag |
+
+## Markdown Rendering
+
+```tsx
+<ContentRenderer value="# Title\n\nParagraph with **bold** text." format="markdown" />
+```

package/docs/ContextMenu.md

@@ -0,0 +1,82 @@
+# ContextMenu
+
+A right-click context menu that appears at the cursor position. Compound component with Trigger, Content, Item, and Separator.
+
+## Import
+
+```tsx
+import { ContextMenu } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<ContextMenu>
+  <ContextMenu.Trigger>
+    <div className="w-64 h-32 border border-dashed rounded p-4">
+      Right-click here
+    </div>
+  </ContextMenu.Trigger>
+  <ContextMenu.Content>
+    <ContextMenu.Item onClick={() => console.log("cut")}>Cut</ContextMenu.Item>
+    <ContextMenu.Item onClick={() => console.log("copy")}>Copy</ContextMenu.Item>
+    <ContextMenu.Item onClick={() => console.log("paste")}>Paste</ContextMenu.Item>
+    <ContextMenu.Separator />
+    <ContextMenu.Item danger onClick={() => console.log("delete")}>Delete</ContextMenu.Item>
+  </ContextMenu.Content>
+</ContextMenu>
+```
+
+## Props
+
+### ContextMenu (root)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Trigger and content children |
+
+### ContextMenu.Trigger
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Area that responds to right-click |
+| className | `string` | - | Additional CSS classes |
+
+### ContextMenu.Content
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Menu items |
+| className | `string` | - | Additional CSS classes |
+
+### ContextMenu.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 |
+
+### ContextMenu.Separator
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | `string` | - | Additional CSS classes |
+
+## Example with Disabled Items
+
+```tsx
+<ContextMenu>
+  <ContextMenu.Trigger>
+    <div className="p-6 bg-zinc-100 rounded">Right-click target</div>
+  </ContextMenu.Trigger>
+  <ContextMenu.Content>
+    <ContextMenu.Item onClick={handleEdit}>Edit</ContextMenu.Item>
+    <ContextMenu.Item disabled>Move (unavailable)</ContextMenu.Item>
+    <ContextMenu.Separator />
+    <ContextMenu.Item danger onClick={handleRemove}>Remove</ContextMenu.Item>
+  </ContextMenu.Content>
+</ContextMenu>
+```

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