@particle-academy/react-fancy 1.7.0 → 1.7.2

package/docs/Callout.md

@@ -0,0 +1,46 @@
+# Callout
+
+A colored alert/callout box with optional icon and dismiss button.
+
+## Import
+
+```tsx
+import { Callout } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Callout>This is an informational callout.</Callout>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | **required** | Callout content |
+| color | `"blue" \| "green" \| "amber" \| "red" \| "zinc"` | `"blue"` | Callout color theme |
+| icon | `ReactNode` | - | Icon element displayed on the left |
+| dismissible | `boolean` | `false` | Show a dismiss/close button |
+| onDismiss | `() => void` | - | Callback when dismiss button is clicked |
+| className | `string` | - | Additional CSS classes |
+
+## Examples
+
+### Warning callout with icon
+
+```tsx
+import { AlertTriangle } from "lucide-react";
+
+<Callout color="amber" icon={<AlertTriangle size={20} />}>
+  Your trial expires in 3 days.
+</Callout>
+```
+
+### Dismissible error callout
+
+```tsx
+<Callout color="red" dismissible onDismiss={() => setVisible(false)}>
+  Something went wrong. Please try again.
+</Callout>
+```

package/docs/Canvas.md

@@ -0,0 +1,102 @@
+# Canvas
+
+An infinite pannable and zoomable canvas for positioning nodes with edges between them. Includes minimap and zoom controls.
+
+## Import
+
+```tsx
+import { Canvas } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Canvas className="h-96 w-full" showGrid>
+  <Canvas.Node id="a" x={50} y={50} draggable>
+    <div className="rounded border bg-white p-4">Node A</div>
+  </Canvas.Node>
+  <Canvas.Node id="b" x={300} y={150} draggable>
+    <div className="rounded border bg-white p-4">Node B</div>
+  </Canvas.Node>
+  <Canvas.Edge from="a" to="b" curve="bezier" markerEnd="canvas-arrow" />
+  <Canvas.Controls />
+  <Canvas.Minimap />
+</Canvas>
+```
+
+## Props
+
+### Canvas (root)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| viewport | `ViewportState` | - | Controlled viewport `{ panX, panY, zoom }` |
+| defaultViewport | `ViewportState` | `{ panX: 0, panY: 0, zoom: 1 }` | Default viewport (uncontrolled) |
+| onViewportChange | `(viewport: ViewportState) => void` | - | Callback when viewport changes |
+| minZoom | `number` | `0.1` | Minimum zoom level |
+| maxZoom | `number` | `3` | Maximum zoom level |
+| pannable | `boolean` | `true` | Enable panning (click+drag on background) |
+| zoomable | `boolean` | `true` | Enable zoom (Ctrl+scroll) |
+| gridSize | `number` | - | Grid cell size in px |
+| showGrid | `boolean` | `false` | Display dot grid background |
+| fitOnMount | `boolean` | `false` | Auto-fit all nodes into view on mount |
+| className | `string` | - | Additional CSS classes |
+| style | `CSSProperties` | - | Inline styles |
+
+### Canvas.Node
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| id | `string` | - | Unique node identifier (required) |
+| x | `number` | - | X position in canvas coordinates (required) |
+| y | `number` | - | Y position in canvas coordinates (required) |
+| draggable | `boolean` | - | Allow drag-to-move |
+| onPositionChange | `(x: number, y: number) => void` | - | Callback when dragged to a new position |
+| className | `string` | - | Additional CSS classes |
+| style | `CSSProperties` | - | Inline styles |
+
+### Canvas.Edge
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| from | `string` | - | Source node id (required) |
+| to | `string` | - | Target node id (required) |
+| fromAnchor | `EdgeAnchor` | - | Anchor point on source: `"top"`, `"bottom"`, `"left"`, `"right"`, `"center"`, `"auto"` |
+| toAnchor | `EdgeAnchor` | - | Anchor point on target |
+| curve | `"bezier" \| "step" \| "straight"` | - | Path interpolation |
+| color | `string` | - | Stroke color |
+| strokeWidth | `number` | - | Stroke width |
+| dashed | `boolean` | - | Dashed line |
+| animated | `boolean` | - | Animated dash pattern |
+| label | `ReactNode` | - | Label at the midpoint |
+| markerStart | `string` | - | SVG marker id for start (e.g. `"canvas-arrow"`, `"canvas-circle"`, `"canvas-diamond"`) |
+| markerEnd | `string` | - | SVG marker id for end |
+| className | `string` | - | Additional CSS classes |
+
+### Canvas.Controls
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| showZoomIn | `boolean` | - | Show zoom-in button |
+| showZoomOut | `boolean` | - | Show zoom-out button |
+| showReset | `boolean` | - | Show reset-viewport button |
+| showFitAll | `boolean` | - | Show fit-all button |
+| className | `string` | - | Additional CSS classes |
+
+### Canvas.Minimap
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| width | `number` | - | Minimap width in px |
+| height | `number` | - | Minimap height in px |
+| className | `string` | - | Additional CSS classes |
+
+### ViewportState
+
+```ts
+{ panX: number; panY: number; zoom: number }
+```
+
+## Built-in SVG Markers
+
+The Canvas includes predefined SVG markers for edge endpoints: `"canvas-arrow"`, `"canvas-circle"`, `"canvas-diamond"`, `"canvas-one"`, `"canvas-crow-foot"`.

package/docs/Card.md

@@ -0,0 +1,68 @@
+# Card
+
+A container component with optional header, body, and footer sections. Uses `Object.assign` to expose compound sub-components.
+
+## Import
+
+```tsx
+import { Card } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Card>
+  <Card.Body>Content goes here</Card.Body>
+</Card>
+```
+
+## Card Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| variant | `"outlined" \| "elevated" \| "flat"` | `"outlined"` | Visual variant |
+| padding | `"none" \| "sm" \| "md" \| "lg"` | `"md"` | Padding applied to child sections |
+
+Also extends all native `<div>` HTML attributes.
+
+## Sub-Components
+
+### Card.Header
+
+Renders a section with a bottom border. Accepts all `<div>` HTML attributes.
+
+### Card.Body
+
+Renders a plain content section. Accepts all `<div>` HTML attributes.
+
+### Card.Footer
+
+Renders a section with a top border. Accepts all `<div>` HTML attributes.
+
+## Examples
+
+### Full card with sections
+
+```tsx
+<Card variant="elevated" padding="lg">
+  <Card.Header>
+    <h3 className="font-semibold">Settings</h3>
+  </Card.Header>
+  <Card.Body>
+    <p>Configure your preferences below.</p>
+  </Card.Body>
+  <Card.Footer>
+    <button>Save</button>
+  </Card.Footer>
+</Card>
+```
+
+### Flat card without header
+
+```tsx
+<Card variant="flat">
+  <Card.Body>
+    <p>A simple flat card.</p>
+  </Card.Body>
+</Card>
+```

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 |