@overdoser/react-toolkit 0.0.16 → 0.5.0

package/components/Draggable/Draggable.d.ts

@@ -0,0 +1,50 @@
+import { forwardRef, ComponentPropsWithoutRef, ReactNode } from 'react';
+/** An `{ x, y }` translation offset, in pixels, from the element's natural position. */
+export interface DraggablePosition {
+    x: number;
+    y: number;
+}
+export interface DraggableClasses {
+    root: string;
+    handle: string;
+}
+export interface DraggableProps extends Omit<ComponentPropsWithoutRef<'div'>, 'onDrag' | 'onDragStart' | 'onDragEnd'> {
+    /** Container content. Include a `<Draggable.Handle>` to restrict the grab area; without one, the whole surface drags. */
+    children?: ReactNode;
+    /** Uncontrolled initial offset. @default { x: 0, y: 0 } */
+    defaultPosition?: DraggablePosition;
+    /** Controlled offset. When set, the component renders at this value and you must update it from `onDrag`. */
+    position?: DraggablePosition;
+    /** Restrict movement to one axis. @default 'both' */
+    axis?: 'both' | 'x' | 'y';
+    /** Where the element is allowed to move. `'viewport'` and `'parent'` clamp to those bounds; `'none'` is unconstrained. @default 'viewport' */
+    bounds?: 'viewport' | 'parent' | 'none';
+    /** Pixel step applied when moving via arrow keys with a focused handle. @default 10 */
+    keyboardStep?: number;
+    /** Disable dragging entirely. @default false */
+    disabled?: boolean;
+    /** Fired when a drag gesture begins, with the current offset. */
+    onDragStart?: (position: DraggablePosition) => void;
+    /** Fired on every move (pointer or keyboard) with the new offset. Required to update a controlled `position`. */
+    onDrag?: (position: DraggablePosition) => void;
+    /** Fired when a drag gesture ends, with the final offset. */
+    onDragEnd?: (position: DraggablePosition) => void;
+    /** Override class names on internal elements. */
+    classes?: Partial<DraggableClasses>;
+}
+type DraggableComponent = ReturnType<typeof forwardRef<HTMLDivElement, DraggableProps>> & {
+    Handle: typeof DraggableHandle;
+};
+export interface DraggableHandleProps extends ComponentPropsWithoutRef<'div'> {
+    children?: ReactNode;
+}
+/**
+ * Grab area for a `<Draggable>`. Place it inside the container; only this element
+ * initiates dragging, and it's keyboard-movable (arrow keys) when focused.
+ */
+declare function DraggableHandle({ children, className, style, ...rest }: DraggableHandleProps): import("react/jsx-runtime").JSX.Element;
+declare namespace DraggableHandle {
+    var displayName: string;
+}
+export declare const Draggable: DraggableComponent;
+export {};

package/components/Draggable/index.d.ts

@@ -0,0 +1,2 @@
+export { Draggable } from './Draggable';
+export type { DraggableProps, DraggableClasses, DraggablePosition, DraggableHandleProps, } from './Draggable';

package/components/Drawer/Drawer.d.ts

@@ -0,0 +1,65 @@
+import { forwardRef, CSSProperties, FC, ReactNode } from 'react';
+export interface DrawerClasses {
+    backdrop: string;
+    drawer: string;
+    header: string;
+    closeButton: string;
+    body: string;
+    footer: string;
+}
+export interface DrawerHeaderProps {
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    /** When provided, renders an "×" close button in the header. */
+    onClose?: () => void;
+}
+export interface DrawerBodyProps {
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}
+export interface DrawerFooterProps {
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}
+declare const Header: FC<DrawerHeaderProps>;
+declare const Body: FC<DrawerBodyProps>;
+declare const Footer: FC<DrawerFooterProps>;
+export interface DrawerProps {
+    /** Whether the drawer is visible. */
+    open: boolean;
+    /** Called on backdrop click, Escape, or the `Drawer.Header` close button. */
+    onClose: () => void;
+    /** Edge the panel slides in from. @default 'right' */
+    side?: 'left' | 'right' | 'top' | 'bottom';
+    /** Panel size (width for left/right, height for top/bottom). @default 'md' */
+    size?: 'sm' | 'md' | 'lg' | 'full';
+    /**
+     * `'temporary'` overlays the page with a dimmed scrim and is modal (click the
+     * scrim or press Escape to close). `'persistent'` shows no scrim and leaves the
+     * page interactive — a fixed side panel. @default 'temporary'
+     */
+    variant?: 'temporary' | 'persistent';
+    /** Close when the backdrop is clicked (temporary only). @default true */
+    closeOnBackdrop?: boolean;
+    /** Close when Escape is pressed. @default true */
+    closeOnEscape?: boolean;
+    /** Override class names on internal elements. */
+    classes?: Partial<DrawerClasses>;
+    className?: string;
+    style?: CSSProperties;
+    /** Should be `<Drawer.Header>`, `<Drawer.Body>`, `<Drawer.Footer>`. */
+    children: ReactNode;
+    /** Accessible label. Use this OR `aria-labelledby`. If neither is set, `Drawer.Header` is auto-wired. */
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+}
+type DrawerComponent = ReturnType<typeof forwardRef<HTMLDivElement, DrawerProps>> & {
+    Header: typeof Header;
+    Body: typeof Body;
+    Footer: typeof Footer;
+};
+export declare const Drawer: DrawerComponent;
+export {};

package/components/Drawer/index.d.ts

@@ -0,0 +1,2 @@
+export { Drawer } from './Drawer';
+export type { DrawerProps, DrawerClasses, DrawerHeaderProps, DrawerBodyProps, DrawerFooterProps, } from './Drawer';

package/components/Dropzone/Dropzone.d.ts

@@ -0,0 +1,50 @@
+import { ReactNode } from 'react';
+export interface DropzoneRejection {
+    file: File;
+    reason: 'type' | 'size' | 'multiple';
+}
+export interface DropzoneClasses {
+    root: string;
+    input: string;
+    content: string;
+    icon: string;
+    label: string;
+    hint: string;
+}
+export interface DropzoneProps {
+    /** Called with the accepted files. */
+    onFiles?: (files: File[]) => void;
+    /** Called with rejected files and the reason, when validation fails. */
+    onReject?: (rejections: DropzoneRejection[]) => void;
+    /** Accepted types — a comma list of extensions and/or MIME patterns (e.g. `'.png,image/*'`). */
+    accept?: string;
+    /** Allow selecting multiple files. @default false */
+    multiple?: boolean;
+    /** Maximum size per file, in bytes. */
+    maxSize?: number;
+    /** Disable the dropzone. @default false */
+    disabled?: boolean;
+    /** Primary label text (ignored if `children` is provided). */
+    label?: ReactNode;
+    /** Secondary hint text (ignored if `children` is provided). */
+    hint?: ReactNode;
+    /** Custom content; receives the current drag state. Replaces the default UI. */
+    children?: ReactNode | ((state: {
+        isDragging: boolean;
+    }) => ReactNode);
+    /** Override class names on internal elements. */
+    classes?: Partial<DropzoneClasses>;
+    className?: string;
+    style?: React.CSSProperties;
+    /** Accessible label for the dropzone button. @default 'Upload files' */
+    'aria-label'?: string;
+}
+/**
+ * File upload dropzone — drag-and-drop or click to browse. Validates `accept`
+ * and `maxSize`, emitting accepted files via `onFiles` and rejected ones via
+ * `onReject`. File-list/state management is left to the consumer.
+ *
+ * @example
+ * <Dropzone accept="image/*" maxSize={2_000_000} multiple onFiles={setFiles} />
+ */
+export declare const Dropzone: import('react').ForwardRefExoticComponent<DropzoneProps & import('react').RefAttributes<HTMLInputElement>>;

package/components/Dropzone/index.d.ts

@@ -0,0 +1,2 @@
+export { Dropzone } from './Dropzone';
+export type { DropzoneProps, DropzoneClasses, DropzoneRejection } from './Dropzone';

package/components/Form/Form.d.ts

@@ -1,4 +1,5 @@
 import { UseFormReturn, FieldValues, SubmitHandler } from 'react-hook-form';
+import { FormFieldClasses } from './FormField';
 export interface FormProps<T extends FieldValues> {
     /** The result of `useForm()`. */
     form: UseFormReturn<T>;
@@ -6,6 +7,20 @@ export interface FormProps<T extends FieldValues> {
     onSubmit: SubmitHandler<T>;
     /** Top-of-form error messages. Rendered above children with `role="alert"`. */
     errors?: React.ReactNode[];
+    /**
+     * Default `reserveErrorSpace` applied to every `FormField` inside this form
+     * (each field can still override it via its own `reserveErrorSpace` prop).
+     * Same accepted values as `FormField`: `boolean | number | string`.
+     * @default true
+     */
+    reserveErrorSpace?: boolean | number | string;
+    /**
+     * Default `classes` applied to every `FormField` inside this form. These are
+     * *merged* with each field's own `classes` (both class names are applied), so
+     * a field can add to — not just replace — the form-wide defaults. Keys:
+     * `{ field, label, message, error, helperText }`.
+     */
+    fieldClasses?: Partial<FormFieldClasses>;
     className?: string;
     style?: React.CSSProperties;
     children: React.ReactNode;
@@ -23,4 +38,4 @@ export interface FormProps<T extends FieldValues> {
  *   <Button type="submit">Save</Button>
  * </Form>
  */
-export declare function Form<T extends FieldValues>({ form, onSubmit, errors, className, style, children, }: FormProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare function Form<T extends FieldValues>({ form, onSubmit, errors, reserveErrorSpace, fieldClasses, className, style, children, }: FormProps<T>): import("react/jsx-runtime").JSX.Element;

package/components/Form/FormField.d.ts

@@ -2,6 +2,7 @@ import { ReactElement, CSSProperties, ReactNode } from 'react';
 export interface FormFieldClasses {
     field: string;
     label: string;
+    message: string;
     error: string;
     helperText: string;
 }
@@ -10,12 +11,26 @@ export interface FormFieldProps {
     name: string;
     /** Field label rendered above the input. */
     label?: ReactNode;
-    /** Helper text rendered below the input (replaced by error message when invalid). */
+    /** Helper/description text rendered below the input. Stays visible when invalid — the error message appears above it, between the input and this text. */
     helperText?: ReactNode;
     /** Renders a `*` indicator next to the label. Does NOT add validation rules — pass those in `rules`. */
     required?: boolean;
     /** react-hook-form `useController` rules (e.g., `{ required: 'msg', minLength: { value: 8, message: '…' } }`). */
     rules?: Record<string, unknown>;
+    /**
+     * Reserve vertical space (after the description) for the validation message so
+     * the field's outer height does not change when an error appears/disappears.
+     * - `true`: reserve one line via the `--crk-field-error-min-height` token.
+     * - `false`: no reservation — an error pushes content down (legacy behaviour).
+     * - `number`: reserved height in pixels.
+     * - `string`: any CSS length (e.g. `'2.5em'` to fit two lines).
+     *
+     * Multi-line messages are allowed to grow past the reserved height. When unset,
+     * inherits the `reserveErrorSpace` set on the enclosing `<Form>`, falling back
+     * to `true`.
+     * @default inherited from `<Form>`, else `true`
+     */
+    reserveErrorSpace?: boolean | number | string;
     /** Override class names on internal elements. */
     classes?: Partial<FormFieldClasses>;
     className?: string;
@@ -41,4 +56,4 @@ export interface FormFieldProps {
  *   <Input type="email" />
  * </FormField>
  */
-export declare function FormField({ name, label, helperText, required, rules, classes, className, style, children, }: FormFieldProps): import("react/jsx-runtime").JSX.Element;
+export declare function FormField({ name, label, helperText, required, rules, reserveErrorSpace, classes, className, style, children, }: FormFieldProps): import("react/jsx-runtime").JSX.Element;

package/components/Form/formFieldDefaults.d.ts

@@ -0,0 +1,9 @@
+import { FormFieldClasses } from './FormField';
+/** Field-level defaults supplied by `<Form>` and inherited by every `<FormField>`. */
+export interface FormFieldDefaults {
+    /** Default `reserveErrorSpace` for fields that don't set their own. */
+    reserveErrorSpace?: boolean | number | string;
+    /** Default `classes` merged into every field (each field's own `classes` are also applied). */
+    classes?: Partial<FormFieldClasses>;
+}
+export declare const FormFieldDefaultsContext: import('react').Context<FormFieldDefaults | null>;

package/components/Link/Link.d.ts

@@ -9,10 +9,20 @@ export interface LinkProps extends ComponentPropsWithRef<'a'> {
      * @default false
      */
     external?: boolean;
+    /**
+     * Hide the inline "opens in a new tab" icon that is shown by default whenever
+     * the link opens in a new tab (`external` or `target="_blank"`). The
+     * screen-reader suffix is kept regardless. @default false
+     */
+    hideExternalIcon?: boolean;
 }
 /**
  * Styled `<a>` with variants and safe external-link defaults.
  *
+ * When the link opens in a new tab (via `external`, or a manual
+ * `target="_blank"`), a small inline ↗ icon is appended to the right so users
+ * know the link leaves the current tab. Pass `hideExternalIcon` to suppress it.
+ *
  * @example <Link href="https://example.com" external>Docs</Link>
  */
 export declare const Link: import('react').ForwardRefExoticComponent<Omit<LinkProps, "ref"> & import('react').RefAttributes<HTMLAnchorElement>>;

package/components/Pagination/Pagination.d.ts

@@ -0,0 +1,48 @@
+import { ComponentPropsWithRef } from 'react';
+export interface PaginationClasses {
+    root: string;
+    list: string;
+    item: string;
+    active: string;
+    ellipsis: string;
+    control: string;
+}
+export interface PaginationProps extends Omit<ComponentPropsWithRef<'nav'>, 'onChange'> {
+    /** Total number of pages. Provide this, or `total` + `pageSize`. */
+    count?: number;
+    /** Total item count — used with `pageSize` to derive `count`. */
+    total?: number;
+    /** Items per page — used with `total` to derive `count`. @default 10 */
+    pageSize?: number;
+    /** Controlled current page (1-based). */
+    page?: number;
+    /** Uncontrolled initial page (1-based). @default 1 */
+    defaultPage?: number;
+    /** Called with the new page number. */
+    onChange?: (page: number) => void;
+    /** Pages always shown at the start and end. @default 1 */
+    boundaryCount?: number;
+    /** Pages shown on each side of the current page. @default 2 (→ up to 9 chips) */
+    siblingCount?: number;
+    /** Show the previous/next arrow controls. @default true */
+    showPrevNext?: boolean;
+    /** Show the jump-to-first/last controls. @default false */
+    showFirstLast?: boolean;
+    /** Control size. @default 'md' */
+    size?: 'sm' | 'md' | 'lg';
+    /** Disable all controls. @default false */
+    disabled?: boolean;
+    /** Accessible label for the nav landmark. @default 'Pagination' */
+    label?: string;
+    /** Override class names on internal elements. */
+    classes?: Partial<PaginationClasses>;
+}
+/**
+ * Page navigation with a windowed range and ellipses (e.g. `1 … 6 7 8 9 10 … 99`).
+ * With the default `siblingCount={2}` it shows at most 9 page chips.
+ *
+ * @example
+ * <Pagination count={99} page={page} onChange={setPage} />
+ * <Pagination total={480} pageSize={20} page={page} onChange={setPage} showFirstLast />
+ */
+export declare const Pagination: import('react').ForwardRefExoticComponent<Omit<PaginationProps, "ref"> & import('react').RefAttributes<HTMLElement>>;

package/components/Pagination/index.d.ts

@@ -0,0 +1,4 @@
+export { Pagination } from './Pagination';
+export type { PaginationProps, PaginationClasses } from './Pagination';
+export { paginationRange } from './paginationRange';
+export type { PaginationItem } from './paginationRange';

package/components/Pagination/paginationRange.d.ts

@@ -0,0 +1,8 @@
+export type PaginationItem = number | 'ellipsis';
+/**
+ * Builds the windowed page list with ellipses — e.g. with `count=99`, `page=8`,
+ * `boundaryCount=1`, `siblingCount=2` → `[1, 'ellipsis', 6, 7, 8, 9, 10, 'ellipsis', 99]`.
+ * Mirrors MUI's `usePagination` range logic. The widest output is
+ * `boundaryCount*2 + siblingCount*2 + 3` items (two ellipses + current).
+ */
+export declare function paginationRange(page: number, count: number, boundaryCount?: number, siblingCount?: number): PaginationItem[];

package/components/Popover/Popover.d.ts

@@ -26,6 +26,13 @@ export interface PopoverProps {
     content: React.ReactNode;
     /** Side of the trigger to anchor the panel to. @default 'bottom' */
     position?: 'top' | 'bottom' | 'left' | 'right';
+    /**
+     * Keep the panel inside the viewport: flip to the opposite side when the
+     * requested one would overflow, and shift along the cross-axis so the panel
+     * stays fully visible near a screen edge. The requested `position` is honored
+     * whenever it fits. @default true
+     */
+    autoPosition?: boolean;
     /** Controlled open state. */
     open?: boolean;
     /** Called when the open state changes. */

package/components/Skeleton/Skeleton.d.ts

@@ -0,0 +1,28 @@
+import { ComponentPropsWithRef } from 'react';
+export interface SkeletonClasses {
+    root: string;
+    line: string;
+}
+export interface SkeletonProps extends Omit<ComponentPropsWithRef<'div'>, 'children'> {
+    /** Shape of the placeholder. @default 'text' */
+    variant?: 'text' | 'circle' | 'rect';
+    /** Explicit width (number → px). Defaults to `100%`. */
+    width?: number | string;
+    /** Explicit height (number → px). Defaults per variant. */
+    height?: number | string;
+    /** Shimmer style. @default 'pulse' */
+    animation?: 'pulse' | 'wave' | 'none';
+    /** For `variant="text"`, render this many stacked lines (the last is shorter). @default 1 */
+    lines?: number;
+    /** Override class names on internal elements. */
+    classes?: Partial<SkeletonClasses>;
+}
+/**
+ * Loading placeholder that mimics content while it's fetching. Decorative
+ * (`aria-hidden`) — pair the surrounding region with its own loading status.
+ *
+ * @example
+ * <Skeleton variant="text" lines={3} />
+ * <Skeleton variant="circle" width={40} height={40} />
+ */
+export declare const Skeleton: import('react').ForwardRefExoticComponent<Omit<SkeletonProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;

package/components/Skeleton/index.d.ts

@@ -0,0 +1,2 @@
+export { Skeleton } from './Skeleton';
+export type { SkeletonProps, SkeletonClasses } from './Skeleton';

package/components/Spinner/Spinner.d.ts

@@ -0,0 +1,29 @@
+import { ComponentPropsWithRef } from 'react';
+export interface SpinnerClasses {
+    root: string;
+    circle: string;
+    label: string;
+}
+export interface SpinnerProps extends ComponentPropsWithRef<'span'> {
+    /** Spinner size. @default 'md' */
+    size?: 'sm' | 'md' | 'lg';
+    /** Stroke color. Defaults to `currentColor`, so it inherits the surrounding text color. */
+    color?: string;
+    /**
+     * Accessible label announced to screen readers (visually hidden). Set to an
+     * empty string only when an adjacent visible element already labels the busy
+     * state. @default 'Loading'
+     */
+    label?: string;
+    /** Override class names on internal elements. */
+    classes?: Partial<SpinnerClasses>;
+}
+/**
+ * Indeterminate loading spinner. Inherits `currentColor` by default, so it works
+ * on any surface (including inside a `Button`).
+ *
+ * @example
+ * <Spinner size="lg" />
+ * <Button disabled><Spinner size="sm" label="" /> Saving…</Button>
+ */
+export declare const Spinner: import('react').ForwardRefExoticComponent<Omit<SpinnerProps, "ref"> & import('react').RefAttributes<HTMLSpanElement>>;

package/components/Spinner/index.d.ts

@@ -0,0 +1,2 @@
+export { Spinner } from './Spinner';
+export type { SpinnerProps, SpinnerClasses } from './Spinner';

package/components/Tabs/Tabs.d.ts

@@ -0,0 +1,66 @@
+import { ComponentPropsWithRef, ReactNode } from 'react';
+export type TabsOrientation = 'horizontal' | 'vertical';
+export type TabsVariant = 'line' | 'solid' | 'pill';
+export type TabsSize = 'sm' | 'md' | 'lg';
+export interface TabsClasses {
+    root: string;
+    list: string;
+    tab: string;
+    panel: string;
+}
+export interface TabsProps extends Omit<ComponentPropsWithRef<'div'>, 'onChange'> {
+    /** Controlled active tab value. */
+    value?: string;
+    /** Uncontrolled initial active tab value. */
+    defaultValue?: string;
+    /** Called with the new value when the active tab changes. */
+    onValueChange?: (value: string) => void;
+    /** Layout direction. @default 'horizontal' */
+    orientation?: TabsOrientation;
+    /** Visual style of the tab list. @default 'line' */
+    variant?: TabsVariant;
+    /** Tab sizing. @default 'md' */
+    size?: TabsSize;
+    /** Override class names on internal elements. */
+    classes?: Partial<TabsClasses>;
+}
+export interface TabsListProps extends ComponentPropsWithRef<'div'> {
+    children?: ReactNode;
+}
+export interface TabsTabProps extends Omit<ComponentPropsWithRef<'button'>, 'value'> {
+    /** Identifier linking this tab to its panel. */
+    value: string;
+    /** Disable selection of this tab. @default false */
+    disabled?: boolean;
+    children?: ReactNode;
+}
+export interface TabsPanelProps extends ComponentPropsWithRef<'div'> {
+    /** Identifier linking this panel to its tab. */
+    value: string;
+    /**
+     * Keep the panel mounted (but hidden) when inactive. Useful to preserve
+     * scroll/input state across tab switches. @default false
+     */
+    keepMounted?: boolean;
+    children?: ReactNode;
+}
+/**
+ * Accessible tabs. Compose with `Tabs.List`, `Tabs.Tab`, and `Tabs.Panel`.
+ * Arrow keys (plus Home/End) move between tabs and activate them; activation is
+ * automatic on focus.
+ *
+ * @example
+ * <Tabs defaultValue="overview">
+ *   <Tabs.List>
+ *     <Tabs.Tab value="overview">Overview</Tabs.Tab>
+ *     <Tabs.Tab value="activity">Activity</Tabs.Tab>
+ *   </Tabs.List>
+ *   <Tabs.Panel value="overview">…</Tabs.Panel>
+ *   <Tabs.Panel value="activity">…</Tabs.Panel>
+ * </Tabs>
+ */
+export declare const Tabs: import('react').ForwardRefExoticComponent<Omit<TabsProps, "ref"> & import('react').RefAttributes<HTMLDivElement>> & {
+    List: import('react').ForwardRefExoticComponent<Omit<TabsListProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;
+    Tab: import('react').ForwardRefExoticComponent<Omit<TabsTabProps, "ref"> & import('react').RefAttributes<HTMLButtonElement>>;
+    Panel: import('react').ForwardRefExoticComponent<Omit<TabsPanelProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;
+};

package/components/Tabs/index.d.ts

@@ -0,0 +1,2 @@
+export { Tabs } from './Tabs';
+export type { TabsProps, TabsListProps, TabsTabProps, TabsPanelProps, TabsClasses, TabsOrientation, TabsVariant, TabsSize, } from './Tabs';

package/components/Timer/Timer.d.ts

@@ -0,0 +1,103 @@
+import { CSSProperties, ReactNode } from 'react';
+export type TimerMode = 'countdown' | 'stopwatch';
+export type TimerVariant = 'digital' | 'ring' | 'segments';
+export type TimerLabelPlacement = 'top' | 'bottom' | 'left' | 'right';
+export type TimerUnit = 'days' | 'hours' | 'minutes' | 'seconds';
+/** One unit cell of the segmented display. */
+export interface TimerSegment {
+    /** Which unit this segment represents. */
+    unit: TimerUnit;
+    /** Numeric value for the unit. */
+    value: number;
+    /** Display text (zero-padded except the leading unit). */
+    text: string;
+    /** Resolved unit label (e.g. `'h'`, `'hours'`). */
+    label: ReactNode;
+}
+export interface TimerHandle {
+    /** Start (or resume) ticking. */
+    start: () => void;
+    /** Pause, preserving elapsed time. */
+    pause: () => void;
+    /** Stop and reset to the initial value. */
+    reset: () => void;
+    /** Reset then start again. */
+    restart: () => void;
+    /** Current displayed time, in seconds. */
+    getTime: () => number;
+    /** Whether the timer is currently running. */
+    readonly isRunning: boolean;
+}
+export interface TimerClasses {
+    root: string;
+    display: string;
+    label: string;
+    ringTrack: string;
+    ringProgress: string;
+    segments: string;
+    segment: string;
+    segmentValue: string;
+    segmentLabel: string;
+}
+export interface TimerProps {
+    /** Count down to zero, or up from zero. @default 'countdown' */
+    mode?: TimerMode;
+    /** Countdown length / stopwatch cap, in seconds. Drives ring progress. */
+    duration?: number;
+    /** Absolute countdown target (`Date` or epoch ms). Overrides `duration`/pause; always counts down. */
+    to?: Date | number;
+    /** Controlled display time in seconds — makes the timer display-only (no internal clock). */
+    value?: number;
+    /** Start ticking on mount (uncontrolled). @default true */
+    autoStart?: boolean;
+    /** Controlled run state. When set, start/pause follow this prop. */
+    running?: boolean;
+    /** Tick interval in milliseconds. @default 1000 */
+    interval?: number;
+    /** Visual style: `'digital'` digits, `'ring'` progress circle, or `'segments'` (one boxed cell per unit). @default 'digital' */
+    variant?: TimerVariant;
+    /** Size of the digits / ring / segments. @default 'md' */
+    size?: 'sm' | 'md' | 'lg';
+    /** Format the time for display (digital/ring only). Receives whole seconds. */
+    format?: (seconds: number) => ReactNode;
+    /** Which segments to show (segments variant). Defaults to the smallest set that fits the duration. */
+    units?: TimerUnit[];
+    /** Default unit-label style for the segments variant. `'short'` → `d/h/m/s`, `'long'` → `days/hours/minutes/seconds` (fixed — no singular/plural switching). @default 'short' */
+    unitFormat?: 'long' | 'short';
+    /** Override unit labels — a node, or a function of the unit's value (for custom pluralization). */
+    unitLabels?: Partial<Record<TimerUnit, ReactNode | ((value: number) => ReactNode)>>;
+    /** Built-in segment style. `'boxed'` is a square with the number and the unit below. @default 'boxed' */
+    segmentVariant?: 'boxed' | 'plain';
+    /** Fully custom segment renderer (segments variant). Overrides `segmentVariant`. */
+    renderSegment?: (segment: TimerSegment, index: number) => ReactNode;
+    /** Content rendered between segments (e.g. `':'`). */
+    segmentSeparator?: ReactNode;
+    /** Content shown alongside the timer (e.g. a caption). */
+    label?: ReactNode;
+    /** Where `label` sits relative to the timer. @default 'bottom' */
+    labelPlacement?: TimerLabelPlacement;
+    /** Fired once when a countdown reaches zero. */
+    onComplete?: () => void;
+    /** Fired each tick with the current seconds. */
+    onTick?: (seconds: number) => void;
+    /** Override class names on internal elements. */
+    classes?: Partial<TimerClasses>;
+    className?: string;
+    style?: CSSProperties;
+    'aria-label'?: string;
+}
+/**
+ * A flexible timer: countdown or stopwatch, shown as digits or a progress ring,
+ * with an optional attached label. Uncontrolled with `autoStart` + an imperative
+ * ref (`start`/`pause`/`reset`/`restart`), or display-only via `value`.
+ *
+ * @example
+ * // Countdown with a caption underneath
+ * <Timer mode="countdown" duration={90} label="Time left" onComplete={onDone} />
+ *
+ * @example
+ * // Ring stopwatch driven by a ref
+ * const t = useRef<TimerHandle>(null);
+ * <Timer ref={t} mode="stopwatch" duration={60} variant="ring" autoStart={false} />
+ */
+export declare const Timer: import('react').ForwardRefExoticComponent<TimerProps & import('react').RefAttributes<TimerHandle>>;

package/components/Timer/index.d.ts

@@ -0,0 +1,2 @@
+export { Timer } from './Timer';
+export type { TimerProps, TimerHandle, TimerClasses, TimerMode, TimerVariant, TimerLabelPlacement, TimerUnit, TimerSegment, } from './Timer';