cleanplate 0.2.9 → 0.3.1

package/docs/FormControls.md

@@ -14,7 +14,7 @@ FormControls is a set of form primitives exported as a namespace: `FormControls.
 | Radio | Radio group (array-based) | name, label, options, value, defaultValue, onChange(value, e), orientation, variant |
 | File | File picker with `button` / `card` variants, drag-and-drop, and a removable file list | name, label, variant, multiple, accept, value (File[]), onChange(files, e), buttonLabel, dropZoneText |
 | Toggle | On/off switch | checked, defaultChecked, onChange(checked: boolean) |
-| Stepper | Text input for step flows | placeholder, value, onChange(e) |
+| Stepper | Numeric value with integrated − / + (integer text field + `min` / `max` / `step`) | placeholder, value, onChange(e), min, max, step, layout |
 
 ## Types
 
@@ -137,7 +137,7 @@ interface InputProps {
 - **CheckboxProps**: `options` (non-empty `CheckboxOption[]`), `name`, `label` (group `<legend>`), optional `id`, `value` (`CheckboxValue[]`), `defaultValue` (`CheckboxValue[]`), `onChange(values, e)`, `orientation` (`"vertical" | "horizontal"`), `variant` (`"default" | "card"`), `isDisabled`, `isRequired`, `isFluid`, `className`, `error`, `dataTestId`.
 - **CheckboxOption**: `{ label, value, isDisabled?, description?, icon?, dataTestId?, id? }`. `description` is rendered under the option label as muted secondary text and linked via `aria-describedby`. `icon` accepts any `ReactNode` (e.g. `<Icon />`, `<img />`, custom SVG) and renders to the left of the label/description. `CheckboxValue = string | number`.
 - **DateProps**: `value` / `defaultValue` (`Date | null`), `onChange(date: Date | null)`, `placeholder`, **`dateFormat`** (display string via `date-fns` + `locale`, default `MMM dd, yyyy`), **`name`** (renders a hidden `<input>` that submits **`yyyy-MM-dd`** for the committed calendar date), **`minDate`** / **`maxDate`** (inclusive navigation + selection bounds), **`disabledDates`** / **`disabledDaysOfWeek`** (greyed cells), **`locale`** (`date-fns` `Locale` — grid, subview copy, and field text), **`weekStartsOn`** (`0`–`6`, default `0` = Sunday), **`clearable`** (default `true`; shows clear control when a value exists), **`readOnly`** (no picker; value fixed), **`popoverPlacement`** (Floating UI placement for desktop; default `bottom-start`), **`onOpen`** / **`onClose`**, plus shared `label`, `isDisabled`, `isRequired`, `isFluid`, `className`, `error`, `dataTestId`.
-- **FormControlsStepperProps**: label, placeholder, value/defaultValue, onChange(e), type, isDisabled, isRequired, isFluid, className, error, dataTestId.
+- **FormControlsStepperProps**: label, placeholder, value/defaultValue, onChange(e), min, max, step, layout (`"default" | "split-controls" | "trailing-stacked-chevrons"`), isDisabled, isRequired, isFluid, className, error, dataTestId.
 
 ## Usage Examples
 

package/docs/MediaObject.md

@@ -1,31 +1,31 @@
 # MediaObject Component
 
-Purpose: A flexible layout pattern that combines media (icon, image, or avatar) with content (title and description). Perfect for displaying user profiles, product cards, notifications, and any content that needs a media element alongside text.
+Purpose: Combines fixed media (`Avatar`: icon, image, or initials) with a dense text stack (primary title, optional subtitle, optional clipped preview). Supports an optional **trailing rail** for metadata aligned to the title row (e.g. date) and an action anchored to the last text row (e.g. star), matching mobile inbox/list cards. Built-in text colors use semantic tokens (`--text-default`, `--text-subtle`, `--text-muted`).
 
 ## Props / Inputs
 
 | Prop | Type | Required | Default | Description |
 | --- | --- | --- | --- | --- |
-| title | string | yes | — | The main title text displayed in the content area. |
-| mediaIcon | string | no | "" | Icon name from Material Symbols to display as the media element. |
-| mediaImage | string | no | "" | Image URL to display as the media element. |
-| mediaAvatar | string | no | "" | Name used to generate an avatar with initials and background color. |
-| description | string | no | — | Secondary text displayed below the title. |
-| margin | string \| string[] | no | "0" | Spacing utility token(s) for outer margin, such as `m-0` or `["m-1", "m-b-2"]`. |
-| padding | string \| string[] | no | "0" | Spacing utility token(s) for inner padding, such as `p-0` or `["p-1", "p-b-2"]`. |
-| className | string | no | "media-object" | Additional class names for the root element. |
-| onClick | function | no | — | Called with the click event when the media object is clicked. |
-| ...rest | React.HTMLAttributes<HTMLDivElement> | no | — | All other standard HTML div attributes are supported and passed through to the rendered element. |
+| title | string | yes | — | Primary line (e.g. name, sender). Rendered emphasized. |
+| mediaIcon | `MaterialIconName` \| string | no | "" | Material Symbol name passed to `Avatar`. |
+| mediaImage | string | no | "" | Image URL for `Avatar`. |
+| mediaAvatar | string | no | "" | Display name used for initials and avatar color generation (when image/icon not shown). |
+| subtitle | `React.ReactNode` | no | — | Optional middle line (e.g. subject). Omit for two-line layouts. |
+| description | `React.ReactNode` | no | — | Optional preview/snippet line(s); muted, multi-line ellipsis via `--cp-media-object-desc-lines`. |
+| descriptionLineClamp | number | no | 2 | Max lines for `description` before truncation. |
+| meta | `React.ReactNode` | no | — | Trailing rail, **first text row**. Strings/numbers get subdued meta typography; pass JSX for custom styling. |
+| action | `React.ReactNode` | no | — | Trailing rail, **last content row** (e.g. `Icon`/button); right-aligned with the snippet row when present. |
+| margin | string \| `SpacingOption[]` | no | "0" | Outer margin spacing tokens (`m-*` utilities). |
+| padding | string \| `SpacingOption[]` | no | "0" | Inner padding spacing tokens (`p-*` utilities). |
+| className | string | no | "media-object" | Extra classes on the root `<div>`. |
+| onClick | function | no | — | Click handler on the root; forwarded to `Avatar` when provided. |
+| ...rest | `React.HTMLAttributes<HTMLDivElement>` | no | — | Standard div props (`id`, `data-*`, `aria-*`, etc.). |
 
 ## Types
 
-### MediaObjectMargin
+### MediaObjectMargin / MediaObjectPadding
 ```typescript
 type MediaObjectMargin = string | SpacingOption[];
-```
-
-### MediaObjectPadding
-```typescript
 type MediaObjectPadding = string | SpacingOption[];
 ```
 
@@ -37,11 +37,15 @@ type SpacingOption = typeof SPACING_OPTIONS[number];
 ### MediaObjectProps
 ```typescript
 interface MediaObjectProps extends React.HTMLAttributes<HTMLDivElement> {
-  mediaIcon?: string;
+  mediaIcon?: MaterialIconName | string;
   mediaImage?: string;
   mediaAvatar?: string;
   title: string;
-  description?: string;
+  subtitle?: React.ReactNode;
+  description?: React.ReactNode;
+  descriptionLineClamp?: number;
+  meta?: React.ReactNode;
+  action?: React.ReactNode;
   margin?: MediaObjectMargin;
   padding?: MediaObjectPadding;
   className?: string;
@@ -51,253 +55,145 @@ interface MediaObjectProps extends React.HTMLAttributes<HTMLDivElement> {
 
 ## Usage Examples
 
-### With icon
-
-```jsx
-import { MediaObject } from "cleanplate";
-
-export const Example = () => (
-  <MediaObject
-    mediaIcon="person"
-    title="User Profile"
-    description="Manage your account settings and preferences"
-  />
-);
-```
-
-### With image
+### Title + description (classic two-line row)
 
 ```jsx
 import { MediaObject } from "cleanplate";
 
-export const Example = () => (
-  <MediaObject
-    mediaImage="https://example.com/avatar.jpg"
-    title="John Doe"
-    description="Senior Developer at Tech Corp"
-  />
-);
+<MediaObject
+  mediaIcon="person"
+  title="User Profile"
+  description="Manage your account settings and preferences"
+/>
 ```
 
-### With avatar (initials)
-
-```jsx
-import { MediaObject } from "cleanplate";
-
-export const Example = () => (
-  <MediaObject
-    mediaAvatar="John Doe"
-    title="John Doe"
-    description="Senior Developer with 5+ years of experience"
-  />
-);
-```
+### Inbox-style row (three lines + date + star)
 
-### Title only
+Prefer `subtitle` + `description` plus `meta` / `action` for mail-style listings. Strings in `meta` use muted sizing; arbitrary JSX is allowed for custom summaries.
 
 ```jsx
-import { MediaObject } from "cleanplate";
-
-export const Example = () => (
-  <MediaObject
-    mediaIcon="settings"
-    title="Settings"
-  />
-);
+import { Button, Icon, MediaObject } from "cleanplate";
+
+<MediaObject
+  mediaAvatar="Ada Lovelace"
+  title="Ada Lovelace"
+  subtitle="» Weekly digest — infra"
+  description="Deployments, deprecation notices, and the FAQ refresh you requested."
+  meta="Thu"
+  descriptionLineClamp={2}
+  action={
+    <Button type="button" variant="icon" aria-label="Star thread" margin="m-0">
+      <Icon name="star_border" />
+    </Button>
+  }
+/>
 ```
 
-### With margin and padding
+### Subtitle without snippet
 
 ```jsx
-import { MediaObject } from "cleanplate";
-
-export const Example = () => (
-  <>
-    <MediaObject
-      mediaIcon="star"
-      title="Featured Item"
-      description="This item has custom spacing"
-      margin="m-3"
-      padding="p-2"
-    />
-    <MediaObject
-      mediaIcon="heart"
-      title="Another Item"
-      description="With multiple margin tokens"
-      margin={["m-1", "m-b-3"]}
-      padding={["p-1", "p-x-2"]}
-    />
-  </>
-);
+<MediaObject
+  mediaIcon="payments"
+  title="Invoice #4021"
+  subtitle="Reminder: payable on receipt."
+  meta="Unpaid"
+/>
 ```
 
-### Clickable media object
+### Action only on the trailing rail
 
 ```jsx
-import { MediaObject } from "cleanplate";
-
-export const Example = () => (
-  <MediaObject
-    mediaImage="https://example.com/product.jpg"
-    title="Wireless Headphones"
-    description="High-quality wireless headphones"
-    onClick={() => console.log("Media object clicked")}
-  />
-);
+<MediaObject
+  mediaIcon="shopping_bag"
+  title="Reorder suggestions"
+  description="Based on your last three carts."
+  action={<Icon name="more_vert" />}
+/>
 ```
 
-### User profile card
+### Meta as custom JSX
 
 ```jsx
-import { MediaObject } from "cleanplate";
-import { Button } from "cleanplate";
-
-export const Example = () => (
-  <div style={{ 
-    border: "1px solid #e0e0e0", 
-    borderRadius: "8px",
-    padding: "16px"
-  }}>
-    <MediaObject
-      mediaImage="https://example.com/avatar.jpg"
-      title="John Doe"
-      description="Senior Developer • john.doe@example.com"
-    />
-    <Button variant="outline" size="small" margin="m-t-3">
-      Edit Profile
-    </Button>
-  </div>
-);
+import { MediaObject, Typography } from "cleanplate";
+
+<MediaObject
+  mediaAvatar="Jane"
+  title="Jane Doe"
+  description="Ping when you merge."
+  meta={
+    <Typography variant="small" margin="m-0" isBold align="right">
+      3 new
+    </Typography>
+  }
+/>
 ```
 
-### Product card
+### With image or avatar initials
 
 ```jsx
-import { MediaObject } from "cleanplate";
-import { Typography } from "cleanplate";
-import { Button } from "cleanplate";
-
-export const Example = () => (
-  <div style={{ 
-    border: "1px solid #e0e0e0", 
-    borderRadius: "8px",
-    padding: "16px"
-  }}>
-    <MediaObject
-      mediaImage="https://example.com/product.jpg"
-      title="Wireless Headphones"
-      description="High-quality wireless headphones with noise cancellation"
-    />
-    <div style={{ marginTop: "12px", display: "flex", justifyContent: "space-between", alignItems: "center" }}>
-      <Typography variant="h5">$199.99</Typography>
-      <Button size="small" variant="outline">Add to Cart</Button>
-    </div>
-  </div>
-);
+<MediaObject
+  mediaImage="https://example.com/avatar.jpg"
+  title="John Doe"
+  description="Senior Developer at Tech Corp"
+/>
+
+<MediaObject
+  mediaAvatar="John Doe"
+  title="John Doe"
+  description="Shows initials until an image overrides."
+/>
 ```
 
-### Notification list
+### Title only
 
 ```jsx
-import { MediaObject } from "cleanplate";
-
-export const Example = () => (
-  <div>
-    <MediaObject
-      mediaIcon="notifications"
-      title="New Message"
-      description="You have received a new message from Jane Smith"
-      margin="m-b-2"
-    />
-    <MediaObject
-      mediaIcon="schedule"
-      title="Meeting Reminder"
-      description="Team standup in 30 minutes"
-      margin="m-b-2"
-    />
-    <MediaObject
-      mediaIcon="done"
-      title="Task Completed"
-      description="Your project 'Website Redesign' has been updated"
-    />
-  </div>
-);
+<MediaObject mediaIcon="settings" title="Settings" />
 ```
 
-### Settings items
+### Margin / padding tokens
 
 ```jsx
-import { MediaObject } from "cleanplate";
-
-export const Example = () => (
-  <div>
-    <MediaObject
-      mediaIcon="settings"
-      title="Account Settings"
-      description="Manage your account preferences and security settings"
-      margin="m-b-2"
-    />
-    <MediaObject
-      mediaIcon="lock"
-      title="Privacy & Security"
-      description="Control your privacy settings and security options"
-      margin="m-b-2"
-    />
-    <MediaObject
-      mediaIcon="notifications"
-      title="Notifications"
-      description="Configure how and when you receive notifications"
-    />
-  </div>
-);
+<MediaObject
+  mediaIcon="star"
+  title="Featured"
+  description="With spacing utilities"
+  margin="m-b-3"
+  padding="p-2"
+/>
+<MediaObject
+  margin={["m-1", "m-b-3"]}
+  padding={["p-1", "p-x-2"]}
+  title="Row"
+/>
 ```
 
-### List of users
+### Clickable row
 
 ```jsx
-import { MediaObject } from "cleanplate";
-
-export const Example = () => {
-  const users = [
-    { name: "John Doe", role: "Developer", avatar: "https://example.com/avatar1.jpg" },
-    { name: "Jane Smith", role: "Designer", avatar: "https://example.com/avatar2.jpg" },
-    { name: "Mike Johnson", role: "Manager", avatar: "https://example.com/avatar3.jpg" }
-  ];
-
-  return (
-    <div>
-      {users.map((user, index) => (
-        <MediaObject
-          key={index}
-          mediaImage={user.avatar}
-          title={user.name}
-          description={user.role}
-          margin={index < users.length - 1 ? "m-b-2" : "m-0"}
-        />
-      ))}
-    </div>
-  );
-};
+<MediaObject
+  mediaImage="/product.jpg"
+  title="Wireless Headphones"
+  description="Noise cancelling"
+  onClick={() => {}}
+/>
 ```
 
 ## Behavior Notes
 
-- The `title` prop is required and will always be displayed in bold text.
-- The `description` prop is optional. If not provided, only the title will be displayed.
-- You can provide one of `mediaIcon`, `mediaImage`, or `mediaAvatar` to display the media element. If multiple are provided, the component will prioritize in this order: `mediaAvatar` > `mediaImage` > `mediaIcon`.
-- The component uses the `Avatar` component internally to render the media element, which supports icons, images, and generated avatars with initials.
-- The component uses the `Typography` component internally for the title and description text.
-- The title is rendered with `isBold={true}` by default.
-- The description is rendered with `variant="small"`.
-- The component renders as a `<div>` element with a flex layout structure.
-- Margin and padding spacing accept either a single string token (e.g., `"m-2"`) or an array of tokens (e.g., `["m-1", "m-b-3"]`).
-- The `onClick` handler makes the entire media object clickable, useful for interactive lists or cards.
-- All standard HTML div attributes can be passed through, allowing for custom `id`, `data-*`, `aria-*`, and other attributes.
-- The component is designed to be responsive and adapts to different screen sizes.
+- **Layout**: Root uses flex (media column + responsive grid body). Without `meta` or `action`, the body is one column of stacked text with **zero row-gap** between lines for inbox-like density.
+- **Trailing rail**: If `meta` and/or `action` is passed, the body adds a second grid column: `meta` always occupies **column 2, row 1** aligned with `title`; `action` occupies **column 2, last text row**, aligned toward the snippet row. When **only one** logical text row remains and **both** `meta` and `action` exist, both stack in one compact trailing cell (`gap` 2px).
+- **`descriptionLineClamp`** sets the CSS custom property `--cp-media-object-desc-lines` on the snippet wrapper so consumers can clamp 1–N lines preview text.
+- **Media slot**: Implemented with `Avatar` (`name={mediaAvatar}`, `image`, `icon`). Combination rules when multiple props are set match `Avatar` (see `docs/Avatar.md`); typical usage passes one dominant source (photo URL vs icon vs name for initials).
+- **`meta` primitives**: Strings and numbers render with component meta typography (muted `--text-muted`); pass React nodes when you control color/weight entirely.
+- **`title`** is always a string rendered as emphasized primary text (`--text-default`).
+- **`subtitle`** and **`description`** accept `React.ReactNode`; empty string / falsy hides the slot.
+- **Styling**: Text stacks use semantic tokens (`--text-default`, `--text-subtle`, `--text-muted`); rules live in CSS modules—not the `Typography` component—so inbox-style line-heights stay consistent.
+- **Spacing**: Margin and padding use the same spacing token shape as elsewhere (`string` or `SpacingOption[]` arrays).
+- **Interaction**: Whole row is clickable when `onClick` is supplied; avatar receives the same handler for consistency.
 
 ## Related Components / Links
 
-- Avatar (used internally for the media element)
-- Typography (used internally for title and description)
-- Button (often used alongside MediaObject in cards)
-- Container (commonly used to wrap MediaObject components)
+- **Avatar** — media slot (`mediaAvatar`, `mediaImage`, `mediaIcon`).
+- **Icon**, **Button** — common `action` content.
+- **Table** — `mobileColumns` maps rows into `MediaObject` on narrow viewports (`title`, `description`, optional `mediaAvatar`; still compatible without `subtitle` / rail).
+- **Container** — often wraps stacked `MediaObject` rows.

package/docs/Stepper.md

@@ -2,6 +2,8 @@
 
 Purpose: Displays a sequence of steps (e.g. for a wizard or checkout). Each step has a label, optional active/completed state, and can be clickable. Use it for multi-step flows and progress indication. Supports horizontal and vertical layout.
 
+**Note:** For a **numeric quantity** field with integrated − / +, use **`FormControls.Stepper`** (see `docs/FormControls.md`). This file documents the **wizard / progress** Stepper only.
+
 ## Props / Inputs
 
 | Prop | Type | Required | Default | Description |

package/llms.txt

@@ -65,10 +65,11 @@ All component documentation is located in the `docs/` folder. The following docu
 
 ### MediaObject Component
 - File: `docs/MediaObject.md`
-- Purpose: A flexible layout pattern that combines media (icon, image, or avatar) with content (title and description). Perfect for displaying user profiles, product cards, notifications, and any content that needs a media element alongside text.
-- Key Features: Media types (icon, image, avatar), title and description, margin and padding spacing, clickable support
-- Types: MediaObjectProps, MediaObjectMargin, MediaObjectPadding, SpacingOption
-- Related Components: Uses Avatar and Typography internally
+- Purpose: Avatar + dense text stack (required `title`, optional `subtitle`, optional line-clamped `description`) plus optional trailing **rail**: `meta` (row 1, e.g. date) and/or `action` (last row, e.g. star). Fits profiles, notifications, inbox-style rows, Table mobile cards.
+- Key Features: `mediaIcon`/`mediaImage`/`mediaAvatar` → `Avatar`; `subtitle`; `meta`/`action`; `descriptionLineClamp` → `--cp-media-object-desc-lines`; semantic text tokens (`--text-default`/`--text-subtle`/`--text-muted`); sparse grid row-gap for list density
+- Props (see full table in doc): title, subtitle?, description?, descriptionLineClamp? (default 2), meta?, action?, margin, padding, onClick?, ...div HTMLAttributes
+- Types: MediaObjectProps, MediaObjectMargin, MediaObjectPadding, SpacingOption; `mediaIcon` accepts MaterialIconName
+- Related Components: Avatar (media); Icon/Button often in `action`; Table (mobile view); Typography not wired internally—text styles live in MediaObject.module.scss
 
 ### Avatar Component
 - File: `docs/Avatar.md`
@@ -110,6 +111,7 @@ All component documentation is located in the `docs/` folder. The following docu
 - Key Features: Variants (horizontal, vertical), config-driven steps (StepperStepConfig), optional onClick(step), margin spacing (suffix API), completed state shows done icon
 - Types: StepperProps, StepperStepConfig, StepperVariant, StepperMargin, SpacingOption
 - Related Components: Container, Typography, Icon (used internally)
+- **Not** the numeric +/- field: for quantity-style inputs use **`FormControls.Stepper`** (see **FormControls** / `docs/FormControls.md`).
 
 ### BreadCrumb Component
 - File: `docs/BreadCrumb.md`
@@ -176,10 +178,10 @@ All component documentation is located in the `docs/` folder. The following docu
 
 ### FormControls
 - File: `docs/FormControls.md`
-- Purpose: Set of form primitives: Input, TextArea, Select, Date, Checkbox, Radio, File, Toggle, Stepper. Access via FormControls.Input, FormControls.Select, etc.
-- Key Features: Input (supports text/search/number + prefix/suffix; number maps to numeric text input and clamps via `min`/`max` on blur; search adds icon + clear button), TextArea, **Select** (Floating UI: portalled combobox on desktop with flip/shift positioning; **viewport ≤768px** uses a **bottom sheet** shell with `role="dialog"` / `aria-modal` when a label exists; **sync** `options` with in-panel **search filter**, or **async** via `options={null}` + `onSearch` (debounced); **groups** (`Option.group` sticky headers); **multi** chips with `triggerMaxItems` **+N** overflow, **Select all / Clear all**, **`maxSelect`** cap; optional **`onAddOption`**; combobox + listbox ARIA, **`aria-invalid`** on error, **`aria-controls`** on trigger/search only while open; `name` + hidden input for forms — multi posts comma-joined **`value`s**), **Date** (calendar **`Date | null`** + **Cancel/OK** staging; `date-fns` **Locale** + **`dateFormat`**; **Floating UI** desktop popover **~max 400px** wide (viewport-capped) with **`popoverPlacement`**; **≤768px** **bottom sheet** + backdrop/body lock like Select; **month/year subviews** with back + **“Select a month of {yyyy}”** / **“Select a year for {MMMM}”** titles; trigger **`calendar_month`** icon + optional clear; **`minDate`/`maxDate`/`disabledDates`/`disabledDaysOfWeek`**, **`weekStartsOn`**, **`readOnly`**, **`clearable`**, **`name`** → hidden **`yyyy-MM-dd`**, **`onOpen`/`onClose`**), Checkbox (group-first: options[], CheckboxValue[] for multi-select, onChange(values, e); each option supports `description` and `icon`; `variant="card"` for tile-style options), Radio (group-first: options[], single value, onChange(value, e); each option supports `description` and `icon`; `variant="card"` for tile-style options), File (`variant="button" | "card"`; card variant has dashed drop zone with drag-and-drop; `value: File[]` + `onChange(files, e)`; renders a removable file list with type-aware thumbnail, name, and size), Toggle (switch semantics via checkbox + role="switch"), Stepper; common props label, isRequired, isFluid, error
-- Types: InputProps, **Option** (preferred), **SelectOption** (deprecated alias of Option), **SelectValue**, SelectProps, TextAreaProps, CheckboxProps, CheckboxOption, CheckboxValue, FileProps, FileVariant, RadioProps, RadioOption, RadioValue, ToggleProps, DateProps, FormControlsStepperProps
-- Theming: Public CSS custom property `--cp-form-control-radius` (default `var(--radius-large)` = 12px) controls corner radius for Input, TextArea, Stepper, Select trigger + open dropdown corners, Date trigger + calendar panel shell, File (outline trigger, drop zone, in-card CTA span, file list rows), and Radio/Checkbox `variant="card"` tiles. Override on `:root` (or any wrapper / inline `style`) after importing `cleanplate/dist/index.css` to retheme just form fields. Prefer this over overriding the underlying `--radius-large` design token, which affects every "large radius" surface in the framework.
+- Purpose: Set of form primitives: Input, TextArea, Select, Date, Checkbox, Radio, File, Toggle, **FormControls.Stepper** (numeric +/− only; wizard step UI is the separate **`Stepper`** export — `docs/Stepper.md`). Access via `FormControls.Input`, `FormControls.Select`, etc.
+- Key Features: Input (supports text/search/number + prefix/suffix; number maps to numeric text input and clamps via `min`/`max` on blur; search adds icon + clear button), TextArea, **Select** (Floating UI: portalled combobox on desktop with flip/shift positioning; **viewport ≤768px** uses a **bottom sheet** shell with `role="dialog"` / `aria-modal` when a label exists; **sync** `options` with in-panel **search filter**, or **async** via `options={null}` + `onSearch` (debounced); **groups** (`Option.group` sticky headers); **multi** chips with `triggerMaxItems` **+N** overflow, **Select all / Clear all**, **`maxSelect`** cap; optional **`onAddOption`**; combobox + listbox ARIA, **`aria-invalid`** on error, **`aria-controls`** on trigger/search only while open; `name` + hidden input for forms — multi posts comma-joined **`value`s**), **Date** (calendar **`Date | null`** + **Cancel/OK** staging; `date-fns` **Locale** + **`dateFormat`**; **Floating UI** desktop popover **~max 400px** wide (viewport-capped) with **`popoverPlacement`**; **≤768px** **bottom sheet** + backdrop/body lock like Select; **month/year subviews** with back + **“Select a month of {yyyy}”** / **“Select a year for {MMMM}”** titles; trigger **`calendar_month`** icon + optional clear; **`minDate`/`maxDate`/`disabledDates`/`disabledDaysOfWeek`**, **`weekStartsOn`**, **`readOnly`**, **`clearable`**, **`name`** → hidden **`yyyy-MM-dd`**, **`onOpen`/`onClose`**), Checkbox (group-first: options[], CheckboxValue[] for multi-select, onChange(values, e); each option supports `description` and `icon`; `variant="card"` for tile-style options), Radio (group-first: options[], single value, onChange(value, e); each option supports `description` and `icon`; `variant="card"` for tile-style options), File (`variant="button" | "card"`; card variant has dashed drop zone with drag-and-drop; `value: File[]` + `onChange(files, e)`; renders a removable file list with type-aware thumbnail, name, and size), Toggle (switch semantics via checkbox + role="switch"), **FormControls.Stepper** (numeric integer only: inner field is `type="text"` + `inputMode="numeric"` with − / +; `min`, `max`, `step`; **`layout`**: `"default"` | `"split-controls"` | `"trailing-stacked-chevrons"`; no **`type`** prop — use **Input** for other field kinds; − / + clicks do not move focus into the field, avoiding unwanted mobile keyboard); common props label, isRequired, isFluid, error
+- Types: InputProps, **Option** (preferred), **SelectOption** (deprecated alias of Option), **SelectValue**, SelectProps, TextAreaProps, CheckboxProps, CheckboxOption, CheckboxValue, FileProps, FileVariant, RadioProps, RadioOption, RadioValue, ToggleProps, DateProps, FormControlsStepperProps, **FormControlsStepperLayout**
+- Theming: Public CSS custom property `--cp-form-control-radius` (default `var(--radius-large)` = 12px) controls corner radius for Input, TextArea, **FormControls.Stepper** shell, Select trigger + open dropdown corners, Date trigger + calendar panel shell, File (outline trigger, drop zone, in-card CTA span, file list rows), and Radio/Checkbox `variant="card"` tiles. Override on `:root` (or any wrapper / inline `style`) after importing `cleanplate/dist/index.css` to retheme just form fields. Prefer this over overriding the underlying `--radius-large` design token, which affects every "large radius" surface in the framework.
 - Related Components: Pills (Input), Pagination (Select), Container, Button
 
 ### Toast Component
@@ -254,7 +256,7 @@ All documentation files follow a consistent format:
 | Dropdown | `docs/Dropdown.md` | Menus and floating panels |
 | Alert | `docs/Alert.md` | Inline feedback and notices |
 | Spinner | `docs/Spinner.md` | Loading and activity indicator |
-| Stepper | `docs/Stepper.md` | Multi-step flows and wizards |
+| Stepper | `docs/Stepper.md` | Wizard / checkout **step progress** (not numeric +/−; that is **FormControls.Stepper** in FormControls) |
 | BreadCrumb | `docs/BreadCrumb.md` | Navigation trail and page hierarchy |
 | Accordion | `docs/Accordion.md` | Collapsible panels and FAQ sections |
 | ConfirmDialog | `docs/ConfirmDialog.md` | Confirmation modals and destructive actions |
@@ -264,7 +266,7 @@ All documentation files follow a consistent format:
 | Badge | `docs/Badge.md` | Status labels, tags, and counts with colored variants |
 | Pills | `docs/Pills.md` | Tags/chips with read-only, edit, and remove modes |
 | Animated | `docs/Animated.md` | Scroll-triggered entrance/exit animations |
-| FormControls | `docs/FormControls.md` | Form primitives (Input, Select, TextArea, Date, Checkbox, etc.) |
+| FormControls | `docs/FormControls.md` | Form primitives (Input, Select, TextArea, Date, Checkbox, **numeric Stepper**, etc.) |
 | Toast | `docs/Toast.md` | Transient messages via ref.addMessage |
 | MenuList | `docs/MenuList.md` | Nav menus and link lists with icons |
 | Header | `docs/Header.md` | Responsive navigation header with logo and menu |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cleanplate",
-  "version": "0.2.9",
+  "version": "0.3.1",
   "description": "CleanPlate - A Headless React UI Framework",
   "files": [
     "dist",