@particle-academy/react-fancy 1.7.1 → 1.7.2

package/docs/Carousel.md

@@ -0,0 +1,97 @@
+# Carousel
+
+A multi-slide carousel/wizard with auto-play, looping, directional or wizard variants, named slides, and controllable index.
+
+## Import
+
+```tsx
+import { Carousel } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Carousel>
+  <Carousel.Panels>
+    <Carousel.Slide>Slide 1 content</Carousel.Slide>
+    <Carousel.Slide>Slide 2 content</Carousel.Slide>
+    <Carousel.Slide>Slide 3 content</Carousel.Slide>
+  </Carousel.Panels>
+  <Carousel.Controls />
+  <Carousel.Steps />
+</Carousel>
+```
+
+## Props
+
+### Carousel (root)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| defaultIndex | `number` | `0` | Initial slide index (uncontrolled) |
+| activeIndex | `number` | - | Controlled slide index |
+| onIndexChange | `(index: number) => void` | - | Callback when index changes |
+| autoPlay | `boolean` | `false` | Auto-advance slides |
+| interval | `number` | `5000` | Auto-play interval in ms |
+| loop | `boolean` | `false` | Loop back to first slide after last |
+| variant | `"directional" \| "wizard"` | `"directional"` | Visual variant (directional = arrows, wizard = steps) |
+| headless | `boolean` | `false` | Disable default styling for full custom layouts |
+| onFinish | `() => void` | - | Callback when "Finish" is clicked on the last slide (wizard variant) |
+| className | `string` | - | Additional CSS classes |
+
+### Carousel.Panels
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Slide elements |
+| className | `string` | - | Additional CSS classes |
+| transition | `"none" \| "fade"` | - | Transition effect between slides |
+
+### Carousel.Slide
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Slide content |
+| name | `string` | - | Named identifier (used by Steps display) |
+| className | `string` | - | Additional CSS classes |
+
+### Carousel.Controls
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| prevLabel | `ReactNode` | - | Custom previous button content |
+| nextLabel | `ReactNode` | - | Custom next button content |
+| finishLabel | `ReactNode` | - | Custom finish button content (wizard, last slide) |
+| className | `string` | - | Additional CSS classes |
+
+### Carousel.Steps
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | `string` | - | Additional CSS classes |
+
+## Wizard Variant
+
+```tsx
+<Carousel variant="wizard" onFinish={() => console.log("done!")}>
+  <Carousel.Steps />
+  <Carousel.Panels transition="fade">
+    <Carousel.Slide name="Account">Step 1: Create account</Carousel.Slide>
+    <Carousel.Slide name="Profile">Step 2: Fill profile</Carousel.Slide>
+    <Carousel.Slide name="Confirm">Step 3: Confirm details</Carousel.Slide>
+  </Carousel.Panels>
+  <Carousel.Controls finishLabel="Complete Setup" />
+</Carousel>
+```
+
+## Auto-Play with Looping
+
+```tsx
+<Carousel autoPlay interval={3000} loop>
+  <Carousel.Panels>
+    <Carousel.Slide>Banner 1</Carousel.Slide>
+    <Carousel.Slide>Banner 2</Carousel.Slide>
+    <Carousel.Slide>Banner 3</Carousel.Slide>
+  </Carousel.Panels>
+</Carousel>
+```

package/docs/Chart.md

@@ -0,0 +1,126 @@
+# Chart
+
+A collection of SVG chart components: Bar, HorizontalBar, StackedBar, Line, Area, Pie, Donut, and Sparkline.
+
+## Import
+
+```tsx
+import { Chart } from "@particle-academy/react-fancy";
+```
+
+## Chart Types
+
+### Chart.Bar
+
+```tsx
+<Chart.Bar
+  data={[
+    { label: "Jan", value: 30 },
+    { label: "Feb", value: 45 },
+    { label: "Mar", value: 28 },
+  ]}
+  height={200}
+  showValues
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| data | `ChartBarData[]` | - | Array of `{ label, value, color? }` |
+| height | `number` | - | Chart height in px |
+| showValues | `boolean` | - | Display values above bars |
+| className | `string` | - | Additional CSS classes |
+
+### Chart.HorizontalBar
+
+Same props as `Chart.Bar`, rendered horizontally.
+
+### Chart.Line
+
+```tsx
+<Chart.Line
+  labels={["Jan", "Feb", "Mar", "Apr"]}
+  series={[
+    { label: "Revenue", data: [100, 200, 150, 300], color: "#3b82f6" },
+    { label: "Costs", data: [80, 120, 100, 180], color: "#ef4444" },
+  ]}
+  height={300}
+  showDots
+  tooltip
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| labels | `string[]` | - | X-axis labels |
+| series | `ChartSeries[]` | - | Array of `{ label, data, color? }` |
+| curve | `"linear" \| "monotone"` | - | Line interpolation |
+| showDots | `boolean` | - | Show data points |
+| fill | `boolean` | - | Fill area under line |
+| fillOpacity | `number` | - | Opacity of fill area |
+| height | `number` | - | Chart height in px |
+| xAxis | `boolean \| { label?, tickCount? }` | - | X-axis config |
+| yAxis | `boolean \| { label?, tickCount? }` | - | Y-axis config |
+| grid | `boolean \| { horizontal?, vertical? }` | - | Grid lines |
+| tooltip | `boolean` | - | Show tooltip on hover |
+| animate | `boolean` | - | Enable animations |
+| responsive | `boolean` | - | Responsive width |
+| className | `string` | - | Additional CSS classes |
+
+### Chart.Area
+
+Same as `Chart.Line` without the `fill` prop (area fill is always enabled).
+
+### Chart.StackedBar
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| labels | `string[]` | - | X-axis labels |
+| series | `ChartSeries[]` | - | Stacked data series |
+| *(plus ChartCommonProps)* | | | height, xAxis, yAxis, grid, tooltip, animate, responsive |
+
+### Chart.Pie
+
+```tsx
+<Chart.Pie
+  data={[
+    { label: "Desktop", value: 60 },
+    { label: "Mobile", value: 35 },
+    { label: "Tablet", value: 5 },
+  ]}
+  size={200}
+  showLabels
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| data | `ChartPieData[]` | - | Array of `{ label, value, color? }` |
+| size | `number` | - | Diameter in px |
+| showLabels | `boolean` | - | Display labels |
+| tooltip | `boolean` | - | Show tooltip on hover |
+| className | `string` | - | Additional CSS classes |
+
+### Chart.Donut
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| data | `ChartDonutData[]` | - | Array of `{ label, value, color? }` |
+| size | `number` | - | Diameter in px |
+| strokeWidth | `number` | - | Ring thickness |
+| showLegend | `boolean` | - | Show legend |
+| className | `string` | - | Additional CSS classes |
+
+### Chart.Sparkline
+
+```tsx
+<Chart.Sparkline data={[5, 10, 8, 15, 12, 20]} width={120} height={32} color="#22c55e" />
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| data | `number[]` | - | Data points |
+| width | `number` | - | Chart width in px |
+| height | `number` | - | Chart height in px |
+| color | `string` | - | Line color |
+| className | `string` | - | Additional CSS classes |

package/docs/Checkbox.md

@@ -0,0 +1,86 @@
+# Checkbox / CheckboxGroup
+
+Single checkbox with optional label, and a group component for managing multiple checkbox selections.
+
+## Import
+
+```tsx
+import { Checkbox, CheckboxGroup } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Checkbox label="I agree to the terms" />
+```
+
+```tsx
+<CheckboxGroup
+  label="Interests"
+  list={["Music", "Sports", "Travel"]}
+  onValueChange={(values) => console.log(values)}
+/>
+```
+
+## Checkbox Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `checked` | `boolean` | - | Controlled checked state |
+| `defaultChecked` | `boolean` | `false` | Initial checked state (uncontrolled) |
+| `onCheckedChange` | `(checked: boolean) => void` | - | Callback when checked state changes |
+| `indeterminate` | `boolean` | `false` | Sets the indeterminate visual state |
+| `label` | `string` | - | Label text next to the checkbox |
+| `description` | `string` | - | Helper text below the label |
+| `error` | `string` | - | Error message |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Checkbox size |
+| `dirty` | `boolean` | `false` | Amber ring |
+| `required` | `boolean` | `false` | Red asterisk on label |
+| `disabled` | `boolean` | `false` | Disables the checkbox |
+| `className` | `string` | - | Additional CSS classes |
+
+## CheckboxGroup Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `list` | `InputOption[]` | **required** | Options as strings or `{ value, label, disabled?, description? }` |
+| `value` | `V[]` | - | Controlled selected values |
+| `defaultValue` | `V[]` | `[]` | Default selected values (uncontrolled) |
+| `onValueChange` | `(values: 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"` | Checkbox size |
+| `dirty` | `boolean` | `false` | Amber ring on all checkboxes |
+| `disabled` | `boolean` | `false` | Disables all checkboxes |
+
+## Examples
+
+### Controlled checkbox
+
+```tsx
+const [agreed, setAgreed] = useState(false);
+
+<Checkbox
+  label="Subscribe to newsletter"
+  checked={agreed}
+  onCheckedChange={setAgreed}
+/>
+```
+
+### Horizontal checkbox group with objects
+
+```tsx
+<CheckboxGroup
+  label="Permissions"
+  orientation="horizontal"
+  list={[
+    { value: "read", label: "Read" },
+    { value: "write", label: "Write" },
+    { value: "delete", label: "Delete", description: "Dangerous" },
+  ]}
+  defaultValue={["read"]}
+  onValueChange={setPermissions}
+/>
+```

package/docs/ColorPicker.md

@@ -0,0 +1,49 @@
+# ColorPicker
+
+A color picker with a swatch button, hex display, and optional preset colors.
+
+## Import
+
+```tsx
+import { ColorPicker } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<ColorPicker onChange={(color) => console.log(color)} />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | `string` | - | Controlled hex color value |
+| defaultValue | `string` | `"#3b82f6"` | Default hex color (uncontrolled) |
+| onChange | `(color: string) => void` | - | Callback when the color changes |
+| presets | `string[]` | - | Array of preset hex colors shown in the native picker's datalist |
+| size | `"sm" \| "md" \| "lg"` | `"md"` | Swatch and text size |
+| variant | `"outline" \| "filled"` | `"outline"` | Swatch border style |
+| disabled | `boolean` | `false` | Disable interaction |
+| className | `string` | - | Additional CSS classes |
+
+Supports both controlled (`value` + `onChange`) and uncontrolled (`defaultValue`) usage.
+
+## Examples
+
+### With presets
+
+```tsx
+<ColorPicker
+  defaultValue="#10b981"
+  presets={["#ef4444", "#3b82f6", "#10b981", "#f59e0b"]}
+/>
+```
+
+### Controlled
+
+```tsx
+const [color, setColor] = useState("#8b5cf6");
+
+<ColorPicker value={color} onChange={setColor} size="lg" />
+```

package/docs/Command.md

@@ -0,0 +1,88 @@
+# Command
+
+A command palette (Cmd+K style) with search input, grouped items, keyboard navigation, and focus trapping. Renders via a portal with backdrop.
+
+## Import
+
+```tsx
+import { Command } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+const [open, setOpen] = useState(false);
+
+useEffect(() => {
+  const handler = (e: KeyboardEvent) => {
+    if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
+      e.preventDefault();
+      setOpen(true);
+    }
+  };
+  document.addEventListener("keydown", handler);
+  return () => document.removeEventListener("keydown", handler);
+}, []);
+
+<Command open={open} onClose={() => setOpen(false)}>
+  <Command.Input placeholder="Search commands..." />
+  <Command.List>
+    <Command.Group heading="Actions">
+      <Command.Item onSelect={() => console.log("new")}>New File</Command.Item>
+      <Command.Item onSelect={() => console.log("open")}>Open File</Command.Item>
+    </Command.Group>
+    <Command.Group heading="Settings">
+      <Command.Item onSelect={() => console.log("prefs")}>Preferences</Command.Item>
+    </Command.Group>
+    <Command.Empty>No results found.</Command.Empty>
+  </Command.List>
+</Command>
+```
+
+## Props
+
+### Command (root)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| open | `boolean` | - | Whether the palette is visible (required) |
+| onClose | `() => void` | - | Callback to close the palette (required) |
+| className | `string` | - | Additional CSS classes |
+
+### Command.Input
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| placeholder | `string` | - | Input placeholder text |
+| className | `string` | - | Additional CSS classes |
+
+### Command.List
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Groups and items |
+| className | `string` | - | Additional CSS classes |
+
+### Command.Group
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Group items |
+| heading | `string` | - | Group heading label |
+| className | `string` | - | Additional CSS classes |
+
+### Command.Item
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Item content |
+| value | `string` | - | Searchable value (defaults to text content) |
+| onSelect | `() => void` | - | Callback when item is selected |
+| className | `string` | - | Additional CSS classes |
+
+### Command.Empty
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | `"No results found."` | Content shown when no items match |
+| className | `string` | - | Additional CSS classes |

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