@overdoser/react-toolkit 0.1.0 → 0.5.0

package/llms.txt

@@ -317,6 +317,278 @@ Example:
 </Modal>
 ```
 
+### Draggable
+Import: `import { Draggable } from '@overdoser/react-toolkit'`
+Element: a `<div>` (forwards ref) that wraps arbitrary children. Free-move container — position is a `translate(x, y)` offset from the element's natural layout position, so it stays in flow until dragged.
+
+Compound: `Draggable.Handle` — place inside to restrict the grab area (e.g. a title bar). Without a handle, the whole surface drags. A focused handle is also keyboard-movable (arrow keys).
+
+`DraggableProps` (extends native `div` props except `onDrag`):
+- `defaultPosition?: { x: number; y: number }` — uncontrolled initial offset. Default `{ x: 0, y: 0 }`.
+- `position?: { x: number; y: number }` — controlled offset; pair with `onDrag` to update it.
+- `axis?: 'both' | 'x' | 'y'` — default `'both'`.
+- `bounds?: 'viewport' | 'parent' | 'none'` — default `'viewport'`. Clamps movement to the viewport / parent element, or unconstrained.
+- `keyboardStep?: number` — px per arrow-key press on a focused handle. Default `10`.
+- `disabled?: boolean` — default `false`.
+- `onDragStart?(pos)`, `onDrag?(pos)`, `onDragEnd?(pos)` — each receives `{ x, y }`.
+- `classes?: Partial<DraggableClasses>` where `DraggableClasses = { root, handle }`.
+
+Example:
+```tsx
+<Draggable defaultPosition={{ x: 40, y: 40 }} bounds="viewport">
+  <Draggable.Handle>⠿ Drag me</Draggable.Handle>
+  <div>Any content here</div>
+</Draggable>
+```
+
+### Toast (ToastProvider + toast + useToast)
+Import: `import { ToastProvider, toast, useToast } from '@overdoser/react-toolkit'`
+
+Imperative notification system backed by a global store. Mount `ToastProvider` **once** (it renders a portal at `document.body` and is the only thing that draws toasts — do NOT render toast elements yourself). Then trigger toasts either way:
+- **Standalone `toast(options)`** — importable, no hook/context needed (works from event handlers, utilities, outside React). Also `toast.dismiss(id)` and `toast.dismissAll()`.
+- **`useToast()`** — returns `{ toast, dismiss, dismissAll }` (the same functions) for callers who prefer a hook. It does NOT require being under the provider and never throws.
+
+If `toast()` fires while no `ToastProvider` is mounted, it warns (dev) and renders nothing.
+
+`ToastProviderProps`:
+- `children: ReactNode` — required.
+- `position?: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'` — default `'top-right'`.
+- `duration?: number` — default auto-dismiss ms. Default `5000`.
+- `max?: number` — max simultaneously-visible toasts (older dropped). Default `5`.
+- `classes?: Partial<ToastClasses>` where `ToastClasses = { viewport, toast, icon, content, title, description, close }`.
+
+`toast(options: ToastOptions): string` — standalone; show a toast, returns its id. Methods: `toast.dismiss(id)`, `toast.dismissAll()`.
+
+`useToast(): ToastApi` — `{ toast, dismiss, dismissAll }` (identical functions; provided for hook-style ergonomics).
+
+`ToastOptions`:
+- `title?: ReactNode`
+- `description?: ReactNode`
+- `variant?: 'neutral' | 'info' | 'success' | 'warning' | 'danger'` — default `'neutral'`.
+- `duration?: number` — override the provider default; `0` or `Infinity` = persist until dismissed.
+
+Behavior: auto-dismiss pauses while hovered and resumes on leave. `danger`/`warning` use `role="alert"` (assertive); others use `role="status"` (polite).
+
+Example:
+```tsx
+import { ToastProvider, toast } from '@overdoser/react-toolkit';
+
+function App() {
+  return <ToastProvider position="bottom-right"><Page /></ToastProvider>;
+}
+function Page() {
+  // No hook needed — call toast() directly.
+  return <Button onClick={() => toast({ variant: 'success', title: 'Saved' })}>Save</Button>;
+}
+```
+
+### Tabs (Tabs.List / Tabs.Tab / Tabs.Panel)
+Import: `import { Tabs } from '@overdoser/react-toolkit'`
+Element: a `<div>` (forwards ref) wrapping a `role="tablist"` and panels.
+
+Compound: `Tabs.List`, `Tabs.Tab` (needs `value`), `Tabs.Panel` (needs `value`). A tab and its panel are linked by matching `value`. Keyboard: arrow keys (orientation-aware) + Home/End move and activate; roving tabindex; automatic activation on focus.
+
+`TabsProps`:
+- `value?: string` — controlled active tab.
+- `defaultValue?: string` — uncontrolled initial active tab.
+- `onValueChange?: (value: string) => void`
+- `orientation?: 'horizontal' | 'vertical'` — default `'horizontal'`.
+- `variant?: 'line' | 'solid' | 'pill'` — default `'line'`.
+- `size?: 'sm' | 'md' | 'lg'` — default `'md'`.
+- `classes?: Partial<TabsClasses>` where `TabsClasses = { root, list, tab, panel }`.
+
+`Tabs.Tab` props: `value: string` (required), `disabled?: boolean`, plus native button props.
+`Tabs.Panel` props: `value: string` (required), `keepMounted?: boolean` (default `false` — keep inactive panels mounted but hidden), plus native div props.
+
+Example:
+```tsx
+<Tabs defaultValue="overview" variant="pill">
+  <Tabs.List aria-label="Sections">
+    <Tabs.Tab value="overview">Overview</Tabs.Tab>
+    <Tabs.Tab value="activity">Activity</Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panel value="overview">Overview content</Tabs.Panel>
+  <Tabs.Panel value="activity">Activity content</Tabs.Panel>
+</Tabs>
+```
+
+### Alert
+Import: `import { Alert } from '@overdoser/react-toolkit'`
+Element: a `<div role="alert">` (forwards ref). Inline, persistent status message.
+
+`AlertProps` (extends native `div` props, omits `title`):
+- `variant?: 'info' | 'success' | 'warning' | 'danger'` — default `'info'`.
+- `title?: ReactNode` — optional bold heading.
+- `icon?: ReactNode | boolean` — default `true` (variant icon). Pass a node to override, `false` to hide.
+- `onClose?: () => void` — when set, renders a dismiss button.
+- `closeLabel?: string` — default `'Dismiss'`.
+- `classes?: Partial<AlertClasses>` where `AlertClasses = { root, icon, content, title, message, close }`.
+- children = message body.
+
+Example:
+```tsx
+<Alert variant="success" title="Saved" onClose={() => setShown(false)}>Your changes were saved.</Alert>
+```
+
+### Badge
+Import: `import { Badge } from '@overdoser/react-toolkit'`
+Element: a `<span>` (forwards ref). Small inline status pill.
+
+`BadgeProps` (extends native `span` props):
+- `variant?: 'neutral' | 'primary' | 'success' | 'warning' | 'danger'` — default `'neutral'`.
+- `appearance?: 'soft' | 'solid' | 'outline'` — default `'soft'`.
+- `size?: 'sm' | 'md' | 'lg'` — default `'md'`.
+- `dot?: boolean` — leading status dot. Default `false`.
+- `classes?: Partial<BadgeClasses>` where `BadgeClasses = { root, dot }`.
+
+Example:
+```tsx
+<Badge variant="success" dot>Active</Badge>
+<Badge variant="primary" appearance="solid">3</Badge>
+```
+
+### Spinner
+Import: `import { Spinner } from '@overdoser/react-toolkit'`
+Element: a `<span role="status">` (forwards ref). Indeterminate loading spinner; inherits `currentColor`.
+
+`SpinnerProps` (extends native `span` props):
+- `size?: 'sm' | 'md' | 'lg'` — default `'md'`.
+- `color?: string` — overrides `currentColor`.
+- `label?: string` — visually-hidden a11y label. Default `'Loading'`; pass `''` to omit when an adjacent element already labels the busy state.
+- `classes?: Partial<SpinnerClasses>` where `SpinnerClasses = { root, circle, label }`.
+
+Example:
+```tsx
+<Spinner size="lg" />
+```
+
+### Skeleton
+Import: `import { Skeleton } from '@overdoser/react-toolkit'`
+Element: a `<div aria-hidden>` (forwards ref). Decorative loading placeholder.
+
+`SkeletonProps` (extends native `div` props, omits `children`):
+- `variant?: 'text' | 'circle' | 'rect'` — default `'text'`.
+- `width?: number | string` — number → px. Defaults to `100%`.
+- `height?: number | string` — number → px. Defaults per variant.
+- `animation?: 'pulse' | 'wave' | 'none'` — default `'pulse'`.
+- `lines?: number` — for `variant="text"`, render N stacked bars (last is shorter). Default `1`.
+- `classes?: Partial<SkeletonClasses>` where `SkeletonClasses = { root, line }`.
+
+Example:
+```tsx
+<Skeleton variant="text" lines={3} />
+<Skeleton variant="circle" width={40} height={40} />
+```
+
+### Drawer (Drawer.Header / Drawer.Body / Drawer.Footer)
+Import: `import { Drawer } from '@overdoser/react-toolkit'`
+Off-canvas panel sliding from a screen edge. Portal at `document.body`, focus trap, body scroll lock, Escape/backdrop close. Same family as `Modal` but anchored to a side.
+
+`DrawerProps`:
+- `open: boolean` — required.
+- `onClose: () => void` — required (backdrop, Escape, header button).
+- `side?: 'left' | 'right' | 'top' | 'bottom'` — default `'right'`. Left/right span full height (partial width); top/bottom span full width (partial height).
+- `size?: 'sm' | 'md' | 'lg' | 'full'` — default `'md'` (width for left/right, height for top/bottom).
+- `variant?: 'temporary' | 'persistent'` — default `'temporary'`. `temporary` overlays a dimmed scrim and is modal (scrim/Escape close). `persistent` shows no scrim and leaves the page interactive (a fixed side panel).
+- `closeOnBackdrop?: boolean` — default `true` (temporary only). `closeOnEscape?: boolean` — default `true`.
+
+Slides in/out with a drawer easing (panel translate + scrim fade); stays mounted through the close transition.
+- `aria-label?` / `aria-labelledby?` — if neither, `Drawer.Header` is auto-wired as the label.
+- `classes?: Partial<DrawerClasses>` = `{ backdrop, drawer, header, closeButton, body, footer }`.
+
+`Drawer.Header` takes `onClose?` (renders an × button). `Drawer.Body`/`Drawer.Footer` take `children`.
+
+### Tooltip
+Import: `import { Tooltip } from '@overdoser/react-toolkit'`
+Lightweight text label on hover/focus after a delay. Wraps the trigger in an inline span and portals the bubble. For interactive/click content use `Popover`.
+
+`TooltipProps`:
+- `content: ReactNode` — the label (nullish/empty → never shows).
+- `children: ReactNode` — the trigger.
+- `placement?: 'top' | 'bottom' | 'left' | 'right'` — default `'top'` (flips on overflow).
+- `delay?: number` — open delay ms, default `300`. `closeDelay?: number` — default `0`.
+- `disabled?: boolean`, `hideArrow?: boolean`.
+- `classes?: Partial<TooltipClasses>` = `{ wrapper, tooltip, arrow }`.
+Closes on Escape; wires `aria-describedby` while open.
+
+### Avatar
+Import: `import { Avatar } from '@overdoser/react-toolkit'`
+Element: `<span>` (forwards ref). Image with initials/icon fallback.
+
+`AvatarProps` (extends `span`): `src?`, `alt?`, `name?` (→ initials), `fallback?: ReactNode`, `size?: 'xs'|'sm'|'md'|'lg'|'xl'` (default `'md'`), `shape?: 'circle'|'square'` (default `'circle'`), `status?: 'online'|'offline'|'away'|'busy'`, `classes?` = `{ root, image, fallback, status }`. Falls back to initials (or a user icon) if `src` is missing or errors.
+
+### Divider
+Import: `import { Divider } from '@overdoser/react-toolkit'`
+Element: `<div role="separator">` (forwards ref). `orientation?: 'horizontal'|'vertical'` (default horizontal), `variant?: 'solid'|'dashed'|'dotted'`, `label?: ReactNode` (horizontal only), `labelPosition?: 'start'|'center'|'end'`, `classes?` = `{ root, line, label }`.
+
+### Breadcrumbs (Breadcrumbs.Item)
+Import: `import { Breadcrumbs } from '@overdoser/react-toolkit'`
+`<nav><ol>` (forwards ref). Children are `Breadcrumbs.Item`; separators auto-inserted; the last item defaults to `current`.
+
+`BreadcrumbsProps`: `separator?: ReactNode` (default `'/'`), `label?: string` (default `'Breadcrumb'`), `classes?` = `{ root, list, item, link, current, separator }`.
+`Breadcrumbs.Item` props: `href?` (omit for plain text), `current?: boolean` (→ `aria-current="page"`, no link).
+
+### Pagination
+Import: `import { Pagination } from '@overdoser/react-toolkit'`
+`<nav>` (forwards ref). Windowed page list with ellipses, e.g. `1 … 6 7 8 9 10 … 99`.
+
+`PaginationProps`:
+- `count?: number` (total pages) OR `total?: number` + `pageSize?: number` (default 10) to derive it.
+- `page?: number` (controlled, 1-based) / `defaultPage?: number` (default 1) / `onChange?: (page) => void`.
+- `siblingCount?: number` — default `2` (→ at most 9 chips). `boundaryCount?: number` — default `1`.
+- `showPrevNext?: boolean` (default true), `showFirstLast?: boolean` (default false).
+- `size?: 'sm'|'md'|'lg'`, `disabled?: boolean`, `label?: string`.
+- `classes?` = `{ root, list, item, active, ellipsis, control }`.
+Also exports `paginationRange(page, count, boundaryCount?, siblingCount?): (number | 'ellipsis')[]`.
+
+### Slider
+Import: `import { Slider } from '@overdoser/react-toolkit'`
+Element: `<div>` (forwards ref) containing `role="slider"` thumb(s). A tuple `value` makes it a range (two thumbs). Pointer drag + keyboard (arrows, Home/End, PageUp/Down).
+
+`SliderProps`: `value?: number | [number, number]`, `defaultValue?`, `onChange?(value)`, `onChangeEnd?(value)`, `min?` (0), `max?` (100), `step?` (1), `disabled?`, `aria-label?`/`aria-labelledby?`, `formatValue?(n): string` (for `aria-valuetext`), `classes?` = `{ root, track, range, thumb }`.
+
+### NumberInput
+Import: `import { NumberInput } from '@overdoser/react-toolkit'`
+Element: `<div>` wrapping `<input>` (forwards ref to the input) + stepper buttons. Emits `onChange(value: number | null)`, so it binds in `FormField`.
+
+`NumberInputProps`: `value?: number | null`, `defaultValue?`, `onChange?(value)`, `min?`, `max?`, `step?` (1), `precision?` (decimal places), `inputSize?: 'sm'|'md'|'lg'`, `error?`, `hideControls?`, `disabled?`, `classes?` = `{ root, input, controls, increment, decrement }`. Arrow keys step; values clamp on blur; buttons disable at min/max.
+
+### DatePicker
+Import: `import { DatePicker } from '@overdoser/react-toolkit'`
+Element: `<div>` wrapping a read-only `<input>` (forwards ref) + a calendar popover. Single date; binds in `FormField` (`value: Date | null`).
+
+`DatePickerProps`: `value?: Date | null`, `defaultValue?`, `onChange?(date)`, `min?: Date`, `max?: Date`, `disabledDate?(date): boolean`, `weekStartsOn?: number` (0 = Sun), `locale?: string`, `format?(date): string`, `placeholder?` (default `'Select date'`), `inputSize?: 'sm'|'md'|'lg'`, `error?`, `disabled?`, `portal?` (default true), `classes?` = `{ root, input, icon, popover, header, nav, grid, day, daySelected, dayToday, dayOutside }`. Keyboard: arrows move days, PageUp/Down change month, Home/End week ends, Enter selects, Esc closes.
+
+### Dropzone
+Import: `import { Dropzone } from '@overdoser/react-toolkit'`
+Element: `<div role="button">` (forwards ref to a hidden file `<input>`). Drag-drop or click to browse; emits files, leaves list UI to you.
+
+`DropzoneProps`: `onFiles?(files: File[])`, `onReject?(rejections: { file, reason: 'type'|'size'|'multiple' }[])`, `accept?` (comma list of extensions/MIME patterns), `multiple?` (default false), `maxSize?` (bytes), `disabled?`, `label?`, `hint?`, `children?: ReactNode | (state: { isDragging }) => ReactNode` (custom content), `classes?` = `{ root, input, content, icon, label, hint }`.
+
+### Timer
+Import: `import { Timer } from '@overdoser/react-toolkit'`
+Element: `<div role="timer">`. Forwards a `TimerHandle` ref (not a DOM node): `{ start, pause, reset, restart, getTime(): number, isRunning }`.
+
+`TimerProps`:
+- `mode?: 'countdown' | 'stopwatch'` — default `'countdown'`.
+- `duration?: number` — seconds (countdown length / stopwatch cap; drives ring progress).
+- `to?: Date | number` — absolute countdown target (overrides `duration`/pause).
+- `value?: number` — controlled seconds → display-only (no internal clock).
+- `autoStart?: boolean` (default true), `running?: boolean` (controlled run state), `interval?: number` ms (default 1000).
+- `variant?: 'digital' | 'ring' | 'segments'` (default `'digital'`), `size?: 'sm'|'md'|'lg'`.
+- `format?(seconds): ReactNode` (digital/ring only; default `MM:SS` / `H:MM:SS` / `Dd HH:MM:SS`).
+- `label?: ReactNode`, `labelPlacement?: 'top'|'bottom'|'left'|'right'` (default `'bottom'`).
+- `onComplete?()` (countdown hits 0), `onTick?(seconds)`.
+- `classes?` = `{ root, display, label, ringTrack, ringProgress, segments, segment, segmentValue, segmentLabel }`.
+
+Segments variant (`variant="segments"`) — one cell per unit, with the unit label under each number:
+- `units?: ('days'|'hours'|'minutes'|'seconds')[]` — which cells to show. Default: smallest set that fits the duration (the leading unit absorbs overflow, e.g. `units={['minutes','seconds']}` on 1h shows `61 : 00`).
+- `unitFormat?: 'long' | 'short'` (default `'short'` → `d/h/m/s`; `'long'` → `days/hours/minutes/seconds`, fixed — no singular/plural switching).
+- `unitLabels?: Partial<Record<TimerUnit, ReactNode | ((value: number) => ReactNode)>>` — override labels per unit.
+- `segmentVariant?: 'boxed' | 'plain'` (default `'boxed'` — a square with the number and the unit below).
+- `renderSegment?: (segment: TimerSegment, index: number) => ReactNode` — fully custom per-cell rendering (`TimerSegment = { unit, value, text, label }`). Overrides `segmentVariant`.
+- `segmentSeparator?: ReactNode` — content between cells (e.g. `':'`).
+
 ### Form / FormField / FormRow
 Requires `react-hook-form` peer dependency.
 
@@ -441,12 +713,14 @@ Element: `<input type="checkbox">` wrapped in a `<label>` (forwards ref to the i
 
 Props (extends native input props):
 - `label?: ReactNode`
-- `indeterminate?: boolean` — default `false`. Sets the DOM `indeterminate` property; visually distinct.
+- `variant?: 'checkbox' | 'switch'` — default `'checkbox'`. `'switch'` renders a sliding toggle; the underlying `<input type="checkbox">` (a11y + form behavior) is identical.
+- `indeterminate?: boolean` — default `false`. Sets the DOM `indeterminate` property; visually distinct. Ignored when `variant="switch"`.
 - `classes?: Partial<CheckboxClasses>` where `CheckboxClasses = { root, input, label }`
 
 Example:
 ```tsx
 <Checkbox label="Remember me" checked={remember} onChange={(e) => setRemember(e.target.checked)} />
+<Checkbox variant="switch" label="Notifications" defaultChecked />
 ```
 
 ### CheckboxGroup