@particle-academy/react-fancy 1.7.0 → 1.7.2

package/docs/Toast.md

@@ -0,0 +1,79 @@
+# Toast
+
+A notification system with timed auto-dismiss, multiple variants, and configurable screen position. Uses a provider + hook pattern.
+
+## Import
+
+```tsx
+import { Toast, useToast } from "@particle-academy/react-fancy";
+```
+
+## Setup
+
+Wrap your app with `Toast.Provider`:
+
+```tsx
+<Toast.Provider position="bottom-right" maxToasts={5}>
+  <App />
+</Toast.Provider>
+```
+
+## Basic Usage
+
+```tsx
+function MyComponent() {
+  const { toast, dismiss } = useToast();
+
+  return (
+    <button
+      onClick={() =>
+        toast({
+          title: "Saved",
+          description: "Your changes have been saved.",
+          variant: "success",
+          duration: 4000,
+        })
+      }
+    >
+      Save
+    </button>
+  );
+}
+```
+
+## Props
+
+### Toast.Provider
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| position | `"top-right" \| "top-left" \| "bottom-right" \| "bottom-left"` | `"bottom-right"` | Screen corner for toast stack |
+| maxToasts | `number` | `5` | Maximum visible toasts (oldest removed first) |
+
+### useToast() return value
+
+| Property | Type | Description |
+|----------|------|-------------|
+| toasts | `ToastData[]` | Current list of active toasts |
+| toast | `(data: Omit<ToastData, "id">) => string` | Show a toast, returns its id |
+| dismiss | `(id: string) => void` | Manually dismiss a toast by id |
+
+### ToastData
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| title | `string` | - | Toast title (required) |
+| description | `string` | - | Optional description text |
+| variant | `"default" \| "success" \| "error" \| "warning" \| "info"` | `"default"` | Visual variant |
+| duration | `number` | - | Auto-dismiss duration in ms |
+
+## Example with Variants
+
+```tsx
+const { toast } = useToast();
+
+toast({ title: "Info", variant: "info" });
+toast({ title: "Success!", variant: "success", description: "Item created." });
+toast({ title: "Error", variant: "error", description: "Something went wrong." });
+toast({ title: "Warning", variant: "warning", duration: 6000 });
+```

package/docs/Tooltip.md

@@ -0,0 +1,46 @@
+# Tooltip
+
+A tooltip that appears on hover/focus around a trigger element, rendered via Portal for correct stacking.
+
+## Import
+
+```tsx
+import { Tooltip } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<Tooltip content="Save changes">
+  <button>Save</button>
+</Tooltip>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactElement` | **required** | Trigger element (must accept ref, onMouseEnter, onMouseLeave, onFocus, onBlur) |
+| content | `ReactNode` | **required** | Tooltip content |
+| placement | `Placement` | `"top"` | Position relative to trigger. One of: `"top"`, `"bottom"`, `"left"`, `"right"`, `"top-start"`, `"top-end"`, `"bottom-start"`, `"bottom-end"` |
+| delay | `number` | `200` | Delay in ms before showing |
+| offset | `number` | `8` | Distance in px from the trigger |
+| className | `string` | - | Additional CSS classes for the tooltip |
+
+## Examples
+
+### Bottom placement with longer delay
+
+```tsx
+<Tooltip content="Delete this item" placement="bottom" delay={500}>
+  <button>Delete</button>
+</Tooltip>
+```
+
+### Rich content
+
+```tsx
+<Tooltip content={<span>Press <kbd>Ctrl+S</kbd> to save</span>}>
+  <button>Save</button>
+</Tooltip>
+```

package/docs/hooks.md

@@ -0,0 +1,180 @@
+# Hooks
+
+Shared React hooks used internally by components and available for direct use.
+
+## Import
+
+```tsx
+import {
+  useControllableState,
+  useOutsideClick,
+  useEscapeKey,
+  useFocusTrap,
+  useFloatingPosition,
+  useAnimation,
+  useId,
+  usePanZoom,
+} from "@particle-academy/react-fancy";
+```
+
+---
+
+## useControllableState
+
+Unifies controlled and uncontrolled component patterns into a single state hook.
+
+```tsx
+const [value, setValue] = useControllableState(controlledValue, defaultValue, onChange);
+```
+
+| Param | Type | Description |
+|-------|------|-------------|
+| controlledValue | `T \| undefined` | External controlled value (pass `undefined` for uncontrolled) |
+| defaultValue | `T` | Initial value when uncontrolled |
+| onChange | `(value: T) => void` | Optional callback fired on every change |
+
+**Returns:** `[T, (value: T | ((prev: T) => T)) => void]` -- current value and setter.
+
+---
+
+## useOutsideClick
+
+Calls a handler when a click or touch occurs outside the referenced element.
+
+```tsx
+useOutsideClick(ref, handler, enabled, ignoreRef);
+```
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| ref | `RefObject<HTMLElement \| null>` | - | Element to monitor |
+| handler | `(event: MouseEvent \| TouchEvent) => void` | - | Called on outside click |
+| enabled | `boolean` | `true` | Enable/disable the listener |
+| ignoreRef | `RefObject<HTMLElement \| null>` | - | Optional element to exclude (e.g. a trigger) |
+
+---
+
+## useEscapeKey
+
+Calls a handler when the Escape key is pressed.
+
+```tsx
+useEscapeKey(handler, enabled);
+```
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| handler | `() => void` | - | Called on Escape keydown |
+| enabled | `boolean` | `true` | Enable/disable the listener |
+
+---
+
+## useFocusTrap
+
+Traps keyboard focus within a container element. Focuses the first focusable element on mount and restores focus on unmount.
+
+```tsx
+useFocusTrap(ref, enabled);
+```
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| ref | `RefObject<HTMLElement \| null>` | - | Container to trap focus within |
+| enabled | `boolean` | `true` | Enable/disable the trap |
+
+Focusable elements: `a[href]`, `button:not([disabled])`, `input:not([disabled])`, `textarea:not([disabled])`, `select:not([disabled])`, `[tabindex]:not([tabindex='-1'])`.
+
+---
+
+## useFloatingPosition
+
+Computes the absolute position for a floating element anchored to a reference element. Handles viewport clamping and automatic placement flipping.
+
+```tsx
+const { x, y, placement } = useFloatingPosition(anchorRef, floatingRef, options);
+```
+
+| Param | Type | Description |
+|-------|------|-------------|
+| anchorRef | `RefObject<HTMLElement \| null>` | Reference/trigger element |
+| floatingRef | `RefObject<HTMLElement \| null>` | Floating element to position |
+| options | `object` | Configuration (see below) |
+
+**Options:**
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| placement | `Placement` | `"bottom"` | Desired placement |
+| offset | `number` | `8` | Pixel gap between anchor and floating element |
+| enabled | `boolean` | `true` | Enable/disable positioning |
+
+**Returns:** `{ x: number, y: number, placement: Placement }` -- the resolved position may differ from requested if the element was flipped to stay in viewport.
+
+---
+
+## useAnimation
+
+Manages CSS animation mount/unmount lifecycle. Keeps the element mounted during the exit animation, then unmounts after `animationend`.
+
+```tsx
+const { mounted, className, ref } = useAnimation({ open, enterClass, exitClass });
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| open | `boolean` | Whether the animated element should be visible |
+| enterClass | `string` | CSS class applied on enter |
+| exitClass | `string` | CSS class applied on exit |
+
+**Returns:**
+
+| Key | Type | Description |
+|-----|------|-------------|
+| mounted | `boolean` | Whether the element should be in the DOM |
+| className | `string` | Current animation class to apply |
+| ref | `RefObject<HTMLElement \| null>` | Attach to the animated element for `animationend` detection |
+
+---
+
+## useId
+
+Generates a stable unique ID, optionally with a prefix. Wraps React's `useId`.
+
+```tsx
+const id = useId("dialog"); // e.g. "dialog-:r0:"
+```
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| prefix | `string` | - | Optional prefix prepended to the id |
+
+---
+
+## usePanZoom
+
+Provides pointer-event handlers for panning (click+drag on background) and Ctrl+wheel zooming on a container element.
+
+```tsx
+const { containerProps, isPanning } = usePanZoom(options);
+```
+
+**Options:**
+
+| Key | Type | Description |
+|-----|------|-------------|
+| viewport | `ViewportState` | Current `{ panX, panY, zoom }` |
+| setViewport | `(vp \| updater) => void` | State setter for viewport |
+| minZoom | `number` | Minimum zoom level |
+| maxZoom | `number` | Maximum zoom level |
+| pannable | `boolean` | Enable panning |
+| zoomable | `boolean` | Enable zooming |
+| containerRef | `RefObject<HTMLElement \| null>` | The scrollable container |
+
+**Returns:**
+
+| Key | Type | Description |
+|-----|------|-------------|
+| containerProps | `{ onPointerDown, onPointerMove, onPointerUp }` | Spread onto the container element |
+| isPanning | `boolean` | Whether a pan gesture is active |
+
+Zooming requires Ctrl+wheel (or Cmd+wheel / pinch gesture). Normal scrolling is not hijacked.

package/docs/utilities.md

@@ -0,0 +1,74 @@
+# Utilities
+
+Shared utility functions and types.
+
+## Import
+
+```tsx
+import { cn } from "@particle-academy/react-fancy";
+```
+
+---
+
+## cn()
+
+Merges class names using `clsx` + `tailwind-merge`. Handles conditional classes and deduplicates conflicting Tailwind utilities.
+
+```tsx
+cn("px-4 py-2", isActive && "bg-blue-500", className);
+// => "px-4 py-2 bg-blue-500"
+
+cn("px-4 text-sm", "px-6");
+// => "px-6 text-sm" (tailwind-merge resolves px conflict)
+```
+
+**Signature:**
+
+```ts
+function cn(...inputs: ClassValue[]): string;
+```
+
+Accepts strings, objects, arrays, `undefined`, `null`, and `false` -- anything `clsx` supports.
+
+---
+
+## Shared Types
+
+### Size
+
+```ts
+type Size = "xs" | "sm" | "md" | "lg" | "xl";
+```
+
+### Color
+
+```ts
+type Color =
+  | "zinc" | "red" | "orange" | "amber" | "yellow" | "lime"
+  | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue"
+  | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose";
+```
+
+### Variant
+
+```ts
+type Variant = "solid" | "outline" | "ghost" | "soft";
+```
+
+### ActionColor
+
+```ts
+type ActionColor =
+  | "blue" | "emerald" | "amber" | "red" | "violet"
+  | "indigo" | "sky" | "rose" | "orange" | "zinc";
+```
+
+### Placement
+
+Used by Popover, Dropdown, and `useFloatingPosition`.
+
+```ts
+type Placement =
+  | "top" | "bottom" | "left" | "right"
+  | "top-start" | "top-end" | "bottom-start" | "bottom-end";
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/react-fancy",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "description": "React UI component library — React port of the fancy-flux Blade component library",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -21,6 +21,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "README.md"
   ],
   "scripts": {