@overdoser/react-toolkit 0.0.15 → 0.1.0

package/AGENTS.md

@@ -19,6 +19,11 @@ For exhaustive component reference (every prop, every variant, every signature),
    import '@overdoser/react-toolkit/theme.css';
    ```
    Without this, components render unstyled.
+   - **Want `className` / `classes.*` overrides to always win regardless of bundler order?** Import the layered twin instead:
+     ```ts
+     import '@overdoser/react-toolkit/theme.layered.css';
+     ```
+     It wraps all toolkit CSS in a `crk` cascade layer, so any of your own *unlayered* rules beat it deterministically. See "Customizing styles" below.
 
 ## Import rules
 
@@ -44,6 +49,8 @@ For exhaustive component reference (every prop, every variant, every signature),
   - Multi-pick with chips → `<Select multiple options={...} onValuesChange={...} />`.
   - You want it to look like a "menu trigger" instead of a form input → `<Dropdown options={...} value={...} onChange={...} />` (select-mode dropdown).
 
+- **Need to pick several values from a small fixed set?** → `<CheckboxGroup options={...} value={...} onChange={...} />` (a checkbox list, or `variant="chips"` for toggle chips). For a large/searchable set, prefer `<Select multiple>` instead.
+
 - **Need a menu (Edit / Delete / Archive)?** → `<Dropdown trigger={...}>` with `<DropdownItem>` children.
 
 - **Need a tooltip / hover card / contextual panel?** → `<Popover trigger={...} content={...} />`.
@@ -96,6 +103,26 @@ For exhaustive component reference (every prop, every variant, every signature),
 </FormField>
 ```
 
+### Wire a CheckboxGroup (multi-value) inside a Form
+```tsx
+<FormField name="interests" label="Interests" rules={{ validate: (v) => v.length > 0 || 'Pick at least one' }}>
+  <CheckboxGroup
+    variant="chips" // or omit for a checkbox list
+    options={[
+      { value: 'design', label: 'Design' },
+      { value: 'eng', label: 'Engineering' },
+    ]}
+  />
+</FormField>
+```
+`CheckboxGroup` binds `value: string[]` / `onChange(values)` directly — no bridge needed.
+
+## Customizing styles
+
+- **Theme tokens:** override `--crk-*` custom properties on `:root` (colors, fonts, spacing, radii). This is the primary, stable customization surface.
+- **Per-element overrides:** use each component's `classes` prop (and `className`) — internal class names are hashed and unstable, so never target them directly.
+- **Make overrides deterministic:** `className` / `classes.*` are plain CSS classes; they only beat the toolkit's built-in class if your stylesheet is inserted *after* it, which the bundler controls. To guarantee precedence, import `@overdoser/react-toolkit/theme.layered.css` (everything ships in a `crk` cascade layer, so your unlayered rules always win), **or** add `@import '@overdoser/react-toolkit/theme.css' layer(crk);` as the first line of your global CSS. Caveat: an aggressive global reset that is itself unlayered will then also override the toolkit's base styles — put your reset in its own earlier layer if so. `theme.css` and `theme.layered.css` are identical except the layer wrapper — import exactly one, and token (`--crk-*`) theming works the same in either.
+
 ## Recipes
 
 Full copy-paste-able files live alongside this doc. Each is one self-contained file that you can drop into a project. Adjust types/imports for your codebase.

package/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+All notable changes to `@overdoser/react-toolkit` are documented here.
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
+project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0]
+
+This release adds a `CheckboxGroup` component, a cascade-layered stylesheet for
+deterministic style overrides, and viewport-aware popovers — plus a round of
+`Form` ergonomics. A few **defaults changed** (forms, popovers, links); they are
+all opt-out (see ⚠️ below).
+
+### ⚠️ Notable default changes (visual)
+
+No API was removed or renamed, but some components now **render differently by
+default**. To restore the previous behavior:
+
+- **Forms reserve space for validation messages** so an error no longer shifts
+  the layout, the error now appears *between the input and the description*
+  (instead of replacing the description), inter-field/element gaps are tighter,
+  and labels are bolder (weight 700). Opt out per field or form-wide with
+  `reserveErrorSpace={false}`.
+- **Popovers reposition to stay in the viewport** (flip to the opposite side /
+  shift near a screen edge). Opt out with `<Popover autoPosition={false} />`.
+- **Links that open in a new tab show an inline ↗ icon** (`external` or a manual
+  `target="_blank"`). Opt out with `<Link hideExternalIcon />`.
+- `theme.css` is **unchanged** — the new cascade layer is opt-in via
+  `theme.layered.css`, so existing stylesheet imports are unaffected.
+
+### Added
+
+- **`CheckboxGroup` component** — multi-value selection from a fixed option set,
+  rendered as a checkbox list (`variant="checkbox"`, default) or toggleable chips
+  (`variant="chips"`). Supports `chipShape` (`pill | rounded | square`),
+  `chipCheckmark` (with constant chip width — padding compensates for the mark),
+  `orientation`, `disabled`, `error`, `name`, `required`, and a `classes`
+  override (`{ group, option, chip, chipSelected }`). Binds directly inside
+  `FormField` (`value: string[]` / `onChange(values)`), no bridge needed.
+- **`theme.layered.css` stylesheet export** — identical to `theme.css` but
+  wrapped in a `@layer crk` cascade layer, so consumer `className` / `classes.*`
+  overrides win deterministically regardless of bundler import order. Import
+  exactly one of the two.
+- **`Form` props** `reserveErrorSpace` (form-wide default for all fields) and
+  `fieldClasses` (form-wide `classes` default, merged with each field's own).
+- **`FormField` prop** `reserveErrorSpace` (`boolean | number | string`) and a
+  `--crk-field-error-min-height` token to size the reserved space.
+- **`Popover` prop** `autoPosition` (default `true`) for viewport-aware flipping
+  and edge shifting.
+- **`Link` prop** `hideExternalIcon` to suppress the new-tab icon.
+- `FormFieldClasses` gained a `message` key (the validation/reserve slot).
+
+### Changed
+
+- `FormField` validation layout reworked so the field's outer height stays
+  constant when a one-line error toggles (the reserved spacer sits after the
+  description and swaps 1:1 with the error). Multi-line errors grow past it.
+- Form-wide reservation off (`<Form reserveErrorSpace={false}>`) uses a slightly
+  larger inter-field gap to compensate for the absent reserved line.
+
+### Fixed
+
+- **Searchable single-select** dropdown was mispositioned / rendered as a ~1px
+  sliver in portal mode because it anchored to the trigger button (hidden while
+  open); it now anchors to the always-visible wrapper.
+- **Native `Select`** silently dropped `onValueChange` and could trip React's
+  controlled-field warning when given `value` + `onValueChange`; it now wires
+  both `onChange` and `onValueChange`.
+
+### Docs
+
+- `README`, `llms.txt`, `manifest.json`, and `AGENTS.md` updated for all of the
+  above, including a `theme.css` vs `theme.layered.css` comparison and the
+  cascade-layer caveat (an unlayered global reset also beats layered toolkit
+  styles — put resets in an earlier layer).

package/README.md

@@ -28,22 +28,79 @@ Override `--crk-*` CSS custom properties to customize the theme:
 }
 ```
 
+For per-element tweaks, every component accepts `className` and a `classes` prop
+(internal class names are hashed — never target them directly).
+
+### `theme.css` vs `theme.layered.css`
+
+The package ships two stylesheets with **identical content** — same rules, same
+hashed class names, same `--crk-*` tokens. The only difference is that
+`theme.layered.css` wraps everything in a CSS cascade layer:
+
+```css
+@layer crk {
+  /* ...the entire stylesheet... */
+}
+```
+
+That wrapper changes how your overrides compete with the toolkit's styles.
+Import **exactly one** of the two (never both).
+
+**The problem with plain `theme.css`.** The overrides you pass via `className` /
+`classes.*` are plain CSS classes, so they tie with the toolkit's own class on
+specificity — the winner is decided by **stylesheet source order**, which your
+bundler controls. In many setups the toolkit CSS is injected *after* your app
+CSS, so your overrides silently lose.
+
+**What the layer fixes.** A core rule of cascade layers: **any unlayered style
+beats any layered style, regardless of specificity or import order.** Since
+`theme.layered.css` puts the whole toolkit in the `crk` layer, your own
+(unlayered) rules — including every `className` / `classes.*` override — always
+win, deterministically:
+
+```ts
+import '@overdoser/react-toolkit/theme.layered.css'; // instead of theme.css
+```
+
+(If you import CSS from a `.css` entry instead of JS, the equivalent is
+`@import '@overdoser/react-toolkit/theme.css' layer(crk);` as the first line.)
+
+| | `theme.css` | `theme.layered.css` |
+| --- | --- | --- |
+| Override wins by | specificity, then import order (bundler-dependent) | **always** (unlayered beats layered) |
+| `--crk-*` token theming | ✅ | ✅ (identical) |
+| Affected by a global CSS reset | only via normal specificity/order | ⚠️ an *unlayered* reset also beats the toolkit's base styles |
+
+**The one caveat.** Because layered styles lose to *all* unlayered styles, an
+aggressive global reset (e.g. `button { font: inherit }`) would also override the
+toolkit's base styles under `theme.layered.css`. If you ship a heavy reset, put
+it in its own earlier layer so the order is explicit:
+
+```css
+@layer reset, crk;
+```
+
+**Rule of thumb:** if you heavily customize component internals via
+`classes` / `className`, use `theme.layered.css`. Otherwise `theme.css` is fine.
+Theme-token (`--crk-*`) overrides work the same in both.
+
 ## Components
 
 | Component | Description |
 | --- | --- |
 | **Button** | Variants: `primary`, `secondary`, `danger`, `ghost`. Multiple sizes. Loading states with `dots`, `shimmer`, and `border` animations. |
-| **Link** | Styled link with variants and external link support. |
+| **Link** | Styled link with variants and external link support (inline new-tab icon, toggleable). |
 | **Typography** | Renders `h1`-`h6`, `p`, `span`, `label`. Supports `weight`, `color`, `align`, and `truncate`. |
 | **List / ListItem** | Ordered and unordered lists with configurable spacing. |
 | **Table** | Sortable columns, multi-sort with Ctrl+click, pagination, and server-side sort support. |
 | **Dropdown** | Menu dropdown with chevron indicator. Also works as a selectable form input with `options`, `value`, and `onChange`. |
-| **Popover** | Positioned popover anchored to a trigger element. |
+| **Popover** | Positioned popover anchored to a trigger element, with viewport-aware auto-flip. |
 | **Modal** | Portal-based modal with `Header`, `Body`, and `Footer` compound components. Includes focus trap and escape/backdrop close. |
 | **Form / FormField** | Form wrapper with react-hook-form integration. |
 | **Input** | Text input with sizes, error state, and prefix/suffix slots. |
 | **Select** | Native `<select>` with a custom arrow indicator. |
 | **Checkbox** | Checkbox with label and indeterminate state support. |
+| **CheckboxGroup** | Multi-value selection as a checkbox list or toggleable chips. |
 | **Radio / RadioGroup** | Context-based radio group. |
 | **Textarea** | Textarea with resize control. |
 

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/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/inputs/Checkbox/CheckboxGroup.d.ts

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

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

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