@overdoser/react-toolkit 0.0.2 → 0.0.4

package/AGENTS.md

@@ -0,0 +1,107 @@
+# AGENTS.md — @overdoser/react-toolkit
+
+Guidance for AI coding assistants integrating this library into a consumer project. Drop the relevant rules into your own project's AGENTS.md / CLAUDE.md / Cursor rules / Copilot instructions.
+
+For exhaustive component reference (every prop, every variant, every signature), see `llms.txt` in this package. For machine-readable structured data, see `manifest.json`.
+
+## Setup checklist
+
+1. Install:
+   ```bash
+   npm install @overdoser/react-toolkit
+   ```
+2. Install the optional peer **only if** you'll use `Form`/`FormField`:
+   ```bash
+   npm install react-hook-form
+   ```
+3. Import the theme stylesheet **once** at the app entry point:
+   ```ts
+   import '@overdoser/react-toolkit/theme.css';
+   ```
+   Without this, components render unstyled.
+
+## Import rules
+
+- Always import from the package root: `import { Button } from '@overdoser/react-toolkit'`. Do **not** reach into subpaths (`@overdoser/react-toolkit/dist/...`) — they're not part of the public API.
+- The only valid stylesheet subpath is `@overdoser/react-toolkit/theme.css`.
+
+## Rules
+
+1. **Use the toolkit components for UI affordances** — `Button`, `Input`, `Select`, `Textarea`, `Link`. Styling and a11y come for free.
+2. **Inside `<Form>`, wrap every focusable input in `<FormField>`.** `FormField` clones the child to inject `value`/`onChange`/`name`/`error`/aria — let it.
+3. **`<Modal>` content lives in `Modal.Header`, `Modal.Body`, `Modal.Footer`.** They own focus targeting and spacing.
+4. **Inputs use `inputSize`** (`'sm' | 'md' | 'lg'`) for the toolkit size scale; the native `size` HTML attribute is independent.
+5. **`Typography` `color`** accepts the preset tokens (`default | muted | primary | danger | success`). For arbitrary colors, use `style` or `className`.
+6. **`Popover` content** goes through the `content` prop.
+7. **Server-side `Table`:** providing `onSort` puts the table in controlled mode — the backend returns the page already sorted and sliced. Pass `pagination.totalRows` so the paginator can compute pages.
+8. **Theme via CSS custom properties** (`--crk-*`) on `:root`. For finer overrides, use each component's `classes` prop — internal class names are hashed and unstable.
+
+## Decision flow
+
+- **Need a select?**
+  - Few options, native UX OK → `<Select options={...} />`.
+  - Many options, want a search filter → `<Select searchable options={...} />`.
+  - 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 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 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`.
+
+- **Multi-step / wizard form?** Use one `useForm()` per step OR a single `<Form>` wrapping all steps with conditional rendering. The toolkit doesn't ship a stepper.
+
+## Common shapes (copy-paste)
+
+### Wire a Select inside a Form
+```tsx
+<FormField name="role" label="Role">
+  <Select options={[
+    { value: 'admin', label: 'Admin' },
+    { value: 'member', label: 'Member' },
+  ]} />
+</FormField>
+```
+`FormField` bridges `onChange` → `onValueChange` automatically; just pass `options`.
+
+### Wire a Checkbox inside a Form
+```tsx
+<FormField name="acceptTerms">
+  <Checkbox label="I accept the terms" />
+</FormField>
+```
+`FormField` bridges the boolean form value to `checked`.
+
+### Wire a RadioGroup inside a Form
+```tsx
+<FormField name="plan" label="Plan">
+  <RadioGroup name="plan" aria-label="Plan">
+    <Radio value="free" label="Free" />
+    <Radio value="pro" label="Pro" />
+  </RadioGroup>
+</FormField>
+```
+
+## 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.
+
+- [recipes/login-form.tsx](./recipes/login-form.tsx) — Form + Input + Button with validation rules.
+- [recipes/paginated-table.tsx](./recipes/paginated-table.tsx) — Client-side sortable + paginated table.
+- [recipes/server-side-table.tsx](./recipes/server-side-table.tsx) — Server-driven sort & pagination.
+- [recipes/confirm-modal.tsx](./recipes/confirm-modal.tsx) — Reusable destructive-action confirm dialog.
+- [recipes/searchable-multi-select.tsx](./recipes/searchable-multi-select.tsx) — Multi-select with search and form integration.
+- [recipes/dropdown-menu.tsx](./recipes/dropdown-menu.tsx) — Row action menu with `Dropdown` + `DropdownItem`.
+
+## Anti-patterns to refuse
+
+- "Wrap every component in a custom `Card` div for spacing" — spacing comes from the consumer's layout. Don't pollute toolkit components with wrapper divs.
+- "Inline-style every component instead of using `classes` / `className`" — use `classes` for targeted overrides; reserve `style` for one-off layout tweaks.
+- "Pass `loading` and `disabled` together on `Button`" — `loading` already implies disabled. Doubling up is harmless but redundant.
+- "Mock `react-hook-form` to make `Form` work in tests" — use a real `useForm()` in your test wrappers; the toolkit's `FormField` reads context.
+- "Manually call `e.preventDefault()` on `Form` submit" — `Form` already wraps `onSubmit` in `form.handleSubmit`. Just return data.

package/README.md

@@ -1,11 +1,11 @@
-# @crk/react-toolkit
+# @overdoser/react-toolkit
 
 A modern, themeable React component library with SCSS modules.
 
 ## Installation
 
 ```bash
-npm install @crk/react-toolkit
+npm install @overdoser/react-toolkit
 ```
 
 ## Setup
@@ -13,7 +13,7 @@ npm install @crk/react-toolkit
 Import the stylesheet in your app entry point:
 
 ```ts
-import '@crk/react-toolkit/index.css';
+import '@overdoser/react-toolkit/theme.css';
 ```
 
 ## Theming
@@ -61,13 +61,13 @@ Override `--crk-*` CSS custom properties to customize the theme:
 ### Button
 
 ```tsx
-import { Button } from '@crk/react-toolkit';
+import { Button } from '@overdoser/react-toolkit';
 
 <Button variant="primary" size="md" onClick={handleClick}>
   Save
 </Button>
 
-<Button variant="danger" loading loadingType="dots">
+<Button variant="danger" loading loadingStyle="dots">
   Deleting...
 </Button>
 ```
@@ -75,14 +75,14 @@ import { Button } from '@crk/react-toolkit';
 ### Form
 
 ```tsx
-import { Form, FormField, Input, Button } from '@crk/react-toolkit';
+import { Form, FormField, Input, Button } from '@overdoser/react-toolkit';
 import { useForm } from 'react-hook-form';
 
 function LoginForm() {
-  const methods = useForm();
+  const form = useForm();
 
   return (
-    <Form formMethods={methods} onSubmit={methods.handleSubmit(onSubmit)}>
+    <Form form={form} onSubmit={(values) => console.log(values)}>
       <FormField name="email" label="Email">
         <Input />
       </FormField>

package/components/Button/Button.d.ts

@@ -7,11 +7,25 @@ export interface ButtonClasses {
     dot: string;
 }
 export interface ButtonProps extends ComponentPropsWithRef<'button'> {
+    /** Override class names on internal elements. */
     classes?: Partial<ButtonClasses>;
+    /** Visual style. @default 'primary' */
     variant?: 'primary' | 'secondary' | 'danger' | 'ghost';
+    /** Button size. @default 'md' */
     size?: 'sm' | 'md' | 'lg';
+    /** When true, the button is disabled and `aria-busy` is set. @default false */
     loading?: boolean;
+    /** Loading animation style. Only applied when `loading` is true. @default 'dots' */
     loadingStyle?: 'dots' | 'shimmer' | 'border';
+    /** Stretch the button to fill its container's width. @default false */
     fullWidth?: boolean;
 }
+/**
+ * Styled `<button>` with variants, sizes, and three loading-state animations.
+ *
+ * @example
+ * <Button variant="danger" size="lg" loading loadingStyle="shimmer" onClick={onDelete}>
+ *   Delete
+ * </Button>
+ */
 export declare const Button: import('react').ForwardRefExoticComponent<Omit<ButtonProps, "ref"> & import('react').RefAttributes<HTMLButtonElement>>;

package/components/Dropdown/Dropdown.d.ts

@@ -1,7 +1,10 @@
 import { CSSProperties } from 'react';
 export interface DropdownOption {
+    /** Selected value sent through `onChange`. */
     value: string;
+    /** Visible label in the menu and trigger. */
     label: React.ReactNode;
+    /** When true, the option is non-interactive. */
     disabled?: boolean;
 }
 export interface DropdownClasses {
@@ -13,28 +16,53 @@ export interface DropdownClasses {
     item: string;
 }
 export interface DropdownProps {
-    /** Custom trigger content — used when no `options` are provided */
+    /**
+     * Trigger content for **menu mode**. Required when `options` is not provided.
+     * Ignored in **select mode** (when `options` is provided) — the trigger then
+     * shows the selected option's label.
+     */
     trigger?: React.ReactNode;
+    /** `<DropdownItem>` children for menu mode. */
     children?: React.ReactNode;
+    /** Menu alignment relative to the trigger. @default 'left' */
     align?: 'left' | 'right';
     className?: string;
     style?: CSSProperties;
     id?: string;
+    /** Called when the menu opens. */
     onOpen?: () => void;
+    /** Called when the menu closes (outside click, Escape, or selection). */
     onClose?: () => void;
-    /** When provided, the Dropdown acts as a selectable input */
+    /** Switches Dropdown to **select mode**: the trigger shows the selected option. */
     options?: DropdownOption[];
-    /** Placeholder shown when no value is selected */
+    /** Placeholder shown in select mode when no value is selected. @default 'Select...' */
     placeholder?: React.ReactNode;
-    /** Controlled value */
+    /** Controlled selected value (select mode). */
     value?: string;
-    /** Called when an option is selected */
+    /** Fires when an option is selected (select mode). */
     onChange?: (value: string) => void;
-    /** Error state styling */
+    /** Error styling on the trigger. @default false */
     error?: boolean;
-    /** Full width trigger */
+    /** Stretch trigger and menu to container width. @default true */
     fullWidth?: boolean;
-    /** Custom class overrides for internal elements */
+    /** Override class names on internal elements. */
     classes?: Partial<DropdownClasses>;
 }
+/**
+ * Two-mode dropdown:
+ * - **Menu mode**: pass `trigger` + `<DropdownItem>` children for an action menu.
+ * - **Select mode**: pass `options` + `value` + `onChange` to use as a form input.
+ *   In this mode the `trigger` prop is ignored.
+ *
+ * Closes on outside click and Escape; auto-focuses the first menu item on open.
+ *
+ * @example Menu mode
+ * <Dropdown trigger="More ▾">
+ *   <DropdownItem onClick={onEdit}>Edit</DropdownItem>
+ *   <DropdownItem onClick={onDelete}>Delete</DropdownItem>
+ * </Dropdown>
+ *
+ * @example Select mode
+ * <Dropdown options={options} value={value} onChange={setValue} />
+ */
 export declare const Dropdown: import('react').ForwardRefExoticComponent<DropdownProps & import('react').RefAttributes<HTMLDivElement>>;

package/components/Dropdown/DropdownItem.d.ts

@@ -1,5 +1,10 @@
 import { ComponentPropsWithRef } from 'react';
 export interface DropdownItemProps extends ComponentPropsWithRef<'button'> {
+    /** Non-interactive when true. @default false */
     disabled?: boolean;
 }
+/**
+ * Action item rendered inside a `<Dropdown>` (menu mode).
+ * Renders as a `<button role="menuitem">`; supports all native button props.
+ */
 export declare const DropdownItem: import('react').ForwardRefExoticComponent<Omit<DropdownItemProps, "ref"> & import('react').RefAttributes<HTMLButtonElement>>;

package/components/Form/Form.d.ts

@@ -1,10 +1,26 @@
 import { UseFormReturn, FieldValues, SubmitHandler } from 'react-hook-form';
 export interface FormProps<T extends FieldValues> {
+    /** The result of `useForm()`. */
     form: UseFormReturn<T>;
+    /** Called with validated values. `Form` handles `preventDefault` and validation internally. */
     onSubmit: SubmitHandler<T>;
+    /** Top-of-form error messages. Rendered above children with `role="alert"`. */
     errors?: React.ReactNode[];
     className?: string;
     style?: React.CSSProperties;
     children: React.ReactNode;
 }
+/**
+ * react-hook-form wrapper that provides `FormProvider` and a styled `<form>` element.
+ *
+ * Pair with `<FormField>` for each input — `FormField` reads the form context
+ * via `useFormContext` and clones its child to inject `value`/`onChange`/`name`/`error`.
+ *
+ * @example
+ * const form = useForm<Values>();
+ * <Form form={form} onSubmit={(values) => save(values)}>
+ *   <FormField name="email" label="Email"><Input /></FormField>
+ *   <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;

package/components/Form/FormField.d.ts

@@ -6,14 +6,39 @@ export interface FormFieldClasses {
     helperText: string;
 }
 export interface FormFieldProps {
+    /** Field name. Becomes the field `id` and the react-hook-form path. */
     name: string;
+    /** Field label rendered above the input. */
     label?: ReactNode;
+    /** Helper text rendered below the input (replaced by error message when invalid). */
     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>;
+    /** Override class names on internal elements. */
     classes?: Partial<FormFieldClasses>;
     className?: string;
     style?: CSSProperties;
+    /**
+     * Exactly one input element. `FormField` clones it to inject
+     * `value`/`onChange`/`name`/`id`/`error`/aria props — do NOT pass those manually.
+     *
+     * Supported: `Input`, `Textarea`, `Select`, `Dropdown` (select-mode), `Checkbox`, `Radio`/`RadioGroup`.
+     */
     children: ReactElement;
 }
+/**
+ * Bridges react-hook-form to a single child input via `cloneElement`.
+ * Must be used inside a `<Form>` (which provides `FormProvider`).
+ *
+ * Bridges automatically applied:
+ * - `Select` (multi/searchable) and `Dropdown` (select-mode): `onChange` → `onValueChange`/`onValuesChange`.
+ * - `Checkbox`: when the form value is boolean, it's bridged to `checked`.
+ *
+ * @example
+ * <FormField name="email" label="Email" required rules={{ required: 'Required' }}>
+ *   <Input type="email" />
+ * </FormField>
+ */
 export declare function FormField({ name, label, helperText, required, rules, classes, className, style, children, }: FormFieldProps): import("react/jsx-runtime").JSX.Element;

package/components/Form/FormRow.d.ts

@@ -4,4 +4,5 @@ export interface FormRowProps {
     className?: string;
     style?: CSSProperties;
 }
+/** Horizontal flex row that lays out its children — useful for putting two `<FormField>`s side-by-side. */
 export declare function FormRow({ children, className, style }: FormRowProps): import("react/jsx-runtime").JSX.Element;

package/components/Link/Link.d.ts

@@ -1,6 +1,18 @@
 import { ComponentPropsWithRef } from 'react';
 export interface LinkProps extends ComponentPropsWithRef<'a'> {
+    /** Visual style. @default 'default' */
     variant?: 'default' | 'muted' | 'danger';
+    /**
+     * Mark the link as opening in a new tab.
+     * Sets `target="_blank"` and `rel="noopener noreferrer"`,
+     * and appends a visually-hidden " (opens in a new tab)" suffix for screen readers.
+     * @default false
+     */
     external?: boolean;
 }
+/**
+ * Styled `<a>` with variants and safe external-link defaults.
+ *
+ * @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/List/List.d.ts

@@ -1,9 +1,25 @@
 import { ComponentPropsWithRef } from 'react';
 export interface ListProps extends ComponentPropsWithRef<'ul'> {
+    /**
+     * List style. `'ordered'` renders `<ol>`, `'unordered'` renders `<ul>`,
+     * `'none'` renders `<ul>` without bullets.
+     * @default 'unordered'
+     */
     variant?: 'unordered' | 'ordered' | 'none';
+    /** Vertical spacing between items. @default 'md' */
     spacing?: 'sm' | 'md' | 'lg';
 }
+/**
+ * Themed list (`<ul>` or `<ol>` based on `variant`).
+ *
+ * @example
+ * <List variant="ordered" spacing="lg">
+ *   <ListItem>First</ListItem>
+ *   <ListItem>Second</ListItem>
+ * </List>
+ */
 export declare const List: import('react').ForwardRefExoticComponent<Omit<ListProps, "ref"> & import('react').RefAttributes<HTMLOListElement | HTMLUListElement>>;
 export interface ListItemProps extends ComponentPropsWithRef<'li'> {
 }
+/** Themed `<li>`. Use only inside `<List>`. */
 export declare const ListItem: import('react').ForwardRefExoticComponent<Omit<ListItemProps, "ref"> & import('react').RefAttributes<HTMLLIElement>>;

package/components/Modal/Modal.d.ts

@@ -11,6 +11,7 @@ export interface ModalHeaderProps {
     children: ReactNode;
     className?: string;
     style?: CSSProperties;
+    /** When provided, renders an "×" close button in the header. */
     onClose?: () => void;
 }
 export interface ModalBodyProps {
@@ -27,15 +28,23 @@ declare const Header: FC<ModalHeaderProps>;
 declare const Body: FC<ModalBodyProps>;
 declare const Footer: FC<ModalFooterProps>;
 export interface ModalProps {
+    /** Whether the modal is visible. */
     open: boolean;
+    /** Called when the user requests close (backdrop, Escape, or `Modal.Header` close button). */
     onClose: () => void;
+    /** Close when the backdrop is clicked. @default true */
     closeOnBackdrop?: boolean;
+    /** Close when Escape is pressed. @default true */
     closeOnEscape?: boolean;
+    /** Modal size. `'fullscreen'` covers the viewport. @default 'md' */
     size?: 'sm' | 'md' | 'lg' | 'fullscreen';
+    /** Override class names on internal elements. */
     classes?: Partial<ModalClasses>;
     className?: string;
     style?: CSSProperties;
+    /** Should be `<Modal.Header>`, `<Modal.Body>`, and `<Modal.Footer>`. */
     children: ReactNode;
+    /** Accessible label. Use this OR `aria-labelledby`. If neither is set, `Modal.Header` is auto-wired as `aria-labelledby`. */
     'aria-label'?: string;
     'aria-labelledby'?: string;
 }
@@ -44,5 +53,19 @@ type ModalComponent = ReturnType<typeof forwardRef<HTMLDivElement, ModalProps>>
     Body: typeof Body;
     Footer: typeof Footer;
 };
+/**
+ * Portal-based modal with focus trap, body scroll lock, and Escape/backdrop close.
+ * Compose with `Modal.Header`, `Modal.Body`, and `Modal.Footer`.
+ *
+ * @example
+ * <Modal open={open} onClose={() => setOpen(false)} size="md">
+ *   <Modal.Header onClose={() => setOpen(false)}>Title</Modal.Header>
+ *   <Modal.Body>Content</Modal.Body>
+ *   <Modal.Footer>
+ *     <Button variant="ghost" onClick={() => setOpen(false)}>Cancel</Button>
+ *     <Button variant="primary" onClick={confirm}>OK</Button>
+ *   </Modal.Footer>
+ * </Modal>
+ */
 export declare const Modal: ModalComponent;
 export {};

package/components/Popover/Popover.d.ts

@@ -5,14 +5,32 @@ export interface PopoverClasses {
     popover: string;
 }
 export interface PopoverProps {
+    /** Trigger content. Wrapped in an internal `<button>`. */
     trigger: React.ReactNode;
+    /** Panel content. Rendered inside a `[role="dialog"]` when open. */
     content: React.ReactNode;
+    /** Side of the trigger to anchor the panel to. @default 'bottom' */
     position?: 'top' | 'bottom' | 'left' | 'right';
+    /** Controlled open state. */
     open?: boolean;
+    /** Called when the open state changes. */
     onOpenChange?: (open: boolean) => void;
+    /** Override class names on internal elements. */
     classes?: Partial<PopoverClasses>;
     className?: string;
     style?: CSSProperties;
+    /** Use the `content` prop. */
     children?: never;
 }
+/**
+ * Anchored popover panel. Closes on outside click and Escape; auto-focuses
+ * the first focusable element inside `content` when opened.
+ *
+ * @example
+ * <Popover
+ *   trigger="Help"
+ *   content={<p>Some help text</p>}
+ *   position="right"
+ * />
+ */
 export declare const Popover: import('react').ForwardRefExoticComponent<PopoverProps & import('react').RefAttributes<HTMLDivElement>>;

package/components/Table/Table.d.ts

@@ -1,11 +1,17 @@
 import { ReactNode } from 'react';
 import { SortConfig } from './useTableSort';
 export interface ColumnDef<T> {
+    /** Object key on each row to read the cell value from. */
     key: keyof T & string;
+    /** Header content (string or any ReactNode). */
     header: ReactNode;
+    /** Enable click-to-sort on the header. */
     sortable?: boolean;
+    /** Custom cell renderer; defaults to rendering `row[key]`. */
     render?: (value: T[keyof T], row: T, index: number) => ReactNode;
+    /** Column width (CSS value). */
     width?: string | number;
+    /** Text alignment for cells in this column. */
     align?: 'left' | 'center' | 'right';
 }
 export interface PaginationConfig {
@@ -31,25 +37,49 @@ export interface TableClasses {
     pageButton: string;
 }
 export interface TableProps<T extends Record<string, unknown>> {
+    /** Row data. */
     data: T[];
+    /** Column definitions. */
     columns: ColumnDef<T>[];
-    /** Controlled sort config — when provided with onSort, sorting is external (server-side) */
+    /** Controlled sort config. Pair with `onSort` for server-side sorting. */
     sortConfig?: SortConfig[];
-    /** Sort callback — when provided, Table won't sort data internally */
+    /**
+     * Sort callback. When provided, Table is in **controlled** mode and will
+     * NOT sort `data` internally and will NOT slice for pagination — your
+     * server is expected to handle both.
+     */
     onSort?: (config: SortConfig[]) => void;
-    /** Enable multi-column sort via Ctrl+click (default: true) */
+    /** Enable multi-column sort via Ctrl/Cmd-click on a sortable header. @default true */
     multiSort?: boolean;
+    /** Alternate row backgrounds. @default false */
     striped?: boolean;
+    /** Highlight rows on hover. @default false */
     hoverable?: boolean;
+    /** Tighter row padding. @default false */
     compact?: boolean;
     className?: string;
     style?: React.CSSProperties;
+    /** Column key to use as React `key` per row. Falls back to row index. */
     rowKey?: keyof T & string;
+    /** Content rendered when `data` is empty. @default 'No data' */
     emptyMessage?: ReactNode;
-    /** Pagination config — when provided, shows a paginator below the table */
+    /** When provided, renders a paginator below the table. */
     pagination?: PaginationConfig;
+    /** Override class names on internal elements. */
     classes?: Partial<TableClasses>;
 }
+/**
+ * Generic data table with sortable columns, multi-sort (Ctrl/Cmd-click), and
+ * client- or server-side pagination.
+ *
+ * Sort cycle on header click: `none → asc → desc → none`.
+ *
+ * **Client-side mode** (default): omit `onSort`. Table sorts and paginates internally.
+ *
+ * **Controlled mode**: pass `sortConfig` + `onSort`. Your server returns the
+ * page already sorted and sliced; pass `pagination.totalRows` so the
+ * paginator can compute page count.
+ */
 declare function TableInner<T extends Record<string, unknown>>({ data, columns, sortConfig: controlledSortConfig, onSort, multiSort, striped, hoverable, compact, className, style, rowKey, emptyMessage, pagination, classes, }: TableProps<T>): import("react/jsx-runtime").JSX.Element;
 export declare const Table: typeof TableInner;
 export {};

package/components/Typography/Typography.d.ts

@@ -1,12 +1,22 @@
 import { ComponentPropsWithRef } from 'react';
 type TypographyVariant = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span' | 'label';
 export interface TypographyProps extends Omit<ComponentPropsWithRef<'p'>, 'color'> {
+    /** HTML tag to render. @default 'p' */
     variant?: TypographyVariant;
+    /** Font weight. */
     weight?: 'normal' | 'medium' | 'semibold' | 'bold';
+    /** Preset color token. For arbitrary colors, use `style` or `className`. */
     color?: 'default' | 'muted' | 'primary' | 'danger' | 'success';
+    /** Text alignment. */
     align?: 'left' | 'center' | 'right';
+    /** Single-line ellipsis truncation. @default false */
     truncate?: boolean;
     children: React.ReactNode;
 }
+/**
+ * Renders `h1`–`h6`, `p`, `span`, or `label` with theme-aware typography tokens.
+ *
+ * @example <Typography variant="h2" weight="bold" color="primary">Title</Typography>
+ */
 export declare const Typography: import('react').ForwardRefExoticComponent<Omit<TypographyProps, "ref"> & import('react').RefAttributes<HTMLElement>>;
 export {};

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

@@ -5,8 +5,22 @@ export interface CheckboxClasses {
     label: string;
 }
 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 */
     indeterminate?: boolean;
+    /** Override class names on internal elements. */
     classes?: Partial<CheckboxClasses>;
 }
+/**
+ * Themed checkbox. The `<input>` is wrapped in a `<label>` so clicking the
+ * label toggles the input.
+ *
+ * @example
+ * <Checkbox
+ *   label="Remember me"
+ *   checked={remember}
+ *   onChange={(e) => setRemember(e.target.checked)}
+ * />
+ */
 export declare const Checkbox: import('react').ForwardRefExoticComponent<Omit<CheckboxProps, "ref"> & import('react').RefAttributes<HTMLInputElement>>;

package/components/inputs/Input/Input.d.ts

@@ -6,10 +6,20 @@ export interface InputClasses {
     suffix: string;
 }
 export interface InputProps extends Omit<ComponentPropsWithRef<'input'>, 'prefix'> {
+    /** Toolkit size scale (independent of the native `size` HTML attribute). @default 'md' */
     inputSize?: 'sm' | 'md' | 'lg';
+    /** Apply error styling. @default false */
     error?: boolean;
+    /** Content rendered inside the input wrapper, before the field. */
     prefix?: ReactNode;
+    /** Content rendered inside the input wrapper, after the field. */
     suffix?: ReactNode;
+    /** Override class names on internal elements. */
     classes?: Partial<InputClasses>;
 }
+/**
+ * Themed text input with optional `prefix`/`suffix` slots.
+ *
+ * @example <Input type="email" inputSize="lg" prefix="@" placeholder="username" />
+ */
 export declare const Input: import('react').ForwardRefExoticComponent<Omit<InputProps, "ref"> & import('react').RefAttributes<HTMLInputElement>>;