@overdoser/react-toolkit 0.0.16 → 0.5.0

package/components/Toast/Toast.d.ts

@@ -0,0 +1,82 @@
+import { ReactNode } from 'react';
+export type ToastVariant = 'neutral' | 'info' | 'success' | 'warning' | 'danger';
+export type ToastPosition = 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+export interface ToastClasses {
+    viewport: string;
+    toast: string;
+    icon: string;
+    content: string;
+    title: string;
+    description: string;
+    close: string;
+}
+export interface ToastOptions {
+    /** Bold heading line. */
+    title?: ReactNode;
+    /** Secondary line beneath the title. */
+    description?: ReactNode;
+    /** Color/semantics. @default 'neutral' */
+    variant?: ToastVariant;
+    /** Auto-dismiss delay in ms. `0` or `Infinity` keeps it until dismissed. Defaults to the provider's `duration`. */
+    duration?: number;
+}
+/** Callable toast trigger with `.dismiss` / `.dismissAll` helpers attached. */
+export interface ToastFn {
+    /** Show a toast; returns its id. */
+    (options: ToastOptions): string;
+    /** Dismiss a specific toast by id. */
+    dismiss: (id: string) => void;
+    /** Dismiss every visible toast. */
+    dismissAll: () => void;
+}
+export interface ToastApi {
+    /** Show a toast; returns its id. */
+    toast: ToastFn;
+    /** Dismiss a specific toast by id. */
+    dismiss: (id: string) => void;
+    /** Dismiss every visible toast. */
+    dismissAll: () => void;
+}
+/**
+ * Show a toast from anywhere — no hook or context required, as long as a
+ * `<ToastProvider>` is mounted somewhere to render the queue. Returns the new
+ * toast's id. Also callable as `toast.dismiss(id)` and `toast.dismissAll()`.
+ *
+ * @example
+ * import { toast } from '@overdoser/react-toolkit';
+ * toast({ variant: 'success', title: 'Saved' });
+ * const id = toast({ title: 'Uploading…', duration: 0 });
+ * toast.dismiss(id);
+ */
+export declare const toast: ToastFn;
+/**
+ * Returns the same imperative API as the standalone {@link toast}, for callers
+ * who prefer a hook. Works anywhere — a `<ToastProvider>` only needs to be
+ * mounted somewhere to render the toasts.
+ *
+ * @example
+ * const { toast } = useToast();
+ * toast({ variant: 'success', title: 'Saved', description: 'All set.' });
+ */
+export declare function useToast(): ToastApi;
+export interface ToastProviderProps {
+    children: ReactNode;
+    /** Where toasts stack on screen. @default 'top-right' */
+    position?: ToastPosition;
+    /** Default auto-dismiss delay in ms. @default 5000 */
+    duration?: number;
+    /** Maximum simultaneously-visible toasts; older ones are dropped. @default 5 */
+    max?: number;
+    /** Override class names on internal elements. */
+    classes?: Partial<ToastClasses>;
+}
+/**
+ * Provides the toast queue and renders the viewport (portaled to `document.body`).
+ * Wrap your app once, then call {@link useToast} anywhere beneath it.
+ *
+ * @example
+ * <ToastProvider position="bottom-right">
+ *   <App />
+ * </ToastProvider>
+ */
+export declare function ToastProvider({ children, position, duration, max, classes, }: ToastProviderProps): import("react/jsx-runtime").JSX.Element;

package/components/Toast/index.d.ts

@@ -0,0 +1,2 @@
+export { ToastProvider, useToast, toast } from './Toast';
+export type { ToastProviderProps, ToastOptions, ToastApi, ToastFn, ToastClasses, ToastVariant, ToastPosition, } from './Toast';

package/components/Toast/toastStore.d.ts

@@ -0,0 +1,28 @@
+import { ReactNode } from 'react';
+import { ToastOptions, ToastVariant } from './Toast';
+/** A live toast in the store. Resolved (`duration`) and renderable. */
+export interface ToastRecord {
+    id: string;
+    variant: ToastVariant;
+    title?: ReactNode;
+    description?: ReactNode;
+    duration: number;
+    exiting: boolean;
+}
+declare let config: {
+    duration: number;
+    max: number;
+};
+export declare function subscribeToasts(listener: () => void): () => void;
+export declare function getToasts(): ToastRecord[];
+export declare function getServerToasts(): ToastRecord[];
+/** A mounted provider sets the active defaults (duration/max). */
+export declare function configureToasts(next: Partial<typeof config>): void;
+/** Track provider lifecycle so we can warn when toasts fire with nothing rendering them. */
+export declare function registerProvider(): () => void;
+export declare function addToast(options: ToastOptions): string;
+export declare function dismissToast(id: string): void;
+export declare function dismissAllToasts(): void;
+/** Test-only: wipe state and pending timers back to defaults. */
+export declare function resetToastStore(): void;
+export {};

package/components/Tooltip/Tooltip.d.ts

@@ -0,0 +1,38 @@
+import { ReactNode } from 'react';
+export type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
+export interface TooltipClasses {
+    wrapper: string;
+    tooltip: string;
+    arrow: string;
+}
+export interface TooltipProps {
+    /** The tooltip text/content. If empty/nullish, the tooltip never shows. */
+    content: ReactNode;
+    /** The trigger element(s). Wrapped in an inline span that owns hover/focus. */
+    children: ReactNode;
+    /** Preferred side. Flips to the opposite side if it would overflow. @default 'top' */
+    placement?: TooltipPlacement;
+    /** Delay before showing, in ms. @default 300 */
+    delay?: number;
+    /** Delay before hiding, in ms. @default 0 */
+    closeDelay?: number;
+    /** Disable the tooltip entirely. @default false */
+    disabled?: boolean;
+    /** Hide the little arrow. @default false */
+    hideArrow?: boolean;
+    /** Override class names on internal elements. */
+    classes?: Partial<TooltipClasses>;
+}
+/**
+ * Lightweight text tooltip shown on hover/focus after a short delay. For rich,
+ * interactive, click-triggered content use `Popover` instead.
+ *
+ * @example
+ * <Tooltip content="Copy to clipboard">
+ *   <button aria-label="Copy">⧉</button>
+ * </Tooltip>
+ */
+export declare function Tooltip({ content, children, placement, delay, closeDelay, disabled, hideArrow, classes, }: TooltipProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace Tooltip {
+    var displayName: string;
+}

package/components/Tooltip/index.d.ts

@@ -0,0 +1,2 @@
+export { Tooltip } from './Tooltip';
+export type { TooltipProps, TooltipClasses, TooltipPlacement } from './Tooltip';

package/components/inputs/Checkbox/Checkbox.d.ts

@@ -7,7 +7,13 @@ export interface CheckboxClasses {
 export interface CheckboxProps extends ComponentPropsWithRef<'input'> {
     /** Visible label rendered next to the box. */
     label?: ReactNode;
-    /** Sets the DOM `indeterminate` property; visually distinct from checked/unchecked. @default false */
+    /**
+     * Visual style of the control. `'switch'` renders a sliding toggle instead of
+     * a box; the underlying `<input type="checkbox">` (and its a11y/form behavior)
+     * is identical. `indeterminate` only applies to `'checkbox'`. @default 'checkbox'
+     */
+    variant?: 'checkbox' | 'switch';
+    /** Sets the DOM `indeterminate` property; visually distinct from checked/unchecked. Ignored when `variant="switch"`. @default false */
     indeterminate?: boolean;
     /** Override class names on internal elements. */
     classes?: Partial<CheckboxClasses>;
@@ -22,5 +28,9 @@ export interface CheckboxProps extends ComponentPropsWithRef<'input'> {
  *   checked={remember}
  *   onChange={(e) => setRemember(e.target.checked)}
  * />
+ *
+ * @example
+ * // Toggle-switch style
+ * <Checkbox variant="switch" label="Notifications" defaultChecked />
  */
 export declare const Checkbox: import('react').ForwardRefExoticComponent<Omit<CheckboxProps, "ref"> & import('react').RefAttributes<HTMLInputElement>>;

package/components/inputs/Checkbox/CheckboxGroup.d.ts

@@ -0,0 +1,83 @@
+import { CSSProperties, ReactNode } from 'react';
+export interface CheckboxGroupOption {
+    /** Value added to / removed from the selected array. */
+    value: string;
+    /** Visible label (checkbox row label, or chip body). */
+    label: ReactNode;
+    /** Non-interactive when true. */
+    disabled?: boolean;
+}
+export interface CheckboxGroupClasses {
+    group: string;
+    /** Each rendered option (a `Checkbox` row, or a chip button). */
+    option: string;
+    /** The chip button (only in `variant="chips"`). */
+    chip: string;
+    /** Applied to a chip when its value is selected. */
+    chipSelected: string;
+}
+export interface CheckboxGroupProps {
+    /** Selectable options. */
+    options: CheckboxGroupOption[];
+    /** Controlled array of selected values. @default [] */
+    value?: string[];
+    /** Fires with the next selected array whenever an option is toggled. */
+    onChange?: (values: string[]) => void;
+    /**
+     * Rendering style:
+     * - `'checkbox'` (default): a list of themed checkboxes.
+     * - `'chips'`: toggleable chips laid out one after another.
+     * @default 'checkbox'
+     */
+    variant?: 'checkbox' | 'chips';
+    /**
+     * Chip corner style (`variant="chips"` only):
+     * - `'pill'`: fully rounded (default).
+     * - `'rounded'`: medium radius.
+     * - `'square'`: small radius — more rectangular.
+     * @default 'pill'
+     */
+    chipShape?: 'pill' | 'rounded' | 'square';
+    /**
+     * Show a leading checkmark on selected chips (`variant="chips"` only). The
+     * chip's total width stays constant: when checked, the horizontal padding
+     * shrinks on both sides by exactly half the mark+gap width, so the freed
+     * space fits the mark and the centered content does not jump. @default true
+     */
+    chipCheckmark?: boolean;
+    /**
+     * Layout direction. `'horizontal'` wraps options onto multiple lines.
+     * Defaults to `'vertical'` for `checkbox` and `'horizontal'` for `chips`.
+     */
+    orientation?: 'vertical' | 'horizontal';
+    /** Disables every option. */
+    disabled?: boolean;
+    /** Apply error styling (e.g. when a required group is empty). @default false */
+    error?: boolean;
+    /** Shared `name` for the underlying checkboxes (checkbox variant). */
+    name?: string;
+    /** Override class names on internal elements. */
+    classes?: Partial<CheckboxGroupClasses>;
+    className?: string;
+    style?: CSSProperties;
+    id?: string;
+    /** Accessible label. Use this OR `aria-labelledby`. */
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    'aria-describedby'?: string;
+    'aria-invalid'?: boolean | 'true' | 'false';
+    /** Marks the group as required (`aria-required`). */
+    required?: boolean;
+}
+/**
+ * Multi-value selection from a fixed set of options. Renders either a list of
+ * checkboxes (default) or a row of toggleable chips. Works standalone or inside
+ * a `<FormField>` (its `value: string[]` / `onChange(values)` bridge directly).
+ *
+ * @example Checkboxes:
+ * <CheckboxGroup options={topics} value={picked} onChange={setPicked} aria-label="Topics" />
+ *
+ * @example Chips:
+ * <CheckboxGroup variant="chips" options={tags} value={picked} onChange={setPicked} aria-label="Tags" />
+ */
+export declare const CheckboxGroup: import('react').ForwardRefExoticComponent<CheckboxGroupProps & import('react').RefAttributes<HTMLDivElement>>;

package/components/inputs/Checkbox/index.d.ts

@@ -1,2 +1,4 @@
 export { Checkbox } from './Checkbox';
 export type { CheckboxProps, CheckboxClasses } from './Checkbox';
+export { CheckboxGroup } from './CheckboxGroup';
+export type { CheckboxGroupProps, CheckboxGroupClasses, CheckboxGroupOption, } from './CheckboxGroup';

package/components/inputs/DatePicker/DatePicker.d.ts

@@ -0,0 +1,58 @@
+import { CSSProperties } from 'react';
+export interface DatePickerClasses {
+    root: string;
+    input: string;
+    icon: string;
+    popover: string;
+    header: string;
+    nav: string;
+    grid: string;
+    day: string;
+    daySelected: string;
+    dayToday: string;
+    dayOutside: string;
+}
+export interface DatePickerProps {
+    /** Controlled selected date (`null` for empty). */
+    value?: Date | null;
+    /** Uncontrolled initial date. */
+    defaultValue?: Date | null;
+    /** Called with the newly selected date. */
+    onChange?: (date: Date | null) => void;
+    /** Earliest selectable date (inclusive). */
+    min?: Date;
+    /** Latest selectable date (inclusive). */
+    max?: Date;
+    /** Predicate to disable arbitrary days. */
+    disabledDate?: (date: Date) => boolean;
+    /** First day of the week (0 = Sunday). @default 0 */
+    weekStartsOn?: number;
+    /** BCP-47 locale for month/weekday names and default formatting. */
+    locale?: string;
+    /** Format the selected date for the input. Defaults to a localized medium date. */
+    format?: (date: Date) => string;
+    /** Placeholder when no date is selected. @default 'Select date' */
+    placeholder?: string;
+    /** Toolkit size scale. @default 'md' */
+    inputSize?: 'sm' | 'md' | 'lg';
+    /** Apply error styling. @default false */
+    error?: boolean;
+    /** Disable the field. @default false */
+    disabled?: boolean;
+    /** Render the calendar in a portal at `document.body` (escapes overflow). @default true */
+    portal?: boolean;
+    /** Override class names on internal elements. */
+    classes?: Partial<DatePickerClasses>;
+    className?: string;
+    style?: CSSProperties;
+    'aria-label'?: string;
+}
+/**
+ * Date input with a pop-up calendar. Single date selection with full keyboard
+ * support (arrows move days, PageUp/Down change month, Enter selects, Esc
+ * closes). Binds inside `FormField` (`value: Date | null` / `onChange`).
+ *
+ * @example
+ * <DatePicker value={date} onChange={setDate} min={new Date()} />
+ */
+export declare const DatePicker: import('react').ForwardRefExoticComponent<DatePickerProps & import('react').RefAttributes<HTMLInputElement>>;

package/components/inputs/DatePicker/dateUtils.d.ts

@@ -0,0 +1,16 @@
+/** Date helpers for the calendar. All operate on local time, day granularity. */
+export declare function startOfDay(d: Date): Date;
+export declare function isSameDay(a: Date | null | undefined, b: Date | null | undefined): boolean;
+export declare function isSameMonth(a: Date, b: Date): boolean;
+export declare function addDays(d: Date, n: number): Date;
+export declare function addMonths(d: Date, n: number): Date;
+export declare function startOfMonth(d: Date): Date;
+/** ISO `YYYY-MM-DD` of the local date — stable key/identifier for a day. */
+export declare function toISODate(d: Date): string;
+/**
+ * The 6×7 grid of days covering the month of `viewDate`, starting each week on
+ * `weekStartsOn` (0 = Sunday). Always 42 cells so the calendar height is stable.
+ */
+export declare function buildCalendarDays(viewDate: Date, weekStartsOn: number): Date[];
+/** Short weekday labels ordered from `weekStartsOn`, localized. */
+export declare function weekdayLabels(locale: string | undefined, weekStartsOn: number): string[];

package/components/inputs/DatePicker/index.d.ts

@@ -0,0 +1,2 @@
+export { DatePicker } from './DatePicker';
+export type { DatePickerProps, DatePickerClasses } from './DatePicker';

package/components/inputs/NumberInput/NumberInput.d.ts

@@ -0,0 +1,41 @@
+import { ComponentPropsWithRef } from 'react';
+export interface NumberInputClasses {
+    root: string;
+    input: string;
+    controls: string;
+    increment: string;
+    decrement: string;
+}
+export interface NumberInputProps extends Omit<ComponentPropsWithRef<'input'>, 'value' | 'defaultValue' | 'onChange' | 'min' | 'max' | 'step' | 'prefix'> {
+    /** Controlled numeric value (`null` when empty). */
+    value?: number | null;
+    /** Uncontrolled initial value. */
+    defaultValue?: number | null;
+    /** Called with the parsed value (`null` when the field is empty). */
+    onChange?: (value: number | null) => void;
+    /** Minimum allowed value. */
+    min?: number;
+    /** Maximum allowed value. */
+    max?: number;
+    /** Increment/decrement step. @default 1 */
+    step?: number;
+    /** Decimal places to round to on commit. */
+    precision?: number;
+    /** Toolkit size scale. @default 'md' */
+    inputSize?: 'sm' | 'md' | 'lg';
+    /** Apply error styling. @default false */
+    error?: boolean;
+    /** Hide the stepper buttons. @default false */
+    hideControls?: boolean;
+    /** Override class names on internal elements. */
+    classes?: Partial<NumberInputClasses>;
+}
+/**
+ * Numeric input with stepper buttons, min/max clamping, and keyboard
+ * arrow-key stepping. Emits `onChange(value: number | null)`, so it binds
+ * directly inside `FormField`.
+ *
+ * @example
+ * <NumberInput value={qty} onChange={setQty} min={0} max={99} />
+ */
+export declare const NumberInput: import('react').ForwardRefExoticComponent<Omit<NumberInputProps, "ref"> & import('react').RefAttributes<HTMLInputElement>>;

package/components/inputs/NumberInput/index.d.ts

@@ -0,0 +1,2 @@
+export { NumberInput } from './NumberInput';
+export type { NumberInputProps, NumberInputClasses } from './NumberInput';

package/components/inputs/Slider/Slider.d.ts

@@ -0,0 +1,44 @@
+import { CSSProperties } from 'react';
+export type SliderValue = number | [number, number];
+export interface SliderClasses {
+    root: string;
+    track: string;
+    range: string;
+    thumb: string;
+}
+export interface SliderProps {
+    /** Controlled value. A two-element tuple makes it a range slider. */
+    value?: SliderValue;
+    /** Uncontrolled initial value. @default 0 (or `[min, max]` shape if a tuple). */
+    defaultValue?: SliderValue;
+    /** Called with the new value during interaction. */
+    onChange?: (value: SliderValue) => void;
+    /** Called once when a drag/keyboard interaction settles (pointer up / key up). */
+    onChangeEnd?: (value: SliderValue) => void;
+    /** Minimum. @default 0 */
+    min?: number;
+    /** Maximum. @default 100 */
+    max?: number;
+    /** Step increment. @default 1 */
+    step?: number;
+    /** Disable interaction. @default false */
+    disabled?: boolean;
+    /** Accessible label for the thumb(s). */
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    /** Format the value for `aria-valuetext`. */
+    formatValue?: (value: number) => string;
+    /** Override class names on internal elements. */
+    classes?: Partial<SliderClasses>;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Range input slider — single thumb (number value) or dual thumb (tuple value).
+ * Supports pointer drag and keyboard (arrows, Home/End).
+ *
+ * @example
+ * <Slider value={vol} onChange={(v) => setVol(v as number)} aria-label="Volume" />
+ * <Slider value={range} onChange={(v) => setRange(v as [number, number])} aria-label="Price" />
+ */
+export declare const Slider: import('react').ForwardRefExoticComponent<SliderProps & import('react').RefAttributes<HTMLDivElement>>;

package/components/inputs/Slider/index.d.ts

@@ -0,0 +1,2 @@
+export { Slider } from './Slider';
+export type { SliderProps, SliderClasses, SliderValue } from './Slider';