@overdoser/react-toolkit 0.0.3 → 0.0.4

package/AGENTS.md

@@ -25,18 +25,16 @@ For exhaustive component reference (every prop, every variant, every signature),
 - 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`.
 
-## Hard rules (don't violate)
-
-1. **Don't ship raw `<button>`, `<input>`, `<select>`, `<textarea>`, `<a>` for UI affordances.** Use the toolkit's `Button`, `Input`, `Select`, `Textarea`, `Link` so styling and a11y come for free.
-2. **Inside `<Form>`, every focusable input must be wrapped in `<FormField>`.** Don't manually wire `value`/`onChange`/`name` on the inner input — `FormField` clones the child to inject them.
-3. **`<Modal>` content must be wrapped in `Modal.Header`, `Modal.Body`, `Modal.Footer`.** Raw children may render but they bypass focus targeting and styling.
-4. **Use `inputSize`, not `size`,** on `Input`/`Select`/`Textarea`. The native `size` attribute is preserved separately.
-5. **`Form`'s prop is `form`, not `formMethods`.** Pass the result of `useForm()`.
-6. **`Button` uses `loadingStyle`** (`'dots' | 'shimmer' | 'border'`), not `loadingType`.
-7. **`Typography` `color`** is an enum (`default | muted | primary | danger | success`), not a free-form string. The native HTML `color` attribute is omitted.
-8. **`Popover` content goes in the `content` prop**, not as children. `children` is typed `never`.
-9. **Server-side `Table`:** if you provide `onSort`, the table will not sort or paginate `data` itself. Your backend must return the page already sorted and sliced. Pass `pagination.totalRows` for the paginator to compute pages.
-10. **Theming is via CSS custom properties** (`--crk-*`) on `:root`. Don't override styles by hand-writing CSS that targets internal class names — those are hashed and unstable. Use the `classes` prop where finer control is needed.
+## 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
 

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>>;

package/components/inputs/Radio/Radio.d.ts

@@ -1,16 +1,31 @@
 import { ComponentPropsWithRef, ReactNode, CSSProperties } from 'react';
 export interface RadioGroupProps {
+    /** Shared `name` attribute applied to every `Radio` child via context. */
     name: string;
+    /** Controlled selected value. */
     value?: string;
+    /** Fires with the newly selected value. */
     onChange?: (value: string) => void;
     className?: string;
     style?: CSSProperties;
     children: ReactNode;
     id?: string;
+    /** Accessible label. Use this OR `aria-labelledby`. */
     'aria-label'?: string;
     'aria-labelledby'?: string;
+    /** Marks the group as required (`aria-required`). */
     required?: boolean;
 }
+/**
+ * Manages selection state and `name` attribute for a group of `<Radio>`s via context.
+ * Inside a `<RadioGroup>`, `Radio` does not need its own `name`/`checked`/`onChange`.
+ *
+ * @example
+ * <RadioGroup name="plan" value={plan} onChange={setPlan} aria-label="Plan">
+ *   <Radio value="free" label="Free" />
+ *   <Radio value="pro" label="Pro" />
+ * </RadioGroup>
+ */
 export declare const RadioGroup: {
     ({ name, value, onChange, className, style, children, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, required, }: RadioGroupProps): import("react/jsx-runtime").JSX.Element;
     displayName: string;
@@ -21,8 +36,15 @@ export interface RadioClasses {
     label: string;
 }
 export interface RadioProps extends Omit<ComponentPropsWithRef<'input'>, 'type'> {
+    /** Visible label rendered next to the radio. */
     label?: ReactNode;
+    /** Value of this option. Required (used to identify the radio in the group). */
     value: string;
+    /** Override class names on internal elements. */
     classes?: Partial<RadioClasses>;
 }
+/**
+ * A single radio option. Inside a `<RadioGroup>`, `name`/`checked`/`onChange`
+ * come from group context — do not pass them manually.
+ */
 export declare const Radio: import('react').ForwardRefExoticComponent<Omit<RadioProps, "ref"> & import('react').RefAttributes<HTMLInputElement>>;

package/components/inputs/Select/Select.d.ts

@@ -1,8 +1,12 @@
 import { ComponentPropsWithRef } from 'react';
 export interface SelectOption {
+    /** Value sent through `onValueChange` / form. */
     value: string;
+    /** Plain-text label (used for filter matching and the trigger text). */
     label: string;
+    /** Optional rich rendered content shown in the menu in place of `label`. */
     content?: React.ReactNode;
+    /** Non-interactive when true. */
     disabled?: boolean;
 }
 export interface SelectClasses {
@@ -16,18 +20,41 @@ export interface SelectClasses {
     chipRemove: string;
 }
 export interface SelectProps extends Omit<ComponentPropsWithRef<'select'>, 'onChange' | 'value'> {
+    /** Toolkit size scale (independent of the native `size` HTML attribute). @default 'md' */
     inputSize?: 'sm' | 'md' | 'lg';
+    /** Apply error styling. @default false */
     error?: boolean;
+    /** Options. When omitted in native mode, `children` is used instead. */
     options?: SelectOption[];
+    /** Placeholder shown when no value is selected. @default 'Select...' */
     placeholder?: string;
+    /** Override class names on internal elements. */
     classes?: Partial<SelectClasses>;
+    /** Replaces the native `<select>` with a filterable dropdown. @default false */
     searchable?: boolean;
+    /** Placeholder for the search input (searchable mode). @default 'Search...' */
     searchPlaceholder?: string;
+    /** Native + searchable mode change event (synthetic in searchable mode). */
     onChange?: (e: React.ChangeEvent<HTMLSelectElement>) => void;
+    /** Single-mode value-only callback. */
     onValueChange?: (value: string) => void;
+    /** `string` for single mode, `string[]` for multi mode. */
     value?: string | string[];
+    /** Enable multi-select with chip rendering and search. @default false */
     multiple?: boolean;
+    /** Multi-mode callback. */
     onValuesChange?: (values: string[]) => void;
+    /** Clear the search query after each toggle in multi mode. @default true */
     clearSearchOnSelect?: boolean;
 }
+/**
+ * Three internal modes, picked automatically:
+ * - **Native** (default): wraps `<select>`. Use `onChange` or pass options as `children`.
+ * - **Searchable**: set `searchable`. Custom dropdown with text filter.
+ * - **Multi**: set `multiple`. Chip-based multi-select with text filter.
+ *
+ * @example Native: <Select options={[{ value: 'a', label: 'A' }]} onValueChange={setValue} />
+ * @example Searchable: <Select searchable options={users} value={id} onValueChange={setId} />
+ * @example Multi: <Select multiple options={tags} value={selected} onValuesChange={setSelected} />
+ */
 export declare const Select: import('react').ForwardRefExoticComponent<Omit<SelectProps, "ref"> & import('react').RefAttributes<HTMLSelectElement>>;

package/components/inputs/Textarea/Textarea.d.ts

@@ -1,8 +1,17 @@
 import { ComponentPropsWithRef } from 'react';
 export interface TextareaProps extends ComponentPropsWithRef<'textarea'> {
+    /** Toolkit size scale. @default 'md' */
     inputSize?: 'sm' | 'md' | 'lg';
+    /** Apply error styling. @default false */
     error?: boolean;
+    /** User resize handle direction. Ignored when `autoExpand` is true. @default 'vertical' */
     resize?: 'none' | 'vertical' | 'horizontal' | 'both';
+    /** Auto-grow height to fit content. Suppresses `resize` while active. @default true */
     autoExpand?: boolean;
 }
+/**
+ * Themed textarea with optional auto-expanding height.
+ *
+ * @example <Textarea placeholder="Bio" rows={3} autoExpand />
+ */
 export declare const Textarea: import('react').ForwardRefExoticComponent<Omit<TextareaProps, "ref"> & import('react').RefAttributes<HTMLTextAreaElement>>;

package/index.d.ts

@@ -1,3 +1,17 @@
+/**
+ * @overdoser/react-toolkit
+ *
+ * Themeable React component library with SCSS modules.
+ *
+ * AI assistants: see `llms.txt` and `AGENTS.md` at the package root for an
+ * exhaustive component reference, recipes, and integration rules. A
+ * machine-readable spec is available in `manifest.json`.
+ *
+ * Setup: `import '@overdoser/react-toolkit/theme.css';` once at the app entry.
+ * Theme via `--crk-*` CSS custom properties on `:root`.
+ *
+ * @packageDocumentation
+ */
 export { Button } from './components/Button';
 export type { ButtonProps, ButtonClasses } from './components/Button';
 export { Link } from './components/Link';

package/llms.txt

@@ -278,7 +278,7 @@ Requires `react-hook-form` peer dependency.
 Imports: `import { Form, FormField, FormRow } from '@overdoser/react-toolkit'`
 
 `Form<T>` props:
-- `form: UseFormReturn<T>` — **the prop name is `form`, not `formMethods`**. Pass the result of `useForm()`.
+- `form: UseFormReturn<T>` — pass the result of `useForm()`.
 - `onSubmit: SubmitHandler<T>` — passed through `form.handleSubmit`.
 - `errors?: ReactNode[]` — top-of-form error list (rendered above children with `role="alert"`).
 
@@ -324,7 +324,7 @@ Import: `import { Input } from '@overdoser/react-toolkit'`
 Element: `<input>` (forwards ref). Native `prefix` attribute is omitted in favor of the prop below.
 
 Props:
-- `inputSize?: 'sm' | 'md' | 'lg'` — default `'md'`. **Note**: it is `inputSize`, NOT `size` — the native HTML `size` attribute is preserved separately.
+- `inputSize?: 'sm' | 'md' | 'lg'` — default `'md'`. Toolkit size scale; independent of the native HTML `size` attribute.
 - `error?: boolean` — default `false`
 - `prefix?: ReactNode` — content rendered inside the input wrapper, before the field.
 - `suffix?: ReactNode` — same, after the field.
@@ -344,7 +344,7 @@ Three internal modes, picked automatically:
 3. **Multi** — set `multiple`. Chip-based multi-select with text filter.
 
 Props:
-- `inputSize?: 'sm' | 'md' | 'lg'` — default `'md'`. (Same naming convention as `Input`.)
+- `inputSize?: 'sm' | 'md' | 'lg'` — default `'md'`. Toolkit size scale.
 - `error?: boolean`
 - `options?: { value: string; label: string; content?: ReactNode; disabled?: boolean }[]`
 - `placeholder?: string` — default `'Select...'` for searchable/multi.
@@ -466,15 +466,13 @@ Binds global keydown listeners keyed by `KeyboardEvent.key`. `active` defaults t
 useKeyboard({ Escape: () => close(), Enter: () => confirm() }, isOpen);
 ```
 
-## Common gotchas (LLM-relevant)
-
-1. **`Form` prop is `form`, not `formMethods`.** Older docs may show `formMethods`.
-2. **`Button` prop is `loadingStyle`, not `loadingType`.**
-3. **`Input` / `Select` / `Textarea` size prop is `inputSize`** — the native `size` attribute still works as itself.
-4. **`Typography` does not accept a free-form `color` string** — only the listed presets. The native `color` attr is omitted.
-5. **`Dropdown` is dual-mode.** If you pass `options`, the `trigger` prop is ignored and it behaves like a select. If you don't, you must pass `trigger` and `<DropdownItem>` children.
-6. **`Popover.children` is typed `never`** — content goes through the `content` prop.
-7. **`Modal` requires `Modal.Header`/`Body`/`Footer`** — don't put raw markup inside `<Modal>`.
-8. **`FormField` clones its single child** to inject `value`/`onChange`/`id`/`name`/`error`/aria. Never put more than one element inside, never wire those props on the child manually inside a form.
-9. **Server-side `Table`:** when `onSort` is provided, the table won't sort or paginate `data` itself — your server must.
-10. **Theme stylesheet is a separate import**: `'@overdoser/react-toolkit/theme.css'`. Without it, components render unstyled.
+## Conventions worth knowing
+
+1. **Inputs use `inputSize`** for the toolkit size scale. The native `size` HTML attribute is independent.
+2. **`Typography` `color`** accepts only the preset tokens; for arbitrary colors use `style` or `className`.
+3. **`Dropdown` has two modes:** with `options` + `value` + `onChange` it acts as a select input (the `trigger` prop is unused). Without `options`, pass `trigger` and `<DropdownItem>` children.
+4. **`Popover` content** goes through the `content` prop.
+5. **`Modal` content** lives in `Modal.Header`, `Modal.Body`, and `Modal.Footer` — these compound components own the spacing and aria wiring.
+6. **`FormField` clones its single child** to inject `value`/`onChange`/`id`/`name`/`error`/aria. Pass exactly one input element and let `FormField` wire it.
+7. **Server-side `Table`:** providing `onSort` puts the table in controlled mode — the consumer is responsible for sorting and slicing `data` server-side.
+8. **Theme stylesheet** is imported separately: `'@overdoser/react-toolkit/theme.css'`. Without it, components render unstyled.

package/manifest.json

@@ -41,7 +41,7 @@
       "props": {
         "variant": { "type": "enum", "values": ["h1", "h2", "h3", "h4", "h5", "h6", "p", "span", "label"], "default": "p" },
         "weight": { "type": "enum", "values": ["normal", "medium", "semibold", "bold"] },
-        "color": { "type": "enum", "values": ["default", "muted", "primary", "danger", "success"], "notes": "Native color attribute is omitted in favor of these presets." },
+        "color": { "type": "enum", "values": ["default", "muted", "primary", "danger", "success"], "notes": "For arbitrary colors, use style or className." },
         "align": { "type": "enum", "values": ["left", "center", "right"] },
         "truncate": { "type": "boolean", "default": false }
       }
@@ -185,7 +185,7 @@
       "requires": "react-hook-form",
       "generic": "T extends FieldValues",
       "props": {
-        "form": { "type": "UseFormReturn<T>", "required": true, "notes": "The result of useForm(). NOTE: prop is `form`, not `formMethods`." },
+        "form": { "type": "UseFormReturn<T>", "required": true, "notes": "The result of useForm()." },
         "onSubmit": { "type": "SubmitHandler<T>", "required": true },
         "errors": { "type": "ReactNode[]", "notes": "Top-of-form errors rendered above children with role=alert." }
       }
@@ -221,7 +221,7 @@
       "extendsNativeProps": "input (without prefix)",
       "forwardsRef": true,
       "props": {
-        "inputSize": { "type": "enum", "values": ["sm", "md", "lg"], "default": "md", "notes": "Named `inputSize` so the native `size` attribute is preserved." },
+        "inputSize": { "type": "enum", "values": ["sm", "md", "lg"], "default": "md", "notes": "Toolkit size scale; independent of the native `size` HTML attribute." },
         "error": { "type": "boolean", "default": false },
         "prefix": { "type": "ReactNode" },
         "suffix": { "type": "ReactNode" },
@@ -339,17 +339,15 @@
       "notes": "Only needed if you want to manage sort state outside <Table>."
     }
   },
-  "gotchas": [
-    "Form prop is `form`, not `formMethods`.",
-    "Button prop is `loadingStyle`, not `loadingType`.",
-    "Input/Select/Textarea size prop is `inputSize`, not `size` — native size attribute is preserved.",
-    "Typography color is restricted to enum presets; native `color` HTML attribute is omitted.",
-    "Dropdown is dual-mode: `options` triggers select-mode and `trigger` is ignored.",
-    "Popover.children is typed `never` — content goes through the `content` prop.",
-    "Modal contents must be wrapped in Modal.Header/Body/Footer.",
-    "FormField clones a single child element to inject form props — don't wire value/onChange manually.",
-    "Server-side Table mode (onSort provided) means Table renders data verbatim — no internal sort or pagination slicing.",
-    "Theme stylesheet must be imported separately: '@overdoser/react-toolkit/theme.css'."
+  "conventions": [
+    "Inputs use `inputSize` for the toolkit size scale; the native `size` HTML attribute is independent.",
+    "Typography color accepts only the preset tokens; for arbitrary colors use `style` or `className`.",
+    "Dropdown has two modes: with `options` + `value` + `onChange` it acts as a select input (the `trigger` prop is unused); without `options`, pass `trigger` and `<DropdownItem>` children.",
+    "Popover content goes through the `content` prop.",
+    "Modal content lives in Modal.Header / Modal.Body / Modal.Footer compound components.",
+    "FormField clones a single child element to inject form props — pass exactly one input element.",
+    "Server-side Table mode (when `onSort` is provided): the consumer is responsible for sorting and slicing `data` server-side.",
+    "Theme stylesheet is imported separately: '@overdoser/react-toolkit/theme.css'."
   ],
   "recipes": [
     "recipes/login-form.tsx",

package/package.json

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