@particle-academy/react-fancy 1.7.0 → 1.7.2

package/docs/Skeleton.md

@@ -0,0 +1,44 @@
+# Skeleton
+
+An animated placeholder component for loading states, available as rectangle, circle, or text line shapes.
+
+## Import
+
+```tsx
+import { Skeleton } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Skeleton width={200} height={20} />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| shape | `"rect" \| "circle" \| "text"` | `"rect"` | Shape of the skeleton placeholder |
+| width | `string \| number` | - | Custom width (CSS value or number in px) |
+| height | `string \| number` | - | Custom height (CSS value or number in px) |
+| className | `string` | - | Additional CSS classes |
+
+Shape defaults: `"rect"` renders with rounded-lg corners; `"circle"` renders as a rounded-full with 1:1 aspect ratio; `"text"` renders as a full-width line at 16px height.
+
+## Examples
+
+### Loading card placeholder
+
+```tsx
+<div className="space-y-3">
+  <Skeleton shape="circle" width={48} height={48} />
+  <Skeleton shape="text" />
+  <Skeleton shape="text" width="60%" />
+</div>
+```
+
+### Custom rectangle
+
+```tsx
+<Skeleton width={300} height={180} />
+```

package/docs/Slider.md

@@ -0,0 +1,75 @@
+# Slider
+
+Range slider supporting single-value and dual-thumb range modes, with optional marks and value display.
+
+## Import
+
+```tsx
+import { Slider } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Slider label="Volume" defaultValue={50} showValue />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `min` | `number` | `0` | Minimum value |
+| `max` | `number` | `100` | Maximum value |
+| `step` | `number` | `1` | Step increment |
+| `showValue` | `boolean` | `false` | Display current value beside the slider |
+| `marks` | `{ value: number; label?: string }[]` | - | Tick marks below the track |
+| `prefix` | `ReactNode` | - | Prefix before the displayed value (e.g. `"$"`) |
+| `suffix` | `ReactNode` | - | Suffix after the displayed value (e.g. `"%"`) |
+| `range` | `boolean` | `false` | Enable dual-thumb range mode |
+| `value` | `number` (single) / `[number, number]` (range) | - | Controlled value |
+| `defaultValue` | `number` / `[number, number]` | `min` / `[min, max]` | 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"` | Track thickness |
+| `dirty` | `boolean` | `false` | Amber ring |
+| `disabled` | `boolean` | `false` | Disables the slider |
+| `className` | `string` | - | Additional CSS classes |
+
+## Examples
+
+### With marks and suffix
+
+```tsx
+<Slider
+  label="Temperature"
+  min={0}
+  max={100}
+  step={10}
+  showValue
+  suffix="°C"
+  marks={[
+    { value: 0, label: "Cold" },
+    { value: 50, label: "Warm" },
+    { value: 100, label: "Hot" },
+  ]}
+/>
+```
+
+### Range slider
+
+```tsx
+const [range, setRange] = useState<[number, number]>([20, 80]);
+
+<Slider
+  label="Price range"
+  range
+  min={0}
+  max={200}
+  prefix="$"
+  showValue
+  value={range}
+  onValueChange={setRange}
+/>
+```

package/docs/Switch.md

@@ -0,0 +1,55 @@
+# Switch
+
+Toggle switch for boolean on/off states with configurable color and optional label.
+
+## Import
+
+```tsx
+import { Switch } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Switch label="Enable notifications" />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `checked` | `boolean` | - | Controlled checked state |
+| `defaultChecked` | `boolean` | `false` | Initial checked state (uncontrolled) |
+| `onCheckedChange` | `(checked: boolean) => void` | - | Callback when toggled |
+| `color` | `Color` | `"blue"` | Track color when checked. Any Tailwind color: `"zinc"`, `"red"`, `"green"`, `"blue"`, `"purple"`, etc. |
+| `label` | `string` | - | Label text next to the switch |
+| `description` | `string` | - | Helper text below the label |
+| `error` | `string` | - | Error message |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Switch size |
+| `dirty` | `boolean` | `false` | Amber ring |
+| `required` | `boolean` | `false` | Red asterisk on label |
+| `disabled` | `boolean` | `false` | Disables the switch |
+| `name` | `string` | - | Form field name (renders a hidden input with value `"1"` or `"0"`) |
+| `className` | `string` | - | Additional CSS classes |
+
+## Examples
+
+### Controlled with color
+
+```tsx
+const [darkMode, setDarkMode] = useState(false);
+
+<Switch
+  label="Dark mode"
+  description="Toggle the application theme"
+  color="violet"
+  checked={darkMode}
+  onCheckedChange={setDarkMode}
+/>
+```
+
+### In a form
+
+```tsx
+<Switch name="marketing_emails" label="Receive marketing emails" defaultChecked />
+```

package/docs/Table.md

@@ -0,0 +1,133 @@
+# Table
+
+A data table with sorting, pagination, search, expandable row trays, and a compound sub-component API.
+
+## Import
+
+```tsx
+import { Table } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Table>
+  <Table.Search placeholder="Filter users..." />
+  <Table.Head>
+    <Table.Row>
+      <Table.Column label="Name" sortKey="name" />
+      <Table.Column label="Email" sortKey="email" />
+      <Table.Column label="Role" />
+    </Table.Row>
+  </Table.Head>
+  <Table.Body>
+    {users.map((user) => (
+      <Table.Row key={user.id}>
+        <Table.Cell>{user.name}</Table.Cell>
+        <Table.Cell>{user.email}</Table.Cell>
+        <Table.Cell>{user.role}</Table.Cell>
+      </Table.Row>
+    ))}
+  </Table.Body>
+  <Table.Pagination total={users.length} pageSize={10} />
+</Table>
+```
+
+## Props
+
+### Table (root)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Table sub-components |
+| className | `string` | - | Additional CSS classes |
+
+### Table.Head
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Header row(s) |
+| className | `string` | - | Additional CSS classes |
+
+### Table.Body
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Data rows |
+| className | `string` | - | Additional CSS classes |
+
+### Table.Row
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Cells |
+| onClick | `() => void` | - | Row click handler |
+| tray | `ReactNode` | - | Expandable tray content |
+| trayTriggerPosition | `"start" \| "end" \| "hidden"` | - | Position of the expand/collapse trigger |
+| expanded | `boolean` | - | Controlled expanded state |
+| defaultExpanded | `boolean` | - | Default expanded state (uncontrolled) |
+| onExpandedChange | `(expanded: boolean) => void` | - | Callback when expanded state changes |
+| className | `string` | - | Additional CSS classes |
+
+### Table.Cell
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Cell content |
+| header | `boolean` | - | Render as `<th>` instead of `<td>` |
+| className | `string` | - | Additional CSS classes |
+
+### Table.Column
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| label | `string` | - | Column header text (required) |
+| sortKey | `string` | - | Enable sorting on this key |
+| className | `string` | - | Additional CSS classes |
+
+### Table.Pagination
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| total | `number` | - | Total number of rows (required) |
+| pageSize | `number` | - | Rows per page |
+| className | `string` | - | Additional CSS classes |
+
+### Table.Search
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| placeholder | `string` | - | Input placeholder |
+| className | `string` | - | Additional CSS classes |
+
+### Table.Tray / Table.RowTray
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Tray content |
+| className | `string` | - | Additional CSS classes |
+
+## Expandable Row Tray
+
+```tsx
+<Table>
+  <Table.Head>
+    <Table.Row>
+      <Table.Column label="Order" />
+      <Table.Column label="Status" />
+    </Table.Row>
+  </Table.Head>
+  <Table.Body>
+    {orders.map((order) => (
+      <Table.Row
+        key={order.id}
+        tray={<div className="p-4">Order details for {order.id}</div>}
+        trayTriggerPosition="end"
+      >
+        <Table.Cell>{order.id}</Table.Cell>
+        <Table.Cell>{order.status}</Table.Cell>
+      </Table.Row>
+    ))}
+  </Table.Body>
+</Table>
+```

package/docs/Tabs.md

@@ -0,0 +1,85 @@
+# Tabs
+
+A tabbed interface with three visual variants, controlled and uncontrolled modes, and linked tab-panel pairs.
+
+## Import
+
+```tsx
+import { Tabs } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Tabs defaultTab="general">
+  <Tabs.List>
+    <Tabs.Tab value="general">General</Tabs.Tab>
+    <Tabs.Tab value="security">Security</Tabs.Tab>
+    <Tabs.Tab value="notifications">Notifications</Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panels>
+    <Tabs.Panel value="general">General settings content</Tabs.Panel>
+    <Tabs.Panel value="security">Security settings content</Tabs.Panel>
+    <Tabs.Panel value="notifications">Notification preferences</Tabs.Panel>
+  </Tabs.Panels>
+</Tabs>
+```
+
+## Props
+
+### Tabs (root)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| defaultTab | `string` | `""` | Initially active tab value (uncontrolled) |
+| activeTab | `string` | - | Controlled active tab value |
+| onTabChange | `(tab: string) => void` | - | Callback when the active tab changes |
+| variant | `"underline" \| "pills" \| "boxed"` | `"underline"` | Visual style |
+| className | `string` | - | Additional CSS classes |
+
+### Tabs.List
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Tab elements |
+| className | `string` | - | Additional CSS classes |
+
+### Tabs.Tab
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | `string` | - | Unique tab identifier (required) |
+| disabled | `boolean` | - | Disable this tab |
+| className | `string` | - | Additional CSS classes |
+
+### Tabs.Panels
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Panel elements |
+| className | `string` | - | Additional CSS classes |
+
+### Tabs.Panel
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | `string` | - | Tab value this panel corresponds to (required) |
+| className | `string` | - | Additional CSS classes |
+
+## Controlled with Pills Variant
+
+```tsx
+const [tab, setTab] = useState("overview");
+
+<Tabs activeTab={tab} onTabChange={setTab} variant="pills">
+  <Tabs.List>
+    <Tabs.Tab value="overview">Overview</Tabs.Tab>
+    <Tabs.Tab value="analytics">Analytics</Tabs.Tab>
+    <Tabs.Tab value="reports" disabled>Reports</Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panels>
+    <Tabs.Panel value="overview">Overview content</Tabs.Panel>
+    <Tabs.Panel value="analytics">Analytics content</Tabs.Panel>
+  </Tabs.Panels>
+</Tabs>
+```

package/docs/Text.md

@@ -0,0 +1,44 @@
+# Text
+
+A text component for rendering paragraphs, spans, or labels with preset sizes, weights, and colors.
+
+## Import
+
+```tsx
+import { Text } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Text>Hello, world!</Text>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| as | `"p" \| "span" \| "div" \| "label"` | `"p"` | Which element to render |
+| size | `"xs" \| "sm" \| "md" \| "lg"` | `"md"` | Text size |
+| weight | `"normal" \| "medium" \| "semibold" \| "bold"` | `"normal"` | Font weight |
+| color | `"default" \| "muted" \| "accent" \| "danger" \| "success"` | `"default"` | Text color preset |
+
+Also extends all native HTML attributes for the rendered element.
+
+## Examples
+
+### Muted helper text
+
+```tsx
+<Text size="sm" color="muted">
+  This action cannot be undone.
+</Text>
+```
+
+### Inline accent text
+
+```tsx
+<Text as="span" color="accent" weight="semibold">
+  New
+</Text>
+```

package/docs/Textarea.md

@@ -0,0 +1,62 @@
+# Textarea
+
+Multi-line text input with optional auto-resize, label, error, and prefix/suffix support.
+
+## Import
+
+```tsx
+import { Textarea } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Textarea label="Bio" placeholder="Tell us about yourself..." />
+```
+
+## Props
+
+Extends all native `<textarea>` attributes (except `size`, `prefix`).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Controls text size and padding |
+| `autoResize` | `boolean` | `false` | Auto-grows height to fit content |
+| `minRows` | `number` | `3` | Minimum visible rows |
+| `maxRows` | `number` | - | Maximum rows before scrolling (only applies with `autoResize`) |
+| `label` | `string` | - | Wraps textarea in a `Field` with this label |
+| `description` | `string` | - | Helper text below the textarea |
+| `error` | `string` | - | Error message (red text and border) |
+| `required` | `boolean` | `false` | Red asterisk on label |
+| `dirty` | `boolean` | `false` | Amber ring to indicate unsaved changes |
+| `disabled` | `boolean` | `false` | Disables the textarea |
+| `prefix` | `ReactNode` | - | Affix rendered before the textarea (always outside) |
+| `suffix` | `ReactNode` | - | Affix rendered after the textarea (always outside) |
+| `onValueChange` | `(value: string) => void` | - | Convenience callback with the string value directly |
+| `className` | `string` | - | Additional CSS classes on the `<textarea>` |
+
+## Examples
+
+### Auto-resize with max height
+
+```tsx
+<Textarea
+  label="Message"
+  autoResize
+  minRows={2}
+  maxRows={10}
+  placeholder="Type your message..."
+/>
+```
+
+### Controlled
+
+```tsx
+const [notes, setNotes] = useState("");
+
+<Textarea
+  label="Notes"
+  value={notes}
+  onValueChange={setNotes}
+/>
+```

package/docs/TimePicker.md

@@ -0,0 +1,45 @@
+# TimePicker
+
+Spinner-style time picker with hour/minute columns and optional 12h/24h format.
+
+## Import
+
+```tsx
+import { TimePicker } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<TimePicker onChange={(time) => console.log(time)} />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | - | Controlled value in `"HH:MM"` 24h format |
+| `defaultValue` | `string` | `"12:00"` | Default time (uncontrolled) |
+| `onChange` | `(value: string) => void` | - | Callback with time string in `"HH:MM"` 24h format |
+| `format` | `"12h" \| "24h"` | `"12h"` | Display format. `"12h"` shows an AM/PM toggle button. |
+| `minuteStep` | `number` | `1` | Minute increment per click |
+| `disabled` | `boolean` | `false` | Disables all controls |
+| `className` | `string` | - | Additional CSS classes |
+
+**Note:** Regardless of display format, the `value` and `onChange` always use 24-hour `"HH:MM"` strings.
+
+## Examples
+
+### 24-hour format with 15-minute steps
+
+```tsx
+<TimePicker format="24h" minuteStep={15} defaultValue="09:00" />
+```
+
+### Controlled
+
+```tsx
+const [time, setTime] = useState("14:30");
+
+<TimePicker value={time} onChange={setTime} />
+```

package/docs/Timeline.md

@@ -0,0 +1,118 @@
+# Timeline
+
+A timeline component supporting stacked, alternating, and horizontal layouts. Can be used data-driven (via the `events` prop) or as a compound component with `Timeline.Item` and `Timeline.Block`.
+
+## Import
+
+```tsx
+import { Timeline } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Timeline>
+  <Timeline.Item date="Jan 2024">
+    <h3>Project started</h3>
+  </Timeline.Item>
+  <Timeline.Item date="Mar 2024">
+    <h3>First release</h3>
+  </Timeline.Item>
+</Timeline>
+```
+
+## Timeline Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Compound children (`Timeline.Item` or `Timeline.Block`) |
+| variant | `"stacked" \| "alternating" \| "horizontal"` | `"stacked"` | Layout variant |
+| events | `TimelineEvent[]` | - | Data-driven events (alternative to children) |
+| heading | `ReactNode` | - | Optional heading above the timeline |
+| description | `ReactNode` | - | Optional description below the heading |
+| animated | `boolean` | `true` | Enable scroll-reveal animation |
+| className | `string` | - | Additional CSS classes |
+
+## Timeline.Item Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Item content |
+| icon | `ReactNode` | - | Custom icon for the dot |
+| emoji | `string` | - | Emoji character for the dot |
+| date | `string` | - | Date label displayed above the content |
+| color | `Color` | `"zinc"` | Dot accent color (any Tailwind color name) |
+| active | `boolean` | `false` | Whether this item is the active/current step |
+| className | `string` | - | Additional CSS classes |
+
+## Timeline.Block Props
+
+A convenience wrapper around `Timeline.Item` that renders content inside a bordered card.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| heading | `ReactNode` | - | Block heading |
+| children | `ReactNode` | **required** | Block body content |
+| icon | `ReactNode` | - | Icon for the dot |
+| emoji | `string` | - | Emoji for the dot |
+| color | `Color` | `"zinc"` | Dot/icon color |
+| active | `boolean` | `false` | Whether this block is active (adds ring highlight) |
+| className | `string` | - | Additional CSS classes |
+
+## TimelineEvent (data-driven)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| title | `string` | yes | Event heading |
+| description | `string` | no | Body text |
+| date | `string` | no | Date string |
+| emoji | `string` | no | Emoji for the dot |
+| icon | `ReactNode` | no | Custom icon for the dot |
+| color | `Color` | no | Accent color |
+
+## Examples
+
+### Data-driven timeline
+
+```tsx
+<Timeline
+  heading="Project History"
+  events={[
+    { date: "Jan 2024", title: "Kickoff", description: "Project started", color: "blue" },
+    { date: "Mar 2024", title: "Beta", description: "First beta release", emoji: "🚀" },
+    { date: "Jun 2024", title: "Launch", description: "Public launch", color: "green" },
+  ]}
+/>
+```
+
+### Alternating layout with blocks
+
+```tsx
+<Timeline variant="alternating">
+  <Timeline.Block heading="Design" color="violet" emoji="🎨">
+    Completed wireframes and mockups.
+  </Timeline.Block>
+  <Timeline.Block heading="Development" color="blue" active>
+    Building core features.
+  </Timeline.Block>
+  <Timeline.Block heading="Launch" color="green">
+    Planned for Q3.
+  </Timeline.Block>
+</Timeline>
+```
+
+### Horizontal timeline
+
+```tsx
+<Timeline variant="horizontal">
+  <Timeline.Item date="Step 1" color="blue">
+    <h3 className="font-semibold">Sign up</h3>
+  </Timeline.Item>
+  <Timeline.Item date="Step 2" color="blue">
+    <h3 className="font-semibold">Configure</h3>
+  </Timeline.Item>
+  <Timeline.Item date="Step 3" color="green" active>
+    <h3 className="font-semibold">Go live</h3>
+  </Timeline.Item>
+</Timeline>
+```