@overdoser/react-toolkit 0.0.16 → 0.5.0

package/AGENTS.md

@@ -19,6 +19,11 @@ For exhaustive component reference (every prop, every variant, every signature),
    import '@overdoser/react-toolkit/theme.css';
    ```
    Without this, components render unstyled.
+   - **Want `className` / `classes.*` overrides to always win regardless of bundler order?** Import the layered twin instead:
+     ```ts
+     import '@overdoser/react-toolkit/theme.layered.css';
+     ```
+     It wraps all toolkit CSS in a `crk` cascade layer, so any of your own *unlayered* rules beat it deterministically. See "Customizing styles" below.
 
 ## Import rules
 
@@ -44,12 +49,40 @@ For exhaustive component reference (every prop, every variant, every signature),
   - Multi-pick with chips → `<Select multiple options={...} onValuesChange={...} />`.
   - You want it to look like a "menu trigger" instead of a form input → `<Dropdown options={...} value={...} onChange={...} />` (select-mode dropdown).
 
+- **Need to pick several values from a small fixed set?** → `<CheckboxGroup options={...} value={...} onChange={...} />` (a checkbox list, or `variant="chips"` for toggle chips). For a large/searchable set, prefer `<Select multiple>` instead.
+
 - **Need a menu (Edit / Delete / Archive)?** → `<Dropdown trigger={...}>` with `<DropdownItem>` children.
 
 - **Need a tooltip / hover card / contextual panel?** → `<Popover trigger={...} content={...} />`.
 
 - **Need a confirm prompt or a full dialog?** → `<Modal>` with `Modal.Header`/`Body`/`Footer`. Always provide either `aria-label` or use a `Modal.Header` (it's auto-wired as `aria-labelledby`).
 
+- **Need a slide-in side panel?** → `<Drawer open onClose side="right">` with `Drawer.Header`/`Body`/`Footer`. Same focus-trap/scroll-lock/Escape behavior as `Modal`, but anchored to a screen edge. Use `Modal` for centered dialogs, `Drawer` for side panels.
+
+- **Need a hover/focus hint label?** → `<Tooltip content="…">{trigger}</Tooltip>` — lightweight, delayed, non-interactive. For click-triggered or interactive floating content use `Popover` instead.
+
+- **Need a user avatar?** → `<Avatar src name status />` (initials/icon fallback). **A separator?** → `<Divider>` (add `label` for a centered caption; `orientation="vertical"` inside a flex row). **Breadcrumb trail?** → `<Breadcrumbs>` with `Breadcrumbs.Item` (last item auto-marked `current`).
+
+- **Need standalone page navigation?** → `<Pagination count={…} page={…} onChange={…} />` (windowed with ellipses, ≤9 chips by default; `total`+`pageSize` instead of `count` also works). Note: `Table` already has its own built-in pagination — only use `Pagination` for non-table lists.
+
+- **Need a numeric/range input?** → `<Slider>` (single number, or a `[lo, hi]` tuple for a range) for choosing along a continuum; `<NumberInput>` for an exact number with steppers (`onChange(number | null)`, binds in `FormField`).
+
+- **Need a date input?** → `<DatePicker value onChange min max disabledDate />` — pop-up calendar, single date, binds in `FormField` (`value: Date | null`).
+
+- **Need file upload?** → `<Dropzone onFiles accept maxSize multiple />` — drag-drop or click; it emits accepted/rejected files but leaves the file-list UI to you.
+
+- **Need a countdown / stopwatch / elapsed display?** → `<Timer mode="countdown|stopwatch" duration={…} variant="digital|ring" label="…" />`. Drive it with `autoStart` + an imperative ref (`start`/`pause`/`reset`/`restart`), or make it display-only with `value`.
+
+- **Need a movable panel / floating widget the user can drag around?** → `<Draggable>` wrapping any content. Add a `<Draggable.Handle>` (e.g. a title bar) to restrict the grab area; without one the whole surface drags. Uncontrolled by default (`defaultPosition`); pass `position` + `onDrag` to control it. It's a free-move/reposition primitive — not a sortable list or drag-and-drop-between-zones helper.
+
+- **Need transient notifications (toasts)?** → Mount `<ToastProvider>` once near the root (sets `position` / `duration` / `max`); it's the renderer and owns the portal/stack — do NOT render toast JSX yourself. To trigger, import the standalone `toast({ variant, title, description })` and call it from anywhere (no hook/context needed); `toast.dismiss(id)` / `toast.dismissAll()` are attached. A `useToast()` hook returns the same `{ toast, dismiss, dismissAll }` if you prefer hook style.
+
+- **Need to switch between sections of content?** → `<Tabs>` with `Tabs.List` / `Tabs.Tab` / `Tabs.Panel`. Each `Tab` and its `Panel` share a `value`. Uncontrolled via `defaultValue` or controlled via `value` + `onValueChange`. Keyboard nav is built in.
+
+- **Need an inline status message?** → `<Alert variant="info|success|warning|danger">`. Add `title` for a heading, `onClose` to make it dismissible. For *transient* feedback prefer Toast; use Alert for persistent, in-flow messaging.
+
+- **Need a status pill / count / tag?** → `<Badge>`. For loading states: `<Spinner>` (indeterminate activity, inherits text color) and `<Skeleton>` (content placeholder — `variant="text|circle|rect"`, `lines` for multi-line text).
+
 - **Need a data table?** → `<Table>`.
   - All data in memory → don't pass `onSort`; pass `pagination` (without `totalRows`) for client-side paging.
   - Data from a server → pass `sortConfig` + `onSort`, and `pagination` with `totalRows`.
@@ -96,6 +129,26 @@ For exhaustive component reference (every prop, every variant, every signature),
 </FormField>
 ```
 
+### Wire a CheckboxGroup (multi-value) inside a Form
+```tsx
+<FormField name="interests" label="Interests" rules={{ validate: (v) => v.length > 0 || 'Pick at least one' }}>
+  <CheckboxGroup
+    variant="chips" // or omit for a checkbox list
+    options={[
+      { value: 'design', label: 'Design' },
+      { value: 'eng', label: 'Engineering' },
+    ]}
+  />
+</FormField>
+```
+`CheckboxGroup` binds `value: string[]` / `onChange(values)` directly — no bridge needed.
+
+## Customizing styles
+
+- **Theme tokens:** override `--crk-*` custom properties on `:root` (colors, fonts, spacing, radii). This is the primary, stable customization surface.
+- **Per-element overrides:** use each component's `classes` prop (and `className`) — internal class names are hashed and unstable, so never target them directly.
+- **Make overrides deterministic:** `className` / `classes.*` are plain CSS classes; they only beat the toolkit's built-in class if your stylesheet is inserted *after* it, which the bundler controls. To guarantee precedence, import `@overdoser/react-toolkit/theme.layered.css` (everything ships in a `crk` cascade layer, so your unlayered rules always win), **or** add `@import '@overdoser/react-toolkit/theme.css' layer(crk);` as the first line of your global CSS. Caveat: an aggressive global reset that is itself unlayered will then also override the toolkit's base styles — put your reset in its own earlier layer if so. `theme.css` and `theme.layered.css` are identical except the layer wrapper — import exactly one, and token (`--crk-*`) theming works the same in either.
+
 ## Recipes
 
 Full copy-paste-able files live alongside this doc. Each is one self-contained file that you can drop into a project. Adjust types/imports for your codebase.

package/CHANGELOG.md

@@ -0,0 +1,226 @@
+# Changelog
+
+All notable changes to `@overdoser/react-toolkit` are documented here.
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
+project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.5.0]
+
+Adds a segmented `Timer` display and reworked `Drawer` motion/variants, and —
+importantly — fixes a build-config bug that broke variant styling in the
+published package.
+
+### Fixed
+
+- **Published variant styles were missing.** The library was built with CSS
+  Modules `localsConvention: 'camelCaseOnly'`, which dropped the original class
+  keys from the exported map. Components look classes up by their literal name
+  (e.g. `styles['side_left']`, `styles['pos_top-right']`), so in the **built
+  package** those lookups returned `undefined` and the rules never applied —
+  affecting `Drawer` (side/position + animation), `Tabs` (`line`/`solid`/`pill`),
+  `Toast` (positions), `Timer` (label placement), and `Avatar` (status dot).
+  Switched to `camelCase` (keeps both key forms). Tests were unaffected because
+  the test env keeps literal keys, so this only surfaced in consuming apps.
+- **`Drawer` slide animation** now plays reliably in both directions. The open
+  was animating like a fade and the close slid the wrong way; it now uses
+  per-side keyframes applied as a single, unambiguous class.
+- **`Drawer` closes back the way it opened** even when the consumer resets the
+  `side` prop while toggling `open` (the common `side={side ?? 'right'}`
+  pattern). The opened side/size are frozen for the duration of the close.
+- **`Pagination`** active-page flicker removed — the selected chip no longer
+  cross-fades its background and text colour (the active state now applies
+  instantly; only hover backgrounds transition).
+- **`Draggable`** prop types: `onDragStart`/`onDragEnd` no longer conflict with
+  the native `div` drag handlers (both are now omitted from the extended props).
+
+### Added
+
+- **`Timer` `variant="segments"`** — one cell per unit (days/hours/minutes/
+  seconds) with the unit label under each number. `units` selects which cells
+  (the leading unit absorbs overflow), `unitFormat` (`short` → `d/h/m/s`,
+  `long` → `days/hours/minutes/seconds`, fixed — no singular/plural),
+  `unitLabels` overrides, `segmentVariant` (`boxed`/`plain`), `renderSegment`
+  for fully custom cells, and `segmentSeparator`. New `TimerUnit` / `TimerSegment`
+  exports.
+- **`Drawer` `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. Replaces the
+  short-lived `backdrop` prop. The scrim is also lighter, and the panel slides
+  with a drawer-style easing.
+
+## [0.4.0]
+
+Eleven new components spanning overlays, navigation, inputs, and a flexible
+timer. Fully additive — no breaking changes.
+
+### Added
+
+- **`Drawer`** — off-canvas panel sliding from any edge (`left`/`right`/`top`/
+  `bottom`), with `Drawer.Header`/`Body`/`Footer`, focus trap, scroll lock, and
+  Escape/backdrop close (same family as `Modal`).
+- **`Tooltip`** — lightweight hover/focus label with an open `delay`, viewport
+  flipping, Escape-to-close, and `aria-describedby` wiring.
+- **`Avatar`** — image with initials/icon fallback, five sizes, circle/square,
+  and a presence `status` dot.
+- **`Divider`** — horizontal/vertical separator with an optional centered label.
+- **`Breadcrumbs`** / **`Breadcrumbs.Item`** — breadcrumb nav with auto
+  separators and `aria-current` on the current crumb.
+- **`Pagination`** — windowed page navigation with ellipses
+  (`1 … 6 7 8 9 10 … 99`; at most 9 chips by default), prev/next and optional
+  first/last controls. Accepts `count` or `total` + `pageSize`. Also exports the
+  pure `paginationRange()` helper.
+- **`Slider`** — single- or dual-thumb (range) input with pointer drag and full
+  keyboard support (arrows, Home/End, PageUp/Down).
+- **`NumberInput`** — numeric field with stepper buttons, min/max clamping,
+  arrow-key stepping, and `precision`. Emits `onChange(number | null)`, so it
+  binds directly in `FormField`.
+- **`DatePicker`** — date field with a pop-up calendar: single-date selection,
+  full keyboard navigation, `min`/`max`, `disabledDate`, `weekStartsOn`, and
+  locale-aware labels. Binds in `FormField` (`value: Date | null`).
+- **`Dropzone`** — file upload via drag-and-drop or click, with `accept` and
+  `maxSize` validation (`onFiles` / `onReject`); the file-list UI is left to you.
+- **`Timer`** — countdown or stopwatch, rendered as digits or a progress ring,
+  with an attachable `label`. Drive it uncontrolled (`autoStart` + an imperative
+  `TimerHandle` ref: `start`/`pause`/`reset`/`restart`), bind to a target date
+  (`to`), or make it display-only with `value`. Fires `onComplete`/`onTick`.
+
+### Docs
+
+- `README`, `llms.txt`, `manifest.json`, and `AGENTS.md` updated for all eleven
+  components (table rows, full prop reference, and decision-flow guidance).
+
+## [0.3.1]
+
+### Fixed
+
+- **`Badge`** text now sits vertically centered in the pill. It was the only
+  pill-shaped element using `line-height: 1`, which rendered the glyph optically
+  high; it now matches the `Button`/chip pattern (`box-sizing: border-box`,
+  `justify-content: center`, `line-height` tight).
+
+## [0.3.0]
+
+Six new components covering feedback, navigation, and loading states. Additive —
+the only behavior note is an internal change to `useToast` (see below).
+
+### Added
+
+- **`Toast`** — imperative notification system backed by a global store. Mount
+  `<ToastProvider>` once (it's the renderer); trigger with the standalone
+  `toast(options)` (importable, no hook/context needed — also `toast.dismiss(id)`
+  / `toast.dismissAll()`) or the `useToast()` hook, which returns the same
+  `{ toast, dismiss, dismissAll }`. Variants (`neutral | info | success |
+  warning | danger`), six `position`s, `duration` / `max`, auto-dismiss that
+  pauses on hover, and assertive vs. polite live regions by variant. Firing a
+  toast with no provider mounted logs a dev warning instead of failing silently.
+- **`Tabs`** — accessible tabs via `Tabs.List` / `Tabs.Tab` / `Tabs.Panel`
+  (linked by matching `value`). `line` / `solid` / `pill` variants, horizontal
+  or vertical, controlled or uncontrolled, full keyboard navigation (arrows +
+  Home/End, roving tabindex), and a `keepMounted` panel option.
+- **`Alert`** — inline status message (`info | success | warning | danger`) with
+  optional `title`, default/overridable/hidden `icon`, and an optional dismiss
+  button.
+- **`Badge`** — status pill with 5 variants, `soft` / `solid` / `outline`
+  appearance, three sizes, and an optional status `dot`.
+- **`Spinner`** — indeterminate loading spinner that inherits `currentColor`,
+  with a visually-hidden a11y `label`.
+- **`Skeleton`** — loading placeholder (`text` with multi-`lines`, `circle`,
+  `rect`); `pulse` / `wave` / `none` animation; respects reduced motion.
+
+### Changed
+
+- **`useToast()` no longer throws when called outside a `ToastProvider`.** Toast
+  state now lives in a global store, so the hook (and the new standalone
+  `toast()`) work anywhere; the provider is purely the renderer. If you relied on
+  the previous throw to detect a missing provider, note that `toast()` now warns
+  in development instead.
+
+## [0.2.0]
+
+Additive release — a new `Draggable` container and a toggle-switch style for
+`Checkbox`. No breaking changes; no default behavior changed.
+
+### Added
+
+- **`Draggable` component** — a free-move container that wraps any children and
+  can be dragged anywhere on screen. Position is a `translate(x, y)` offset from
+  the element's natural layout position. Add a `<Draggable.Handle>` to restrict
+  the grab area (e.g. a title bar); without one, the whole surface drags, and a
+  focused handle is keyboard-movable (arrow keys). Props: `defaultPosition` /
+  `position` (uncontrolled / controlled), `axis` (`both | x | y`), `bounds`
+  (`viewport | parent | none`), `keyboardStep`, `disabled`, `onDragStart` /
+  `onDrag` / `onDragEnd`, and a `classes` override (`{ root, handle }`).
+- **`Checkbox` `variant` prop** (`'checkbox' | 'switch'`, default `'checkbox'`).
+  `'switch'` renders a sliding toggle; the underlying `<input type="checkbox">`
+  (a11y + form behavior) is identical, so it binds inside `FormField` unchanged.
+  `indeterminate` is ignored for switches.
+
+## [0.1.0]
+
+This release adds a `CheckboxGroup` component, a cascade-layered stylesheet for
+deterministic style overrides, and viewport-aware popovers — plus a round of
+`Form` ergonomics. A few **defaults changed** (forms, popovers, links); they are
+all opt-out (see ⚠️ below).
+
+### ⚠️ Notable default changes (visual)
+
+No API was removed or renamed, but some components now **render differently by
+default**. To restore the previous behavior:
+
+- **Forms reserve space for validation messages** so an error no longer shifts
+  the layout, the error now appears *between the input and the description*
+  (instead of replacing the description), inter-field/element gaps are tighter,
+  and labels are bolder (weight 700). Opt out per field or form-wide with
+  `reserveErrorSpace={false}`.
+- **Popovers reposition to stay in the viewport** (flip to the opposite side /
+  shift near a screen edge). Opt out with `<Popover autoPosition={false} />`.
+- **Links that open in a new tab show an inline ↗ icon** (`external` or a manual
+  `target="_blank"`). Opt out with `<Link hideExternalIcon />`.
+- `theme.css` is **unchanged** — the new cascade layer is opt-in via
+  `theme.layered.css`, so existing stylesheet imports are unaffected.
+
+### Added
+
+- **`CheckboxGroup` component** — multi-value selection from a fixed option set,
+  rendered as a checkbox list (`variant="checkbox"`, default) or toggleable chips
+  (`variant="chips"`). Supports `chipShape` (`pill | rounded | square`),
+  `chipCheckmark` (with constant chip width — padding compensates for the mark),
+  `orientation`, `disabled`, `error`, `name`, `required`, and a `classes`
+  override (`{ group, option, chip, chipSelected }`). Binds directly inside
+  `FormField` (`value: string[]` / `onChange(values)`), no bridge needed.
+- **`theme.layered.css` stylesheet export** — identical to `theme.css` but
+  wrapped in a `@layer crk` cascade layer, so consumer `className` / `classes.*`
+  overrides win deterministically regardless of bundler import order. Import
+  exactly one of the two.
+- **`Form` props** `reserveErrorSpace` (form-wide default for all fields) and
+  `fieldClasses` (form-wide `classes` default, merged with each field's own).
+- **`FormField` prop** `reserveErrorSpace` (`boolean | number | string`) and a
+  `--crk-field-error-min-height` token to size the reserved space.
+- **`Popover` prop** `autoPosition` (default `true`) for viewport-aware flipping
+  and edge shifting.
+- **`Link` prop** `hideExternalIcon` to suppress the new-tab icon.
+- `FormFieldClasses` gained a `message` key (the validation/reserve slot).
+
+### Changed
+
+- `FormField` validation layout reworked so the field's outer height stays
+  constant when a one-line error toggles (the reserved spacer sits after the
+  description and swaps 1:1 with the error). Multi-line errors grow past it.
+- Form-wide reservation off (`<Form reserveErrorSpace={false}>`) uses a slightly
+  larger inter-field gap to compensate for the absent reserved line.
+
+### Fixed
+
+- **Searchable single-select** dropdown was mispositioned / rendered as a ~1px
+  sliver in portal mode because it anchored to the trigger button (hidden while
+  open); it now anchors to the always-visible wrapper.
+- **Native `Select`** silently dropped `onValueChange` and could trip React's
+  controlled-field warning when given `value` + `onValueChange`; it now wires
+  both `onChange` and `onValueChange`.
+
+### Docs
+
+- `README`, `llms.txt`, `manifest.json`, and `AGENTS.md` updated for all of the
+  above, including a `theme.css` vs `theme.layered.css` comparison and the
+  cascade-layer caveat (an unlayered global reset also beats layered toolkit
+  styles — put resets in an earlier layer).

package/README.md

@@ -28,22 +28,97 @@ Override `--crk-*` CSS custom properties to customize the theme:
 }
 ```
 
+For per-element tweaks, every component accepts `className` and a `classes` prop
+(internal class names are hashed — never target them directly).
+
+### `theme.css` vs `theme.layered.css`
+
+The package ships two stylesheets with **identical content** — same rules, same
+hashed class names, same `--crk-*` tokens. The only difference is that
+`theme.layered.css` wraps everything in a CSS cascade layer:
+
+```css
+@layer crk {
+  /* ...the entire stylesheet... */
+}
+```
+
+That wrapper changes how your overrides compete with the toolkit's styles.
+Import **exactly one** of the two (never both).
+
+**The problem with plain `theme.css`.** The overrides you pass via `className` /
+`classes.*` are plain CSS classes, so they tie with the toolkit's own class on
+specificity — the winner is decided by **stylesheet source order**, which your
+bundler controls. In many setups the toolkit CSS is injected *after* your app
+CSS, so your overrides silently lose.
+
+**What the layer fixes.** A core rule of cascade layers: **any unlayered style
+beats any layered style, regardless of specificity or import order.** Since
+`theme.layered.css` puts the whole toolkit in the `crk` layer, your own
+(unlayered) rules — including every `className` / `classes.*` override — always
+win, deterministically:
+
+```ts
+import '@overdoser/react-toolkit/theme.layered.css'; // instead of theme.css
+```
+
+(If you import CSS from a `.css` entry instead of JS, the equivalent is
+`@import '@overdoser/react-toolkit/theme.css' layer(crk);` as the first line.)
+
+| | `theme.css` | `theme.layered.css` |
+| --- | --- | --- |
+| Override wins by | specificity, then import order (bundler-dependent) | **always** (unlayered beats layered) |
+| `--crk-*` token theming | ✅ | ✅ (identical) |
+| Affected by a global CSS reset | only via normal specificity/order | ⚠️ an *unlayered* reset also beats the toolkit's base styles |
+
+**The one caveat.** Because layered styles lose to *all* unlayered styles, an
+aggressive global reset (e.g. `button { font: inherit }`) would also override the
+toolkit's base styles under `theme.layered.css`. If you ship a heavy reset, put
+it in its own earlier layer so the order is explicit:
+
+```css
+@layer reset, crk;
+```
+
+**Rule of thumb:** if you heavily customize component internals via
+`classes` / `className`, use `theme.layered.css`. Otherwise `theme.css` is fine.
+Theme-token (`--crk-*`) overrides work the same in both.
+
 ## Components
 
 | Component | Description |
 | --- | --- |
 | **Button** | Variants: `primary`, `secondary`, `danger`, `ghost`. Multiple sizes. Loading states with `dots`, `shimmer`, and `border` animations. |
-| **Link** | Styled link with variants and external link support. |
+| **Link** | Styled link with variants and external link support (inline new-tab icon, toggleable). |
 | **Typography** | Renders `h1`-`h6`, `p`, `span`, `label`. Supports `weight`, `color`, `align`, and `truncate`. |
 | **List / ListItem** | Ordered and unordered lists with configurable spacing. |
 | **Table** | Sortable columns, multi-sort with Ctrl+click, pagination, and server-side sort support. |
 | **Dropdown** | Menu dropdown with chevron indicator. Also works as a selectable form input with `options`, `value`, and `onChange`. |
-| **Popover** | Positioned popover anchored to a trigger element. |
+| **Popover** | Positioned popover anchored to a trigger element, with viewport-aware auto-flip. |
 | **Modal** | Portal-based modal with `Header`, `Body`, and `Footer` compound components. Includes focus trap and escape/backdrop close. |
+| **Draggable** | Free-move container for any content. Optional `Draggable.Handle`, axis lock, viewport/parent bounds, keyboard moves. |
+| **Toast** | Imperative notifications: `ToastProvider` renders, standalone `toast()` (or `useToast()`) triggers. Variants, positions, auto-dismiss with hover-pause. |
+| **Tabs** | Accessible tabs (`Tabs.List` / `Tabs.Tab` / `Tabs.Panel`). Line/solid/pill variants, vertical, keyboard nav. |
+| **Alert** | Inline status message (info/success/warning/danger) with optional title, icon, and dismiss. |
+| **Badge** | Small status pill. Variants, `soft`/`solid`/`outline` appearance, sizes, optional status dot. |
+| **Spinner** | Indeterminate loading spinner; inherits `currentColor`. |
+| **Skeleton** | Loading placeholder — text (multi-line), circle, or rect; pulse/wave animation. |
+| **Drawer** | Off-canvas panel sliding from any edge. `Header`/`Body`/`Footer`, focus trap, Escape/backdrop close. |
+| **Tooltip** | Lightweight hover/focus label with open delay and viewport-aware flipping. |
+| **Avatar** | Image with initials/icon fallback, sizes, circle/square, presence dot. |
+| **Divider** | Horizontal/vertical separator, optional centered label. |
+| **Breadcrumbs** | Breadcrumb nav with auto separators and `aria-current`. |
+| **Pagination** | Windowed page nav with ellipses (`1 … 6 7 8 9 10 … 99`), prev/next/first/last. |
+| **Slider** | Single or dual-thumb range input; pointer + keyboard. |
+| **NumberInput** | Numeric field with steppers, min/max clamp, arrow-key step. |
+| **Dropzone** | File upload via drag-drop or click, with `accept`/`maxSize` validation. |
+| **Timer** | Countdown/stopwatch, digital or ring, attachable label, imperative controls. |
+| **DatePicker** | Date field with a pop-up calendar, keyboard nav, min/max and disabled days. |
 | **Form / FormField** | Form wrapper with react-hook-form integration. |
 | **Input** | Text input with sizes, error state, and prefix/suffix slots. |
 | **Select** | Native `<select>` with a custom arrow indicator. |
-| **Checkbox** | Checkbox with label and indeterminate state support. |
+| **Checkbox** | Checkbox with label and indeterminate state support; `variant="switch"` for a toggle switch. |
+| **CheckboxGroup** | Multi-value selection as a checkbox list or toggleable chips. |
 | **Radio / RadioGroup** | Context-based radio group. |
 | **Textarea** | Textarea with resize control. |
 
@@ -95,6 +170,30 @@ function LoginForm() {
 }
 ```
 
+### Toast
+
+Mount `ToastProvider` once (it's the renderer), then fire notifications with the
+standalone `toast()` — no hook or context required:
+
+```tsx
+import { ToastProvider, toast, Button } from '@overdoser/react-toolkit';
+
+function App() {
+  return (
+    <ToastProvider position="top-right">
+      <Button onClick={() => toast({ variant: 'success', title: 'Saved', description: 'All set.' })}>
+        Save
+      </Button>
+    </ToastProvider>
+  );
+}
+```
+
+`toast()` is importable and callable from anywhere (event handlers, utilities,
+outside React). It returns an id and exposes `toast.dismiss(id)` /
+`toast.dismissAll()`. A `useToast()` hook returning the same
+`{ toast, dismiss, dismissAll }` is also available if you prefer.
+
 ## Peer Dependencies
 
 - `react` >= 18

package/components/Alert/Alert.d.ts

@@ -0,0 +1,34 @@
+import { ComponentPropsWithRef, ReactNode } from 'react';
+export type AlertVariant = 'info' | 'success' | 'warning' | 'danger';
+export interface AlertClasses {
+    root: string;
+    icon: string;
+    content: string;
+    title: string;
+    message: string;
+    close: string;
+}
+export interface AlertProps extends Omit<ComponentPropsWithRef<'div'>, 'title'> {
+    /** Color/semantics. @default 'info' */
+    variant?: AlertVariant;
+    /** Optional bold heading above the message. */
+    title?: ReactNode;
+    /** Leading status icon. Pass a node to override, or `false` to hide. @default true */
+    icon?: ReactNode | boolean;
+    /** When provided, renders a dismiss "×" button that calls this handler. */
+    onClose?: () => void;
+    /** Accessible label for the dismiss button. @default 'Dismiss' */
+    closeLabel?: string;
+    /** Override class names on internal elements. */
+    classes?: Partial<AlertClasses>;
+}
+/**
+ * Inline status message — info, success, warning, or danger. Optionally titled,
+ * dismissible, and with a leading icon.
+ *
+ * @example
+ * <Alert variant="success" title="Saved" onClose={() => setShown(false)}>
+ *   Your changes were saved.
+ * </Alert>
+ */
+export declare const Alert: import('react').ForwardRefExoticComponent<Omit<AlertProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;

package/components/Alert/index.d.ts

@@ -0,0 +1,2 @@
+export { Alert } from './Alert';
+export type { AlertProps, AlertClasses, AlertVariant } from './Alert';

package/components/Avatar/Avatar.d.ts

@@ -0,0 +1,36 @@
+import { ComponentPropsWithRef, ReactNode } from 'react';
+export type AvatarStatus = 'online' | 'offline' | 'away' | 'busy';
+export interface AvatarClasses {
+    root: string;
+    image: string;
+    fallback: string;
+    status: string;
+}
+export interface AvatarProps extends Omit<ComponentPropsWithRef<'span'>, 'children'> {
+    /** Image URL. If it fails to load (or is omitted), the initials/icon fallback shows. */
+    src?: string;
+    /** Alt text for the image and accessible name for the fallback. */
+    alt?: string;
+    /** Full name; used to derive initials when no image is available. */
+    name?: string;
+    /** Explicit fallback content (overrides derived initials). */
+    fallback?: ReactNode;
+    /** Avatar size. @default 'md' */
+    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    /** Outer shape. @default 'circle' */
+    shape?: 'circle' | 'square';
+    /** Presence indicator dot. */
+    status?: AvatarStatus;
+    /** Override class names on internal elements. */
+    classes?: Partial<AvatarClasses>;
+}
+/**
+ * User avatar with image, initials fallback, and an optional presence dot.
+ * Falls back to initials (from `name`) or a generic icon if the image is
+ * missing or fails to load.
+ *
+ * @example
+ * <Avatar src="/me.jpg" name="Ada Lovelace" />
+ * <Avatar name="Ada Lovelace" status="online" />
+ */
+export declare const Avatar: import('react').ForwardRefExoticComponent<Omit<AvatarProps, "ref"> & import('react').RefAttributes<HTMLSpanElement>>;

package/components/Avatar/index.d.ts

@@ -0,0 +1,2 @@
+export { Avatar } from './Avatar';
+export type { AvatarProps, AvatarClasses, AvatarStatus } from './Avatar';

package/components/Badge/Badge.d.ts

@@ -0,0 +1,25 @@
+import { ComponentPropsWithRef } from 'react';
+export interface BadgeClasses {
+    root: string;
+    dot: string;
+}
+export interface BadgeProps extends ComponentPropsWithRef<'span'> {
+    /** Color intent. @default 'neutral' */
+    variant?: 'neutral' | 'primary' | 'success' | 'warning' | 'danger';
+    /** Fill style — `soft` (tinted), `solid` (filled), or `outline`. @default 'soft' */
+    appearance?: 'soft' | 'solid' | 'outline';
+    /** Badge size. @default 'md' */
+    size?: 'sm' | 'md' | 'lg';
+    /** Render a leading status dot. @default false */
+    dot?: boolean;
+    /** Override class names on internal elements. */
+    classes?: Partial<BadgeClasses>;
+}
+/**
+ * Small inline status pill for labels, counts, and states.
+ *
+ * @example
+ * <Badge variant="success" dot>Active</Badge>
+ * <Badge variant="primary" appearance="solid">3</Badge>
+ */
+export declare const Badge: import('react').ForwardRefExoticComponent<Omit<BadgeProps, "ref"> & import('react').RefAttributes<HTMLSpanElement>>;

package/components/Badge/index.d.ts

@@ -0,0 +1,2 @@
+export { Badge } from './Badge';
+export type { BadgeProps, BadgeClasses } from './Badge';

package/components/Breadcrumbs/Breadcrumbs.d.ts

@@ -0,0 +1,44 @@
+import { ComponentPropsWithRef, ReactNode } from 'react';
+export interface BreadcrumbsClasses {
+    root: string;
+    list: string;
+    item: string;
+    link: string;
+    current: string;
+    separator: string;
+}
+export interface BreadcrumbsProps extends Omit<ComponentPropsWithRef<'nav'>, 'children'> {
+    /** `Breadcrumbs.Item` children. Separators are inserted automatically. */
+    children?: ReactNode;
+    /** Separator between items. @default '/' */
+    separator?: ReactNode;
+    /** Accessible label for the nav landmark. @default 'Breadcrumb' */
+    label?: string;
+    /** Override class names on internal elements. */
+    classes?: Partial<BreadcrumbsClasses>;
+}
+export interface BreadcrumbItemProps extends Omit<ComponentPropsWithRef<'li'>, 'children'> {
+    /** Link target. Omit for a plain (non-link) crumb. */
+    href?: string;
+    /** Marks the current page — rendered as text with `aria-current="page"`. @default false */
+    current?: boolean;
+    children?: ReactNode;
+}
+export declare function BreadcrumbItem({ href, current, children, className, ...rest }: BreadcrumbItemProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace BreadcrumbItem {
+    var displayName: string;
+}
+/**
+ * Breadcrumb navigation. Compose with `Breadcrumbs.Item`; the last item is
+ * typically `current`. Separators are inserted automatically.
+ *
+ * @example
+ * <Breadcrumbs>
+ *   <Breadcrumbs.Item href="/">Home</Breadcrumbs.Item>
+ *   <Breadcrumbs.Item href="/library">Library</Breadcrumbs.Item>
+ *   <Breadcrumbs.Item current>Data</Breadcrumbs.Item>
+ * </Breadcrumbs>
+ */
+export declare const Breadcrumbs: import('react').ForwardRefExoticComponent<Omit<BreadcrumbsProps, "ref"> & import('react').RefAttributes<HTMLElement>> & {
+    Item: typeof BreadcrumbItem;
+};

package/components/Breadcrumbs/index.d.ts

@@ -0,0 +1,2 @@
+export { Breadcrumbs, BreadcrumbItem } from './Breadcrumbs';
+export type { BreadcrumbsProps, BreadcrumbItemProps, BreadcrumbsClasses } from './Breadcrumbs';

package/components/Divider/Divider.d.ts

@@ -0,0 +1,28 @@
+import { ComponentPropsWithRef, ReactNode } from 'react';
+export interface DividerClasses {
+    root: string;
+    line: string;
+    label: string;
+}
+export interface DividerProps extends Omit<ComponentPropsWithRef<'div'>, 'children'> {
+    /** Layout direction. @default 'horizontal' */
+    orientation?: 'horizontal' | 'vertical';
+    /** Line style. @default 'solid' */
+    variant?: 'solid' | 'dashed' | 'dotted';
+    /** Optional centered label (horizontal only). Renders a line–label–line layout. */
+    label?: ReactNode;
+    /** Label alignment when `label` is set. @default 'center' */
+    labelPosition?: 'start' | 'center' | 'end';
+    /** Override class names on internal elements. */
+    classes?: Partial<DividerClasses>;
+}
+/**
+ * Visual separator between content. Horizontal or vertical, with an optional
+ * centered label.
+ *
+ * @example
+ * <Divider />
+ * <Divider label="OR" />
+ * <Divider orientation="vertical" />
+ */
+export declare const Divider: import('react').ForwardRefExoticComponent<Omit<DividerProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;

package/components/Divider/index.d.ts

@@ -0,0 +1,2 @@
+export { Divider } from './Divider';
+export type { DividerProps, DividerClasses } from './Divider';