@overdoser/react-toolkit 0.1.0 → 0.5.0

package/manifest.json

@@ -478,6 +478,547 @@
         "childrenTyped": "never — pass via `content` prop"
       }
     },
+    "Draggable": {
+      "import": "import { Draggable } from '@overdoser/react-toolkit'",
+      "element": "div wrapping arbitrary children",
+      "forwardsRef": true,
+      "extendsNativeProps": "div (except onDrag)",
+      "compoundComponents": [
+        "Draggable.Handle"
+      ],
+      "notes": "Free-move container. Position is a translate(x,y) offset from the element's natural layout position. Add Draggable.Handle to restrict the grab area; without one the whole surface drags. A focused handle is keyboard-movable (arrow keys).",
+      "props": {
+        "defaultPosition": {
+          "type": "{ x: number; y: number }",
+          "default": "{ x: 0, y: 0 }",
+          "notes": "Uncontrolled initial offset."
+        },
+        "position": {
+          "type": "{ x: number; y: number }",
+          "notes": "Controlled offset; pair with onDrag to update it."
+        },
+        "axis": {
+          "type": "'both' | 'x' | 'y'",
+          "default": "both"
+        },
+        "bounds": {
+          "type": "'viewport' | 'parent' | 'none'",
+          "default": "viewport",
+          "notes": "Clamp movement to the viewport / parent element, or leave unconstrained."
+        },
+        "keyboardStep": {
+          "type": "number",
+          "default": 10,
+          "notes": "Px per arrow-key press on a focused handle."
+        },
+        "disabled": {
+          "type": "boolean",
+          "default": false
+        },
+        "onDragStart": {
+          "type": "(position: { x: number; y: number }) => void"
+        },
+        "onDrag": {
+          "type": "(position: { x: number; y: number }) => void",
+          "notes": "Required to update a controlled position."
+        },
+        "onDragEnd": {
+          "type": "(position: { x: number; y: number }) => void"
+        },
+        "classes": {
+          "type": "Partial<DraggableClasses>",
+          "shape": [
+            "root",
+            "handle"
+          ]
+        }
+      }
+    },
+    "Toast": {
+      "import": "import { ToastProvider, toast, useToast } from '@overdoser/react-toolkit'",
+      "element": "portal viewport at document.body",
+      "notes": "Imperative notification system backed by a global store. Mount ToastProvider once (it is the renderer; do NOT render toast elements yourself). Trigger via the standalone toast(options) (no hook/context needed; also toast.dismiss(id) / toast.dismissAll()) OR via useToast() which returns the same { toast, dismiss, dismissAll }. useToast does not require the provider and never throws. toast() with no provider mounted warns (dev) and renders nothing. danger/warning use role=alert (assertive); others role=status (polite). Auto-dismiss pauses on hover.",
+      "standaloneTrigger": {
+        "name": "toast",
+        "signature": "toast(options: ToastOptions): string",
+        "methods": [
+          "toast.dismiss(id: string): void",
+          "toast.dismissAll(): void"
+        ],
+        "notes": "Importable; callable anywhere without a hook or context."
+      },
+      "provider": {
+        "name": "ToastProvider",
+        "props": {
+          "children": {
+            "type": "ReactNode",
+            "required": true
+          },
+          "position": {
+            "type": "'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'",
+            "default": "top-right"
+          },
+          "duration": {
+            "type": "number",
+            "default": 5000,
+            "notes": "Default auto-dismiss ms."
+          },
+          "max": {
+            "type": "number",
+            "default": 5
+          },
+          "classes": {
+            "type": "Partial<ToastClasses>",
+            "shape": [
+              "viewport",
+              "toast",
+              "icon",
+              "content",
+              "title",
+              "description",
+              "close"
+            ]
+          }
+        }
+      },
+      "hook": {
+        "name": "useToast",
+        "returns": "ToastApi = { toast(options): string; dismiss(id): void; dismissAll(): void }",
+        "throwsWithoutProvider": false,
+        "toastOptions": {
+          "title": {
+            "type": "ReactNode"
+          },
+          "description": {
+            "type": "ReactNode"
+          },
+          "variant": {
+            "type": "'neutral' | 'info' | 'success' | 'warning' | 'danger'",
+            "default": "neutral"
+          },
+          "duration": {
+            "type": "number",
+            "notes": "Overrides provider default; 0 or Infinity persists until dismissed."
+          }
+        }
+      }
+    },
+    "Tabs": {
+      "import": "import { Tabs } from '@overdoser/react-toolkit'",
+      "element": "div wrapping role=tablist + panels",
+      "forwardsRef": true,
+      "compoundComponents": [
+        "Tabs.List",
+        "Tabs.Tab",
+        "Tabs.Panel"
+      ],
+      "notes": "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.",
+      "props": {
+        "value": {
+          "type": "string",
+          "notes": "Controlled active tab."
+        },
+        "defaultValue": {
+          "type": "string",
+          "notes": "Uncontrolled initial active tab."
+        },
+        "onValueChange": {
+          "type": "(value: string) => void"
+        },
+        "orientation": {
+          "type": "'horizontal' | 'vertical'",
+          "default": "horizontal"
+        },
+        "variant": {
+          "type": "'line' | 'solid' | 'pill'",
+          "default": "line"
+        },
+        "size": {
+          "type": "'sm' | 'md' | 'lg'",
+          "default": "md"
+        },
+        "classes": {
+          "type": "Partial<TabsClasses>",
+          "shape": [
+            "root",
+            "list",
+            "tab",
+            "panel"
+          ]
+        }
+      },
+      "subComponentProps": {
+        "Tabs.Tab": {
+          "value": {
+            "type": "string",
+            "required": true
+          },
+          "disabled": {
+            "type": "boolean",
+            "default": false
+          }
+        },
+        "Tabs.Panel": {
+          "value": {
+            "type": "string",
+            "required": true
+          },
+          "keepMounted": {
+            "type": "boolean",
+            "default": false,
+            "notes": "Keep inactive panels mounted but hidden."
+          }
+        }
+      }
+    },
+    "Alert": {
+      "import": "import { Alert } from '@overdoser/react-toolkit'",
+      "element": "div[role=alert]",
+      "forwardsRef": true,
+      "extendsNativeProps": "div (without title)",
+      "notes": "Inline, persistent status message. For transient feedback prefer Toast.",
+      "props": {
+        "variant": {
+          "type": "'info' | 'success' | 'warning' | 'danger'",
+          "default": "info"
+        },
+        "title": {
+          "type": "ReactNode"
+        },
+        "icon": {
+          "type": "ReactNode | boolean",
+          "default": true,
+          "notes": "true = variant icon; node = override; false = hide."
+        },
+        "onClose": {
+          "type": "() => void",
+          "notes": "When set, renders a dismiss button."
+        },
+        "closeLabel": {
+          "type": "string",
+          "default": "Dismiss"
+        },
+        "classes": {
+          "type": "Partial<AlertClasses>",
+          "shape": [
+            "root",
+            "icon",
+            "content",
+            "title",
+            "message",
+            "close"
+          ]
+        }
+      }
+    },
+    "Badge": {
+      "import": "import { Badge } from '@overdoser/react-toolkit'",
+      "element": "span",
+      "forwardsRef": true,
+      "extendsNativeProps": "span",
+      "props": {
+        "variant": {
+          "type": "'neutral' | 'primary' | 'success' | 'warning' | 'danger'",
+          "default": "neutral"
+        },
+        "appearance": {
+          "type": "'soft' | 'solid' | 'outline'",
+          "default": "soft"
+        },
+        "size": {
+          "type": "'sm' | 'md' | 'lg'",
+          "default": "md"
+        },
+        "dot": {
+          "type": "boolean",
+          "default": false,
+          "notes": "Leading status dot."
+        },
+        "classes": {
+          "type": "Partial<BadgeClasses>",
+          "shape": [
+            "root",
+            "dot"
+          ]
+        }
+      }
+    },
+    "Spinner": {
+      "import": "import { Spinner } from '@overdoser/react-toolkit'",
+      "element": "span[role=status]",
+      "forwardsRef": true,
+      "extendsNativeProps": "span",
+      "notes": "Indeterminate loading spinner; inherits currentColor.",
+      "props": {
+        "size": {
+          "type": "'sm' | 'md' | 'lg'",
+          "default": "md"
+        },
+        "color": {
+          "type": "string",
+          "notes": "Overrides currentColor."
+        },
+        "label": {
+          "type": "string",
+          "default": "Loading",
+          "notes": "Visually-hidden a11y label; pass '' to omit."
+        },
+        "classes": {
+          "type": "Partial<SpinnerClasses>",
+          "shape": [
+            "root",
+            "circle",
+            "label"
+          ]
+        }
+      }
+    },
+    "Skeleton": {
+      "import": "import { Skeleton } from '@overdoser/react-toolkit'",
+      "element": "div[aria-hidden]",
+      "forwardsRef": true,
+      "extendsNativeProps": "div (without children)",
+      "notes": "Decorative loading placeholder.",
+      "props": {
+        "variant": {
+          "type": "'text' | 'circle' | 'rect'",
+          "default": "text"
+        },
+        "width": {
+          "type": "number | string",
+          "notes": "number → px; defaults to 100%."
+        },
+        "height": {
+          "type": "number | string",
+          "notes": "number → px; defaults per variant."
+        },
+        "animation": {
+          "type": "'pulse' | 'wave' | 'none'",
+          "default": "pulse"
+        },
+        "lines": {
+          "type": "number",
+          "default": 1,
+          "notes": "For variant=text, render N stacked bars (last shorter)."
+        },
+        "classes": {
+          "type": "Partial<SkeletonClasses>",
+          "shape": [
+            "root",
+            "line"
+          ]
+        }
+      }
+    },
+    "Drawer": {
+      "import": "import { Drawer } from '@overdoser/react-toolkit'",
+      "element": "div (portal at document.body)",
+      "forwardsRef": true,
+      "compoundComponents": ["Drawer.Header", "Drawer.Body", "Drawer.Footer"],
+      "notes": "Off-canvas panel sliding from a screen edge (left/right = full-height strip, top/bottom = full-width strip). Animates in/out and stays mounted through the close transition.",
+      "props": {
+        "open": { "type": "boolean", "required": true },
+        "onClose": { "type": "() => void", "required": true },
+        "side": { "type": "'left' | 'right' | 'top' | 'bottom'", "default": "right" },
+        "size": { "type": "'sm' | 'md' | 'lg' | 'full'", "default": "md" },
+        "variant": { "type": "'temporary' | 'persistent'", "default": "temporary", "notes": "temporary = scrim + modal (scrim/Escape close); persistent = no scrim, page stays interactive." },
+        "closeOnBackdrop": { "type": "boolean", "default": true, "notes": "Temporary only." },
+        "closeOnEscape": { "type": "boolean", "default": true },
+        "classes": { "type": "Partial<DrawerClasses>", "shape": ["backdrop", "drawer", "header", "closeButton", "body", "footer"] }
+      }
+    },
+    "Tooltip": {
+      "import": "import { Tooltip } from '@overdoser/react-toolkit'",
+      "element": "inline span wrapper + portaled bubble (role=tooltip)",
+      "notes": "Lightweight hover/focus label with delay. Use Popover for interactive/click content.",
+      "props": {
+        "content": { "type": "ReactNode", "required": true, "notes": "Nullish/empty → never shows." },
+        "children": { "type": "ReactNode", "required": true, "notes": "The trigger." },
+        "placement": { "type": "'top' | 'bottom' | 'left' | 'right'", "default": "top", "notes": "Flips on overflow." },
+        "delay": { "type": "number", "default": 300, "notes": "Open delay ms." },
+        "closeDelay": { "type": "number", "default": 0 },
+        "disabled": { "type": "boolean", "default": false },
+        "hideArrow": { "type": "boolean", "default": false },
+        "classes": { "type": "Partial<TooltipClasses>", "shape": ["wrapper", "tooltip", "arrow"] }
+      }
+    },
+    "Avatar": {
+      "import": "import { Avatar } from '@overdoser/react-toolkit'",
+      "element": "span",
+      "forwardsRef": true,
+      "extendsNativeProps": "span",
+      "notes": "Falls back to initials (from name) or a user icon if the image is missing or errors.",
+      "props": {
+        "src": { "type": "string" },
+        "alt": { "type": "string" },
+        "name": { "type": "string", "notes": "Used to derive initials." },
+        "fallback": { "type": "ReactNode" },
+        "size": { "type": "'xs' | 'sm' | 'md' | 'lg' | 'xl'", "default": "md" },
+        "shape": { "type": "'circle' | 'square'", "default": "circle" },
+        "status": { "type": "'online' | 'offline' | 'away' | 'busy'" },
+        "classes": { "type": "Partial<AvatarClasses>", "shape": ["root", "image", "fallback", "status"] }
+      }
+    },
+    "Divider": {
+      "import": "import { Divider } from '@overdoser/react-toolkit'",
+      "element": "div[role=separator]",
+      "forwardsRef": true,
+      "extendsNativeProps": "div (without children)",
+      "props": {
+        "orientation": { "type": "'horizontal' | 'vertical'", "default": "horizontal" },
+        "variant": { "type": "'solid' | 'dashed' | 'dotted'", "default": "solid" },
+        "label": { "type": "ReactNode", "notes": "Horizontal only." },
+        "labelPosition": { "type": "'start' | 'center' | 'end'", "default": "center" },
+        "classes": { "type": "Partial<DividerClasses>", "shape": ["root", "line", "label"] }
+      }
+    },
+    "Breadcrumbs": {
+      "import": "import { Breadcrumbs } from '@overdoser/react-toolkit'",
+      "element": "nav > ol",
+      "forwardsRef": true,
+      "compoundComponents": ["Breadcrumbs.Item"],
+      "notes": "Separators auto-inserted; the last item defaults to current (aria-current=page, no link).",
+      "props": {
+        "separator": { "type": "ReactNode", "default": "/" },
+        "label": { "type": "string", "default": "Breadcrumb" },
+        "classes": { "type": "Partial<BreadcrumbsClasses>", "shape": ["root", "list", "item", "link", "current", "separator"] }
+      },
+      "subComponentProps": {
+        "Breadcrumbs.Item": {
+          "href": { "type": "string", "notes": "Omit for a plain (non-link) crumb." },
+          "current": { "type": "boolean", "notes": "Renders as text with aria-current=page." }
+        }
+      }
+    },
+    "Pagination": {
+      "import": "import { Pagination } from '@overdoser/react-toolkit'",
+      "element": "nav > ul",
+      "forwardsRef": true,
+      "notes": "Windowed page list with ellipses, e.g. 1 … 6 7 8 9 10 … 99. Also exports paginationRange(page, count, boundaryCount?, siblingCount?). Table has its own pagination — use this for non-table lists.",
+      "props": {
+        "count": { "type": "number", "notes": "Total pages. Or use total + pageSize." },
+        "total": { "type": "number", "notes": "With pageSize, derives count." },
+        "pageSize": { "type": "number", "default": 10 },
+        "page": { "type": "number", "notes": "Controlled, 1-based." },
+        "defaultPage": { "type": "number", "default": 1 },
+        "onChange": { "type": "(page: number) => void" },
+        "boundaryCount": { "type": "number", "default": 1 },
+        "siblingCount": { "type": "number", "default": 2, "notes": "Defaults give at most 9 chips." },
+        "showPrevNext": { "type": "boolean", "default": true },
+        "showFirstLast": { "type": "boolean", "default": false },
+        "size": { "type": "'sm' | 'md' | 'lg'", "default": "md" },
+        "disabled": { "type": "boolean", "default": false },
+        "classes": { "type": "Partial<PaginationClasses>", "shape": ["root", "list", "item", "active", "ellipsis", "control"] }
+      }
+    },
+    "Slider": {
+      "import": "import { Slider } from '@overdoser/react-toolkit'",
+      "element": "div containing role=slider thumb(s)",
+      "forwardsRef": true,
+      "notes": "A tuple value makes it a range (two thumbs). Pointer drag + keyboard (arrows, Home/End, PageUp/Down).",
+      "props": {
+        "value": { "type": "number | [number, number]", "notes": "Tuple → range slider." },
+        "defaultValue": { "type": "number | [number, number]" },
+        "onChange": { "type": "(value: number | [number, number]) => void" },
+        "onChangeEnd": { "type": "(value: number | [number, number]) => void" },
+        "min": { "type": "number", "default": 0 },
+        "max": { "type": "number", "default": 100 },
+        "step": { "type": "number", "default": 1 },
+        "disabled": { "type": "boolean", "default": false },
+        "formatValue": { "type": "(value: number) => string", "notes": "For aria-valuetext." },
+        "classes": { "type": "Partial<SliderClasses>", "shape": ["root", "track", "range", "thumb"] }
+      }
+    },
+    "NumberInput": {
+      "import": "import { NumberInput } from '@overdoser/react-toolkit'",
+      "element": "div wrapping input + stepper buttons",
+      "forwardsRef": true,
+      "notes": "Emits onChange(value: number | null), so it binds directly inside FormField. Arrow keys step; clamps on blur.",
+      "props": {
+        "value": { "type": "number | null", "notes": "Controlled." },
+        "defaultValue": { "type": "number | null" },
+        "onChange": { "type": "(value: number | null) => void" },
+        "min": { "type": "number" },
+        "max": { "type": "number" },
+        "step": { "type": "number", "default": 1 },
+        "precision": { "type": "number", "notes": "Decimal places to round to." },
+        "inputSize": { "type": "'sm' | 'md' | 'lg'", "default": "md" },
+        "error": { "type": "boolean", "default": false },
+        "hideControls": { "type": "boolean", "default": false },
+        "classes": { "type": "Partial<NumberInputClasses>", "shape": ["root", "input", "controls", "increment", "decrement"] }
+      }
+    },
+    "DatePicker": {
+      "import": "import { DatePicker } from '@overdoser/react-toolkit'",
+      "element": "div wrapping a read-only input + calendar popover",
+      "forwardsRef": true,
+      "notes": "Single date with a pop-up calendar. Binds in FormField (value: Date | null). Keyboard: arrows move days, PageUp/Down change month, Home/End week ends, Enter selects, Esc closes.",
+      "props": {
+        "value": { "type": "Date | null", "notes": "Controlled." },
+        "defaultValue": { "type": "Date | null" },
+        "onChange": { "type": "(date: Date | null) => void" },
+        "min": { "type": "Date" },
+        "max": { "type": "Date" },
+        "disabledDate": { "type": "(date: Date) => boolean" },
+        "weekStartsOn": { "type": "number", "default": 0, "notes": "0 = Sunday." },
+        "locale": { "type": "string", "notes": "BCP-47 for month/weekday names." },
+        "format": { "type": "(date: Date) => string" },
+        "placeholder": { "type": "string", "default": "Select date" },
+        "inputSize": { "type": "'sm' | 'md' | 'lg'", "default": "md" },
+        "error": { "type": "boolean", "default": false },
+        "disabled": { "type": "boolean", "default": false },
+        "portal": { "type": "boolean", "default": true },
+        "classes": { "type": "Partial<DatePickerClasses>", "shape": ["root", "input", "icon", "popover", "header", "nav", "grid", "day", "daySelected", "dayToday", "dayOutside"] }
+      }
+    },
+    "Dropzone": {
+      "import": "import { Dropzone } from '@overdoser/react-toolkit'",
+      "element": "div[role=button] + hidden file input",
+      "forwardsRef": true,
+      "notes": "Drag-drop or click to browse. Emits accepted/rejected files; file-list UI is left to the consumer.",
+      "props": {
+        "onFiles": { "type": "(files: File[]) => void" },
+        "onReject": { "type": "(rejections: { file: File; reason: 'type' | 'size' | 'multiple' }[]) => void" },
+        "accept": { "type": "string", "notes": "Comma list of extensions and/or MIME patterns (e.g. '.png,image/*')." },
+        "multiple": { "type": "boolean", "default": false },
+        "maxSize": { "type": "number", "notes": "Max bytes per file." },
+        "disabled": { "type": "boolean", "default": false },
+        "label": { "type": "ReactNode" },
+        "hint": { "type": "ReactNode" },
+        "children": { "type": "ReactNode | ((state: { isDragging: boolean }) => ReactNode)", "notes": "Custom content; replaces the default UI." },
+        "classes": { "type": "Partial<DropzoneClasses>", "shape": ["root", "input", "content", "icon", "label", "hint"] }
+      }
+    },
+    "Timer": {
+      "import": "import { Timer } from '@overdoser/react-toolkit'",
+      "element": "div[role=timer]",
+      "forwardsRef": true,
+      "refHandle": "TimerHandle = { start(); pause(); reset(); restart(); getTime(): number; isRunning }",
+      "notes": "Countdown or stopwatch; digital, ring, or segments (one boxed cell per unit with the label below). Uncontrolled with autoStart + imperative ref, or display-only via value. Time values are in seconds; interval is ms.",
+      "props": {
+        "mode": { "type": "'countdown' | 'stopwatch'", "default": "countdown" },
+        "duration": { "type": "number", "notes": "Seconds; countdown length / stopwatch cap; drives ring progress." },
+        "to": { "type": "Date | number", "notes": "Absolute countdown target (overrides duration/pause)." },
+        "value": { "type": "number", "notes": "Controlled seconds → display-only (no internal clock)." },
+        "autoStart": { "type": "boolean", "default": true },
+        "running": { "type": "boolean", "notes": "Controlled run state." },
+        "interval": { "type": "number", "default": 1000, "notes": "Tick ms." },
+        "variant": { "type": "'digital' | 'ring' | 'segments'", "default": "digital" },
+        "size": { "type": "'sm' | 'md' | 'lg'", "default": "md" },
+        "format": { "type": "(seconds: number) => ReactNode", "notes": "digital/ring only." },
+        "units": { "type": "('days' | 'hours' | 'minutes' | 'seconds')[]", "notes": "segments variant; default = smallest set that fits the duration; leading unit absorbs overflow." },
+        "unitFormat": { "type": "'long' | 'short'", "default": "short", "notes": "short → d/h/m/s; long → days/hours/minutes/seconds (fixed, no singular/plural)." },
+        "unitLabels": { "type": "Partial<Record<TimerUnit, ReactNode | ((value: number) => ReactNode)>>", "notes": "Override unit labels." },
+        "segmentVariant": { "type": "'boxed' | 'plain'", "default": "boxed", "notes": "boxed = square with number, unit below." },
+        "renderSegment": { "type": "(segment: TimerSegment, index: number) => ReactNode", "notes": "Custom per-cell rendering; TimerSegment = { unit, value, text, label }." },
+        "segmentSeparator": { "type": "ReactNode", "notes": "Content between cells, e.g. ':'." },
+        "label": { "type": "ReactNode" },
+        "labelPlacement": { "type": "'top' | 'bottom' | 'left' | 'right'", "default": "bottom" },
+        "onComplete": { "type": "() => void", "notes": "Countdown reaches zero." },
+        "onTick": { "type": "(seconds: number) => void" },
+        "classes": { "type": "Partial<TimerClasses>", "shape": ["root", "display", "label", "ringTrack", "ringProgress", "segments", "segment", "segmentValue", "segmentLabel"] }
+      }
+    },
     "Modal": {
       "import": "import { Modal } from '@overdoser/react-toolkit'",
       "element": "div (portal at document.body)",
@@ -816,9 +1357,15 @@
         "label": {
           "type": "ReactNode"
         },
+        "variant": {
+          "type": "'checkbox' | 'switch'",
+          "default": "checkbox",
+          "notes": "switch renders a sliding toggle; the underlying input[type=checkbox] is identical."
+        },
         "indeterminate": {
           "type": "boolean",
-          "default": false
+          "default": false,
+          "notes": "Ignored when variant=switch."
         },
         "classes": {
           "type": "Partial<CheckboxClasses>",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overdoser/react-toolkit",
-  "version": "0.1.0",
+  "version": "0.5.0",
   "type": "module",
   "main": "./index.js",
   "module": "./index.js",