npm - @particle-academy/react-fancy - Versions diffs - 1.7.1 → 1.7.2 - Mend

@particle-academy/react-fancy 1.7.1 → 1.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (61) hide show

package/docs/Popover.md ADDED Viewed

@@ -0,0 +1,82 @@
+# Popover
+A floating content panel anchored to a trigger element. Supports click and hover activation with configurable placement.
+## Import
+```tsx
+import { Popover } from "@particle-academy/react-fancy";
+```
+## Basic Usage
+```tsx
+<Popover>
+  <Popover.Trigger>
+    <button>Open popover</button>
+  </Popover.Trigger>
+  <Popover.Content>
+    <p>Popover content here</p>
+  </Popover.Content>
+</Popover>
+```
+## Props
+### Popover (root)
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| open | `boolean` | - | Controlled open state |
+| defaultOpen | `boolean` | `false` | Default open state (uncontrolled) |
+| onOpenChange | `(open: boolean) => void` | - | Callback when open state changes |
+| placement | `Placement` | `"bottom"` | Position relative to trigger. One of: `"top"`, `"bottom"`, `"left"`, `"right"`, `"top-start"`, `"top-end"`, `"bottom-start"`, `"bottom-end"` |
+| offset | `number` | `8` | Pixel offset from the trigger |
+| hover | `boolean` | `false` | Open on hover instead of click |
+| hoverDelay | `number` | `200` | Delay in ms before opening on hover |
+| hoverCloseDelay | `number` | `300` | Delay in ms before closing after hover leaves |
+### Popover.Trigger
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Trigger element |
+| className | `string` | - | Additional CSS classes |
+### Popover.Content
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Content to display |
+| className | `string` | - | Additional CSS classes |
+## Hover Mode
+The `hover` prop switches from click-to-toggle to hover-to-open behavior. When enabled, the popover opens after `hoverDelay` ms and closes after `hoverCloseDelay` ms once the cursor leaves both the trigger and content. Moving from the trigger into the content keeps the popover open.
+```tsx
+<Popover hover hoverDelay={100} hoverCloseDelay={400}>
+  <Popover.Trigger>
+    <button>Hover me</button>
+  </Popover.Trigger>
+  <Popover.Content>
+    <p>Tooltip-like popover</p>
+  </Popover.Content>
+</Popover>
+```
+## Controlled Example
+```tsx
+const [open, setOpen] = useState(false);
+<Popover open={open} onOpenChange={setOpen} placement="right">
+  <Popover.Trigger>
+    <button>Info</button>
+  </Popover.Trigger>
+  <Popover.Content className="p-4 w-64">
+    <h3>Details</h3>
+    <p>Some additional information.</p>
+  </Popover.Content>
+</Popover>
+```

package/docs/Portal.md ADDED Viewed

@@ -0,0 +1,40 @@
+# Portal
+Renders children into a DOM node outside the React component tree using `createPortal`, with automatic dark mode propagation.
+## Import
+```tsx
+import { Portal } from "@particle-academy/react-fancy";
+```
+## Basic Usage
+```tsx
+<Portal>
+  <div className="fixed inset-0 z-50 bg-black/50">Modal overlay</div>
+</Portal>
+```
+## Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | **required** | Content to render in the portal |
+| container | `HTMLElement` | `document.body` | Target DOM element to portal into |
+Portal wraps children in a `<div style="display: contents">` that automatically syncs the `dark` class from `<html>`, ensuring Tailwind `dark:` utilities work correctly inside portals.
+Returns `null` during SSR (when `document` is undefined).
+## Examples
+### Custom container
+```tsx
+const container = document.getElementById("modal-root")!;
+<Portal container={container}>
+  <div>Rendered inside #modal-root</div>
+</Portal>
+```

package/docs/Profile.md ADDED Viewed

@@ -0,0 +1,52 @@
+# Profile
+A profile display component that combines an Avatar with a name and optional subtitle.
+## Import
+```tsx
+import { Profile } from "@particle-academy/react-fancy";
+```
+## Basic Usage
+```tsx
+<Profile name="Jane Doe" />
+```
+## Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| src | `string` | - | Avatar image URL |
+| alt | `string` | - | Avatar alt text (falls back to `name`) |
+| fallback | `string` | - | Fallback initials for the avatar |
+| name | `string` | **required** | Display name |
+| subtitle | `string` | - | Secondary text (role, email, etc.) |
+| size | `"sm" \| "md" \| "lg"` | `"md"` | Overall size |
+| status | `"online" \| "offline" \| "busy" \| "away"` | - | Status indicator on the avatar |
+| className | `string` | - | Additional CSS classes |
+## Examples
+### With avatar and status
+```tsx
+<Profile
+  src="/photo.jpg"
+  name="Jane Doe"
+  subtitle="Product Designer"
+  status="online"
+/>
+```
+### Fallback initials
+```tsx
+<Profile
+  fallback="AB"
+  name="Alice Brown"
+  subtitle="alice@example.com"
+  size="lg"
+/>
+```

package/docs/Progress.md ADDED Viewed

@@ -0,0 +1,42 @@
+# Progress
+A progress indicator available as a horizontal bar or circular ring, with optional percentage display.
+## Import
+```tsx
+import { Progress } from "@particle-academy/react-fancy";
+```
+## Basic Usage
+```tsx
+<Progress value={60} />
+```
+## Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | `number` | `0` | Current progress value |
+| max | `number` | `100` | Maximum value |
+| variant | `"bar" \| "circular"` | `"bar"` | Visual variant |
+| size | `"sm" \| "md" \| "lg"` | `"md"` | Component size |
+| color | `"blue" \| "green" \| "amber" \| "red" \| "violet" \| "zinc"` | `"blue"` | Progress color |
+| indeterminate | `boolean` | `false` | Show indeterminate/loading animation |
+| showValue | `boolean` | `false` | Display percentage text |
+| className | `string` | - | Additional CSS classes |
+## Examples
+### Bar with percentage
+```tsx
+<Progress value={75} showValue color="green" />
+```
+### Circular indeterminate
+```tsx
+<Progress variant="circular" indeterminate size="lg" color="violet" />
+```

package/docs/RadioGroup.md ADDED Viewed

@@ -0,0 +1,69 @@
+# RadioGroup
+Radio button group for single-value selection from a list of options.
+## Import
+```tsx
+import { RadioGroup } from "@particle-academy/react-fancy";
+```
+## Basic Usage
+```tsx
+<RadioGroup
+  label="Plan"
+  list={["Free", "Pro", "Enterprise"]}
+  onValueChange={(plan) => console.log(plan)}
+/>
+```
+## Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `list` | `InputOption[]` | **required** | Options as strings or `{ value, label, disabled?, description? }` |
+| `value` | `V` | - | Controlled selected value |
+| `defaultValue` | `V` | - | Default selected value (uncontrolled) |
+| `onValueChange` | `(value: 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"` | Radio button size |
+| `dirty` | `boolean` | `false` | Amber ring on all radios |
+| `required` | `boolean` | `false` | Red asterisk on label |
+| `disabled` | `boolean` | `false` | Disables all radios |
+| `name` | `string` | auto-generated | HTML `name` attribute for the radio group |
+| `className` | `string` | - | Additional CSS classes |
+## Examples
+### Horizontal layout with descriptions
+```tsx
+<RadioGroup
+  label="Priority"
+  orientation="horizontal"
+  list={[
+    { value: "low", label: "Low", description: "No rush" },
+    { value: "medium", label: "Medium" },
+    { value: "high", label: "High", description: "Urgent" },
+  ]}
+  defaultValue="medium"
+  onValueChange={setPriority}
+/>
+```
+### Controlled
+```tsx
+const [color, setColor] = useState("blue");
+<RadioGroup
+  label="Theme color"
+  list={["red", "blue", "green"]}
+  value={color}
+  onValueChange={setColor}
+/>
+```

package/docs/Select.md ADDED Viewed

@@ -0,0 +1,122 @@
+# Select
+Dropdown select with two variants: a native `<select>` element and a custom listbox with search, multi-select, and indicator support.
+## Import
+```tsx
+import { Select } from "@particle-academy/react-fancy";
+```
+## Basic Usage
+```tsx
+<Select
+  label="Country"
+  list={["USA", "Canada", "Mexico"]}
+  placeholder="Choose a country"
+/>
+```
+## Variants
+- **`"native"`** (default for single-select) -- Renders a standard `<select>` element. Best for simple use cases and mobile.
+- **`"listbox"`** (default when `multiple` is set) -- Renders a custom dropdown with keyboard navigation, optional search, and selection indicators.
+The variant is auto-selected based on the `multiple` prop, or set it explicitly with `variant`.
+## Props
+Extends native `<select>` attributes (except `size`, `prefix`, `multiple`).
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `list` | `InputOption[] \| InputOptionGroup[]` | **required** | Options as strings or `{ value, label, disabled?, description? }`. Groups via `{ label, options }`. |
+| `variant` | `"native" \| "listbox"` | `"native"` (auto `"listbox"` if `multiple`) | Rendering variant |
+| `placeholder` | `string` | `"Select..."` (listbox) | Placeholder text |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Controls sizing |
+| `label` | `string` | - | Wraps in a `Field` with this label |
+| `description` | `string` | - | Helper text below the select |
+| `error` | `string` | - | Error message |
+| `required` | `boolean` | `false` | Red asterisk on label |
+| `dirty` | `boolean` | `false` | Amber ring |
+| `disabled` | `boolean` | `false` | Disables the select |
+| `onValueChange` | `(value: string) => void` | - | Callback for single-select value changes |
+| **Listbox-only props** | | | |
+| `multiple` | `boolean` | `false` | Enable multi-select (forces listbox variant) |
+| `values` | `string[]` | - | Controlled multi-select values |
+| `defaultValues` | `string[]` | - | Default multi-select values (uncontrolled) |
+| `onValuesChange` | `(values: string[]) => void` | - | Callback for multi-select changes |
+| `searchable` | `boolean` | `false` | Show search/filter input in the dropdown |
+| `selectedSuffix` | `string` | `"selected"` | Suffix for the count display (e.g. "3 selected") |
+| `indicator` | `"check" \| "checkbox"` | `"check"` | Selection indicator style |
+| `prefix` | `ReactNode` | - | Affix before the select |
+| `suffix` | `ReactNode` | - | Affix after the select |
+### InputOption type
+```ts
+type InputOption = string | { value: string; label: string; disabled?: boolean; description?: string };
+```
+### InputOptionGroup type
+```ts
+type InputOptionGroup = { label: string; options: InputOption[] };
+```
+## Examples
+### Native with option objects
+```tsx
+<Select
+  label="Role"
+  list={[
+    { value: "admin", label: "Administrator" },
+    { value: "editor", label: "Editor" },
+    { value: "viewer", label: "Viewer", disabled: true },
+  ]}
+  onValueChange={(role) => console.log(role)}
+/>
+```
+### Listbox with search
+```tsx
+<Select
+  variant="listbox"
+  label="Framework"
+  searchable
+  list={["React", "Vue", "Angular", "Svelte", "Solid"]}
+  onValueChange={setFramework}
+/>
+```
+### Multi-select with checkbox indicator
+```tsx
+const [selected, setSelected] = useState<string[]>([]);
+<Select
+  label="Toppings"
+  multiple
+  searchable
+  indicator="checkbox"
+  list={["Pepperoni", "Mushrooms", "Onions", "Olives", "Peppers"]}
+  values={selected}
+  onValuesChange={setSelected}
+/>
+```
+### Option groups (native)
+```tsx
+<Select
+  label="Vehicle"
+  list={[
+    { label: "Cars", options: ["Sedan", "SUV", "Truck"] },
+    { label: "Bikes", options: ["Sport", "Cruiser"] },
+  ]}
+/>
+```

package/docs/Separator.md ADDED Viewed

@@ -0,0 +1,41 @@
+# Separator
+A horizontal or vertical divider line with optional centered label text.
+## Import
+```tsx
+import { Separator } from "@particle-academy/react-fancy";
+```
+## Basic Usage
+```tsx
+<Separator />
+```
+## Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| orientation | `"horizontal" \| "vertical"` | `"horizontal"` | Separator direction |
+| label | `string` | - | Optional centered label text (horizontal only) |
+| className | `string` | - | Additional CSS classes |
+## Examples
+### Horizontal with label
+```tsx
+<Separator label="or" />
+```
+### Vertical separator
+```tsx
+<div className="flex h-8 items-center gap-4">
+  <span>Left</span>
+  <Separator orientation="vertical" />
+  <span>Right</span>
+</div>
+```

package/docs/Sidebar.md ADDED Viewed

@@ -0,0 +1,88 @@
+# Sidebar
+A collapsible sidebar navigation with icon-only or letter-abbreviated collapsed mode, submenus, groups, and a toggle button.
+## Import
+```tsx
+import { Sidebar } from "@particle-academy/react-fancy";
+```
+## Basic Usage
+```tsx
+<Sidebar>
+  <Sidebar.Item href="/" icon={<HomeIcon />} active>Home</Sidebar.Item>
+  <Sidebar.Item href="/settings" icon={<GearIcon />}>Settings</Sidebar.Item>
+  <Sidebar.Group label="Projects">
+    <Sidebar.Item href="/project-a">Project A</Sidebar.Item>
+    <Sidebar.Item href="/project-b">Project B</Sidebar.Item>
+  </Sidebar.Group>
+  <Sidebar.Toggle />
+</Sidebar>
+```
+## Props
+### Sidebar (root)
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| collapsed | `boolean` | - | Controlled collapsed state |
+| defaultCollapsed | `boolean` | `false` | Default collapsed state (uncontrolled) |
+| onCollapsedChange | `(collapsed: boolean) => void` | - | Callback when collapsed state changes |
+| collapseMode | `"icons" \| "letters"` | `"icons"` | How items display when collapsed: icons only, or first 3 letters |
+| className | `string` | - | Additional CSS classes |
+### Sidebar.Item
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Item label |
+| href | `string` | - | Link URL |
+| icon | `ReactNode` | - | Leading icon |
+| active | `boolean` | - | Active state highlight |
+| disabled | `boolean` | - | Disable the item |
+| badge | `ReactNode` | - | Trailing badge element |
+| onClick | `() => void` | - | Click handler |
+| className | `string` | - | Additional CSS classes |
+### Sidebar.Group
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Grouped items |
+| label | `string` | - | Group heading |
+| className | `string` | - | Additional CSS classes |
+### Sidebar.Submenu
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Submenu items |
+| label | `string` | - | Submenu trigger label (required) |
+| icon | `ReactNode` | - | Leading icon |
+| defaultOpen | `boolean` | - | Whether the submenu starts open |
+| className | `string` | - | Additional CSS classes |
+### Sidebar.Toggle
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | `string` | - | Additional CSS classes |
+## Collapsible Sidebar
+```tsx
+const [collapsed, setCollapsed] = useState(false);
+<Sidebar collapsed={collapsed} onCollapsedChange={setCollapsed} collapseMode="icons">
+  <Sidebar.Item icon={<HomeIcon />}>Dashboard</Sidebar.Item>
+  <Sidebar.Item icon={<UsersIcon />}>Users</Sidebar.Item>
+  <Sidebar.Submenu label="Reports" icon={<ChartIcon />} defaultOpen>
+    <Sidebar.Item>Monthly</Sidebar.Item>
+    <Sidebar.Item>Yearly</Sidebar.Item>
+  </Sidebar.Submenu>
+  <Sidebar.Toggle />
+</Sidebar>
+```

package/docs/Skeleton.md ADDED Viewed

@@ -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 ADDED Viewed

@@ -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}
+/>
+```