@particle-academy/react-fancy 1.7.1 → 1.7.2

package/docs/Accordion.md

@@ -0,0 +1,78 @@
+# Accordion
+
+A collapsible content panel supporting single or multiple open items simultaneously.
+
+## Import
+
+```tsx
+import { Accordion } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Accordion>
+  <Accordion.Item value="item-1">
+    <Accordion.Trigger>What is React Fancy?</Accordion.Trigger>
+    <Accordion.Content>
+      A headless-ish UI component library for React.
+    </Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="item-2">
+    <Accordion.Trigger>Is it accessible?</Accordion.Trigger>
+    <Accordion.Content>
+      Yes, it follows WAI-ARIA patterns.
+    </Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```
+
+## Props
+
+### Accordion (root)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| type | `"single" \| "multiple"` | `"single"` | Whether one or multiple items can be open |
+| defaultOpen | `string[]` | `[]` | Values of items that start open |
+| className | `string` | - | Additional CSS classes |
+
+### Accordion.Item
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | `string` | - | Unique item identifier (required) |
+| className | `string` | - | Additional CSS classes |
+
+### Accordion.Trigger
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Clickable header content |
+| className | `string` | - | Additional CSS classes |
+
+### Accordion.Content
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Collapsible content |
+| className | `string` | - | Additional CSS classes |
+
+## Multiple Open Items
+
+```tsx
+<Accordion type="multiple" defaultOpen={["faq-1", "faq-3"]}>
+  <Accordion.Item value="faq-1">
+    <Accordion.Trigger>First question</Accordion.Trigger>
+    <Accordion.Content>First answer</Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="faq-2">
+    <Accordion.Trigger>Second question</Accordion.Trigger>
+    <Accordion.Content>Second answer</Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="faq-3">
+    <Accordion.Trigger>Third question</Accordion.Trigger>
+    <Accordion.Content>Third answer</Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```

package/docs/Action.md

@@ -0,0 +1,76 @@
+# Action
+
+A versatile button component with support for icons, emojis, avatars, badges, loading states, and color variants.
+
+## Import
+
+```tsx
+import { Action } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Action>Click me</Action>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| variant | `"default" \| "circle"` | `"default"` | Shape variant |
+| color | `ActionColor` | - | Standalone color (overrides state colors). One of: `"blue"`, `"emerald"`, `"amber"`, `"red"`, `"violet"`, `"indigo"`, `"sky"`, `"rose"`, `"orange"`, `"zinc"` |
+| size | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Button size |
+| active | `boolean` | - | Active state (blue highlight) |
+| checked | `boolean` | - | Checked state (emerald highlight) |
+| warn | `boolean` | - | Warning state (amber highlight) |
+| alert | `boolean` | - | Pulsing animation on the entire button |
+| icon | `string` | - | Leading icon slug resolved via the Icon component |
+| iconTrailing | `string` | - | Trailing icon slug |
+| iconPlace | `string` | `"left"` | Icon placement. Supports: `"left"`, `"right"`, `"top"`, `"bottom"`, and compound positions like `"top left"`, `"bottom right"` |
+| alertIcon | `string` | - | Pulsing alert icon slug |
+| alertIconTrailing | `boolean` | - | Position alert icon on trailing side |
+| emoji | `string` | - | Leading emoji slug |
+| emojiTrailing | `string` | - | Trailing emoji slug |
+| avatar | `string` | - | Avatar image URL |
+| avatarTrailing | `boolean` | - | Position avatar on trailing side |
+| badge | `string` | - | Badge text |
+| badgeTrailing | `boolean` | - | Position badge on trailing side |
+| sort | `string` | `"eiab"` | Sort order of decorative elements: `e`=emoji, `i`=icon, `a`=avatar, `b`=badge |
+| loading | `boolean` | `false` | Show loading spinner (disables the button) |
+| disabled | `boolean` | - | Disable the button |
+| href | `string` | - | Render as an anchor tag instead of a button |
+
+Also extends all native `<button>` HTML attributes (except `color`).
+
+## Examples
+
+### Icon button with color
+
+```tsx
+<Action icon="pencil" color="blue" size="lg">
+  Edit
+</Action>
+```
+
+### Circle icon button
+
+```tsx
+<Action variant="circle" icon="plus" color="emerald" />
+```
+
+### Loading state with badge
+
+```tsx
+<Action loading badge="3" badgeTrailing>
+  Messages
+</Action>
+```
+
+### Link button with trailing icon
+
+```tsx
+<Action href="/docs" iconTrailing="arrow-right">
+  Read docs
+</Action>
+```

package/docs/Autocomplete.md

@@ -0,0 +1,74 @@
+# Autocomplete
+
+Text input with a filterable dropdown of suggestions, supporting async search and keyboard navigation.
+
+## Import
+
+```tsx
+import { Autocomplete } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Autocomplete
+  options={[
+    { value: "react", label: "React" },
+    { value: "vue", label: "Vue" },
+    { value: "angular", label: "Angular" },
+  ]}
+  placeholder="Search frameworks..."
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `options` | `AutocompleteOption[]` | **required** | `{ value: string; label: string; disabled?: boolean }` |
+| `value` | `string` | - | Controlled selected value |
+| `defaultValue` | `string` | `""` | Default value (uncontrolled) |
+| `onChange` | `(value: string) => void` | - | Callback when an option is selected |
+| `onSearch` | `(query: string) => void` | - | Callback fired as the user types (for async fetching) |
+| `placeholder` | `string` | - | Input placeholder |
+| `loading` | `boolean` | `false` | Show a loading indicator in the dropdown |
+| `emptyMessage` | `ReactNode` | `"No results found."` | Message when no options match |
+| `disabled` | `boolean` | `false` | Disables the input |
+| `className` | `string` | - | Additional CSS classes |
+
+Matching text in dropdown options is automatically highlighted in bold.
+
+## Examples
+
+### Async search
+
+```tsx
+const [options, setOptions] = useState([]);
+const [loading, setLoading] = useState(false);
+
+<Autocomplete
+  options={options}
+  loading={loading}
+  placeholder="Search users..."
+  onSearch={async (query) => {
+    setLoading(true);
+    const results = await fetchUsers(query);
+    setOptions(results.map((u) => ({ value: u.id, label: u.name })));
+    setLoading(false);
+  }}
+  onChange={(userId) => console.log("Selected:", userId)}
+/>
+```
+
+### Controlled
+
+```tsx
+const [city, setCity] = useState("");
+
+<Autocomplete
+  options={cities}
+  value={city}
+  onChange={setCity}
+  placeholder="Pick a city"
+/>
+```

package/docs/Avatar.md

@@ -0,0 +1,40 @@
+# Avatar
+
+A circular avatar component with image, fallback initials, and optional online status indicator.
+
+## Import
+
+```tsx
+import { Avatar } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Avatar src="/photo.jpg" alt="Jane Doe" />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| src | `string` | - | Image source URL |
+| alt | `string` | `""` | Alt text for the image |
+| fallback | `string` | - | Fallback initials when no image is provided |
+| size | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Avatar size |
+| status | `"online" \| "offline" \| "busy" \| "away"` | - | Online status indicator dot |
+| className | `string` | - | Additional CSS classes |
+
+## Examples
+
+### With fallback initials and status
+
+```tsx
+<Avatar fallback="JD" size="lg" status="online" />
+```
+
+### Small avatar with image
+
+```tsx
+<Avatar src="/avatar.png" alt="User" size="sm" status="busy" />
+```

package/docs/Badge.md

@@ -0,0 +1,42 @@
+# Badge
+
+An inline badge/tag component with color, variant, and optional dot indicator.
+
+## Import
+
+```tsx
+import { Badge } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Badge>Default</Badge>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| color | `"zinc" \| "red" \| "blue" \| "green" \| "amber" \| "violet" \| "rose"` | `"zinc"` | Badge color |
+| variant | `"solid" \| "outline" \| "soft"` | `"soft"` | Visual variant |
+| size | `"sm" \| "md" \| "lg"` | `"md"` | Badge size |
+| dot | `boolean` | `false` | Show a small dot indicator before text |
+
+Also extends all native `<span>` HTML attributes.
+
+## Examples
+
+### Status badge with dot
+
+```tsx
+<Badge color="green" dot>Active</Badge>
+```
+
+### Solid colored badge
+
+```tsx
+<Badge color="red" variant="solid" size="sm">
+  3 errors
+</Badge>
+```

package/docs/Brand.md

@@ -0,0 +1,44 @@
+# Brand
+
+A branding component that displays a logo, name, and tagline side by side.
+
+## Import
+
+```tsx
+import { Brand } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Brand name="Acme Inc." />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| logo | `ReactNode` | - | Logo element (image, icon, SVG, etc.) |
+| name | `string` | - | Brand name text |
+| tagline | `string` | - | Tagline or subtitle text |
+| size | `"sm" \| "md" \| "lg"` | `"md"` | Overall size |
+| className | `string` | - | Additional CSS classes |
+
+## Examples
+
+### Full brand with logo
+
+```tsx
+<Brand
+  logo={<img src="/logo.svg" alt="" className="h-8 w-8" />}
+  name="Acme Inc."
+  tagline="Build amazing things"
+  size="lg"
+/>
+```
+
+### Name only
+
+```tsx
+<Brand name="My App" size="sm" />
+```

package/docs/Breadcrumbs.md

@@ -0,0 +1,51 @@
+# Breadcrumbs
+
+A navigation trail with configurable separators, a shrinkable mode that collapses intermediate items to "...", and an automatic mobile dropdown.
+
+## Import
+
+```tsx
+import { Breadcrumbs } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Breadcrumbs>
+  <Breadcrumbs.Item href="/">Home</Breadcrumbs.Item>
+  <Breadcrumbs.Item href="/products">Products</Breadcrumbs.Item>
+  <Breadcrumbs.Item active>Widget</Breadcrumbs.Item>
+</Breadcrumbs>
+```
+
+## Props
+
+### Breadcrumbs (root)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| separator | `ReactNode` | `<ChevronRight />` | Custom separator element between items |
+| shrink | `boolean` | - | Collapse intermediate items to "..." (expand on hover/click) |
+| className | `string` | - | Additional CSS classes |
+
+### Breadcrumbs.Item
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Item label |
+| href | `string` | - | Link URL (renders an anchor when provided) |
+| active | `boolean` | - | Mark as the current page (no link) |
+| className | `string` | - | Additional CSS classes |
+
+## Shrinkable Breadcrumbs
+
+When `shrink` is enabled, only the "..." button and the last item are shown. Hovering or clicking "..." expands the full trail.
+
+```tsx
+<Breadcrumbs shrink>
+  <Breadcrumbs.Item href="/">Home</Breadcrumbs.Item>
+  <Breadcrumbs.Item href="/docs">Docs</Breadcrumbs.Item>
+  <Breadcrumbs.Item href="/docs/components">Components</Breadcrumbs.Item>
+  <Breadcrumbs.Item active>Breadcrumbs</Breadcrumbs.Item>
+</Breadcrumbs>
+```

package/docs/Calendar.md

@@ -0,0 +1,72 @@
+# Calendar
+
+Inline calendar widget supporting single date, multiple date, and date range selection.
+
+## Import
+
+```tsx
+import { Calendar } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Calendar onChange={(date) => console.log(date)} />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `mode` | `"single" \| "range" \| "multiple"` | `"single"` | Selection mode |
+| `value` | `Date \| Date[] \| DateRange \| null` | - | Controlled value (type depends on mode) |
+| `onChange` | `(value: Date \| Date[] \| DateRange \| null) => void` | - | Callback when selection changes |
+| `minDate` | `Date` | - | Earliest selectable date |
+| `maxDate` | `Date` | - | Latest selectable date |
+| `disabledDates` | `Date[]` | `[]` | Specific dates to disable |
+| `className` | `string` | - | Additional CSS classes |
+
+### DateRange type
+
+```ts
+interface DateRange {
+  start: Date | null;
+  end: Date | null;
+}
+```
+
+**Behavior:**
+- Month navigation via chevron buttons.
+- Today is visually emphasized with bold text.
+- In `"range"` mode, hovering previews the range highlight before the second click.
+- Out-of-month days are dimmed but still clickable.
+
+## Examples
+
+### Date range selection
+
+```tsx
+const [range, setRange] = useState<DateRange>({ start: null, end: null });
+
+<Calendar
+  mode="range"
+  value={range}
+  onChange={setRange}
+  minDate={new Date()}
+/>
+```
+
+### Multiple dates with constraints
+
+```tsx
+const [dates, setDates] = useState<Date[]>([]);
+
+<Calendar
+  mode="multiple"
+  value={dates}
+  onChange={setDates}
+  minDate={new Date(2024, 0, 1)}
+  maxDate={new Date(2024, 11, 31)}
+  disabledDates={[new Date(2024, 6, 4)]}
+/>
+```

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