cleanplate 0.2.3 → 0.2.5

package/docs/FormControls.md

@@ -8,7 +8,7 @@ FormControls is a set of form primitives exported as a namespace: `FormControls.
 | --- | --- | --- |
 | Input | Single-line text | placeholder, value, onChange(e), type |
 | TextArea | Multi-line text | placeholder, value, onChange(e) |
-| Select | Single or multi select dropdown | options ({ label, value }[]), value, onChange(option \| option[]), isMulti, placeholder |
+| Select | Floating UI combobox: desktop portalled list; **≤768px** bottom sheet; sync or async options, search, groups, multi chips + cap | `mode` / `isMulti`, `options`, `onSearch`, `groups`, `maxSelect`, `triggerMaxItems`, `name`, `placeholder`, `error` |
 | Date | Day/month/year picker (DD-MMM-YYYY) | defaultValue, onChange(dateValue: string) |
 | Checkbox | Checkbox group (array-based, multi-select) | name, label, options, value (CheckboxValue[]), defaultValue, onChange(values, e), orientation, variant |
 | Radio | Radio group (array-based) | name, label, options, value, defaultValue, onChange(value, e), orientation, variant |
@@ -18,23 +18,54 @@ FormControls is a set of form primitives exported as a namespace: `FormControls.
 
 ## Types
 
-### SelectOption
+### Option (and SelectOption)
+
+`Option` is the canonical option shape. **`SelectOption` is a deprecated alias** — use `Option` in new code.
+
 ```typescript
-interface SelectOption {
-  label: string;
+interface Option {
   value: string | number;
+  label: string;
+  /** Contiguous rows with the same non-empty string get a sticky group heading when `groups` is true. */
+  group?: string;
+  /** Material Symbols icon name (row-leading). */
+  icon?: string;
+  /** Image URL for a circular avatar (row-leading). */
+  avatar?: string;
+  /** Muted secondary line (e.g. subtitle). */
+  meta?: string;
+  disabled?: boolean;
 }
 ```
 
 ### SelectProps
+
 ```typescript
+type SelectValue = Option | Option[] | null;
+
 interface SelectProps {
-  onChange?: (option: SelectOption | SelectOption[]) => void;
-  value?: SelectOption | SelectOption[] | null;
+  name?: string;
+  id?: string;
   label?: string;
-  options?: SelectOption[];
+  /** Controlled selection: one option, array (multi), or `null` when cleared (single). Multi clear uses `[]`. */
+  value?: SelectValue;
+  onChange?: (option: Option | Option[] | null) => void;
+  /**
+   * Static list, or `null` with `onSearch` for async/search-backed data.
+   * `[]` or missing = empty sync list.
+   */
+  options?: Option[] | null;
+  /** Required when `options` is `null`. Debounced by `searchDebounce`; empty query runs immediately. */
+  onSearch?: (query: string) => Promise<Option[]>;
+  /** Debounce for `onSearch` only (ms). @default 300 */
+  searchDebounce?: number;
+  /** Panel search field placeholder. @default "Search" */
+  searchPlaceholder?: string;
+  /** When search text matches nothing, optional “add” callback receives trimmed string. */
+  onAddOption?: (value: string) => void;
+  /** @default true */
+  closeOnAddOption?: boolean;
   placeholder?: string;
-  isMulti?: boolean;
   isRequired?: boolean;
   isDisabled?: boolean;
   isFluid?: boolean;
@@ -43,6 +74,19 @@ interface SelectProps {
   triggerClassName?: string;
   triggerActiveClassName?: string;
   contentsClassName?: string;
+  dataTestId?: string;
+  /** Selection mode. @default 'single'. Prefer over legacy `isMulti`. */
+  mode?: "single" | "multi";
+  /** @deprecated Use `mode="multi"`. */
+  isMulti?: boolean;
+  /** Multi: max chips before a "+N" overflow badge. @default 2 */
+  triggerMaxItems?: number;
+  /** Multi: show clear control on trigger when allowed. @default true */
+  clearable?: boolean;
+  /** Group headings for contiguous same-`group` options. @default false */
+  groups?: boolean;
+  /** Multi only: max selectable options; “Select all” respects cap. No effect in single mode. */
+  maxSelect?: number;
 }
 ```
 
@@ -111,6 +155,41 @@ import { FormControls } from "cleanplate";
 />
 ```
 
+### Select — multi, groups, async
+
+**Multi** with `mode="multi"` (or legacy `isMulti`). **`triggerMaxItems`** limits visible chips; extra selections show a **`+N`** badge with an accessible label. **`maxSelect`** caps how many options can be chosen (optional).
+
+```jsx
+const [tags, setTags] = useState([{ label: "A", value: "a" }]);
+<FormControls.Select
+  label="Tags"
+  mode="multi"
+  placeholder="Choose"
+  triggerMaxItems={2}
+  maxSelect={5}
+  value={tags}
+  onChange={(next) => setTags(Array.isArray(next) ? next : [])}
+  options={[
+    { label: "Apple", value: "apple", group: "Fruit" },
+    { label: "Carrot", value: "carrot", group: "Veg" },
+  ]}
+  groups
+/>
+```
+
+**Async / search-backed list:** pass **`options={null}`** and implement **`onSearch(query)`** returning a `Promise<Option[]>`. The panel search field debounces calls (**`searchDebounce`**, default 300ms); an empty query runs immediately. For a fixed in-memory list, pass **`options={items}`** — the same search field **filters** options client-side.
+
+```jsx
+<FormControls.Select
+  label="City"
+  options={null}
+  onSearch={async (q) => fetchCities(q)} // return Option[]
+  searchPlaceholder="Type to search"
+/>
+```
+
+**Mobile:** At **viewport width ≤768px**, the panel opens as a **bottom sheet** (fixed to the lower viewport) with dialog semantics when a **label** is present, instead of a floating anchored list.
+
 ### Input with prefix / suffix
 
 ```jsx
@@ -277,13 +356,55 @@ Pagination uses `FormControls.Select` for rows-per-page. Pills uses `FormControl
 - **Input (`prefix` / `suffix`):** Inline leading/trailing text affix for currency (`$`), country code (`+91`), unit (`kg`, `%`), TLD (`.com`), etc. Soft-capped at 4 characters so the layout stays predictable; longer strings are truncated. When set, the field's outer wrapper takes over the visible border / padding / focus ring so the affixes read as part of the same input. Affixes are linked to the input via `aria-describedby`, so screen readers announce e.g. "Amount, dollars, $500" when the visible affix is `$`. For symbols/abbreviations that don't read well, pass `prefixA11yLabel` / `suffixA11yLabel` (e.g. `prefix="$"`, `prefixA11yLabel="dollars"`). Ignored when `type="search"` (search already uses both edges) — for any other `type`, including `number`, affixes work as expected.
 - **Input (validation / constraints):** `maxLength` is passed straight to the native attribute (works for any `type`). `min` / `max` are passed to the native attribute (HTML5 form-validation hints) and, for `type="number"` only, also clamped on `blur` — the user can finish typing freely and the value snaps to the bound when they leave the field.
 - **Input (`autoComplete` / `onBlur`):** `autoComplete` maps to the native attribute (`"email"`, `"current-password"`, `"off"`, …). `onBlur` runs after any internal numeric clamp so consumers see the final value.
-- **Select:** options are `{ label, value }`; single select passes one option to onChange, multi passes an array. value can be option or array for multi.
+- **Select:** Built on **Floating UI** — desktop uses a **portalled** panel with flip/shift to stay in the viewport; **≤768px** uses a **bottom sheet** (`role="dialog"`, `aria-modal`, `aria-labelledby` to the field label when the label exists). **Option** shape supports `group`, `icon`, `avatar`, `meta`, `disabled`. **`mode`** (`'single' | 'multi'`) replaces **`isMulti`** (still supported, deprecated). Single mode: **`onChange(Option | null)`** — `null` when cleared. Multi mode: **`onChange(Option[])`** — use **`[]`** for clear. **`name` + hidden `<input>`:** native form submit posts the selected **`value`**(s); **multi** joins with **commas** — avoid comma characters inside `value` if you rely on `FormData`, or parse manually. **`options={null}` + `onSearch`:** async loading; show loading/empty/error states in the panel. **`groups`:** sticky headings for shared `Option.group`. **`maxSelect`:** multi only; **`triggerMaxItems`:** chip overflow **`+N`**. **`aria-controls`** on the combobox trigger and panel search point at the listbox **only while open**. **`aria-invalid`** reflects **`error`** on trigger, search field, and listbox. Validation message uses **`role="alert"`** (via shared field error pattern).
 - **Date:** Returns string "dd-mm-yyyy" to onChange; uses internal day/month/year Selects.
 - **Radio:** Group-first API — pass `options: RadioOption[]`. Renders `<fieldset>` + `<legend>` with a single `value` and `onChange(value, e)`. `isRequired` puts `*` on the legend and adds `required`/`aria-required` to the first enabled option (HTML5 only requires one input in the group to carry it). Custom ring/dot follows the native `:checked` state so uncontrolled groups stay visually correct. Pass `variant="card"` for tile-style options (ring in top-right, optional `icon` on the left, primary-brand border + tint when selected).
 - **Checkbox:** Group-first API — pass `options: CheckboxOption[]`. Renders `<fieldset>` + `<legend>` with a `value: CheckboxValue[]` and `onChange(values, e)`. `isRequired` puts `*` on the legend and sets `aria-required` on the group; native HTML5 doesn't enforce "at least one" for checkbox groups, so add custom validation at the form layer. Custom box/tick follows the native `:checked` state. Pass `variant="card"` for tile-style options (box in top-right, optional `icon` on the left, primary-brand border + tint when checked). For a single checkbox, pass a one-element `options` array — `value=[]` is unchecked, `value=[opt.value]` is checked.
 - **File:** Native `<input type="file">` is visually hidden but stays in the a11y tree. Manages a `File[]` selection internally; `onChange(files, e)` fires for picker selections, drops, and removals (the underlying event is `undefined` for non-picker triggers). With `multiple`, subsequent picks/drops append; without, the new selection replaces the old. The card variant supports drag-and-drop and tints primary-brand on hover. Removing a file resets the native input so re-selecting the same file still emits a change. `defaultValue` seeds the visual list only — browsers don't allow programmatic pre-population of file inputs.
 - **isFluid:** Full-width field wrapper.
 
+## Theming
+
+CleanPlate exposes a thin layer of CSS custom properties on `:root` so consumer apps can retheme the form-control surface without forking styles or wrestling specificity. Override these in your own stylesheet **after** the `cleanplate/dist/index.css` import.
+
+| Token | Default | What it controls |
+| --- | --- | --- |
+| `--cp-form-control-radius` | `var(--radius-large)` (12px) | Corner radius for `Input`, `TextArea`, `Stepper`, `Select` trigger + open dropdown corners, `Date` day/month/year segments, `File` (outline trigger, drop zone, in-card CTA, file list rows), and `Radio` / `Checkbox` `variant="card"` option tiles. |
+
+### Recipes
+
+```css
+/* Square-ish form fields across the whole app, while leaving badges, cards,   */
+/* and other --radius-large surfaces alone.                                    */
+:root {
+  --cp-form-control-radius: 4px;
+}
+```
+
+```css
+/* Scope the override to one section — CSS custom properties cascade, so any   */
+/* wrapper works as the boundary.                                              */
+.checkout-form {
+  --cp-form-control-radius: 0;
+}
+```
+
+```jsx
+// Per-instance override — same token, scoped to one element via the style prop.
+<FormControls.Input
+  name="zip"
+  label="ZIP"
+  style={{ "--cp-form-control-radius": "20px" }}
+/>
+```
+
+### When to override what
+
+- **`--cp-form-control-radius`** when you want to retheme just the form-field family (Input, Select trigger, Date, Stepper, TextArea, File triggers and card CTA, file list rows, Radio/Checkbox card tiles). Recommended path.
+- **`--radius-large`** (the underlying design token) when you want every "large radius" surface in CleanPlate — form fields *and* anything else that opts into the same scale — to move together. Coarser, but useful for whole-product rebrands.
+
+The component-level token is the public, supported override. Underlying design tokens (`--radius-small`, `--radius-medium`, `--radius-large`, …) are exposed but treated as the lower tier — overriding them is allowed, but expect broader visual impact.
+
 ## Related Components / Links
 
 - Pills (uses FormControls.Input in edit mode)

package/docs/superpowers/plans/2026-05-10-select-floating-ui.md

@@ -0,0 +1,122 @@
+# Select rebuild — Frozen requirements & implementation plan
+
+> **Frozen as of:** 2026-05-10  
+> **Process:** Implement one numbered phase per session (or PR slice); pause for Storybook review before starting the next. Work stays on the current feature branch.
+
+**Goal:** Replace `Select` with a Floating UI–based control: desktop portalled dropdown with collision-aware positioning; mobile-first bottom sheet for the panel; parity with your written spec plus the decisions below.
+
+**Tech stack:** React 18, existing SCSS (`FormControls.module.scss`), `@floating-ui/react` (must be a **runtime dependency** for the published package—not only devDependency).
+
+**Architecture (short):** Reference element = composite trigger (`button`/`div` pattern matching a11y plan). Floating panel = `FloatingPortal` → `FloatingFocusManager` for desktop; overlay + sheet panel for narrow viewports sharing the same inner list/search shell where possible.
+
+**Testing gate:** Existing Storybook form-controls **Select** story (expand with variants as phases land).
+
+---
+
+## Frozen requirements
+
+### Locked from your original spec
+
+- **Modes:** `mode: 'single' | 'multi'` (multi shows removable chips when selected; overflow `+N` after `triggerMaxItems`).
+- **Data:** Static `Option[]`, or async when `options === null` and `onSearch` is provided.
+- **Options:** Shape as in your doc (`value`, `label`, optional `group`, `icon`, `avatar`, `meta`, `disabled`).
+- **Portal:** Dropdown content renders through a portal (`document.body` or `#root`-safe target if we add optional `portalRoot` prop—**frozen default:** `document.body`).
+- **Clear:** Trigger shows × whenever there is a selection; clears all and closes panel.
+- **Search:** Debounced `searchDebounce` (async); search row at top of panel (clear control on search input when non-empty)—matches your inspirations.
+- **Panel (multi):** Select all row with checked / unchecked / **indeterminate** when some visible options are selected; respects disabled options and `maxSelect`.
+- **`maxSelect`:** Enforced in multi only; capped state is visibly disabled before tap; single mode **no-op** (frozen).
+- **Keyboard (desktop dropdown):** ↓ / ↑ move active option; Enter toggles selection; Escape closes and returns focus to trigger; Tab closes (match spec table).
+- **States:** Idle, open (+ search focus behavior per phase notes), loading, error, empty, disabled.
+- **Forms:** Preserve hidden/native submission story where applicable (`name` prop); extend as needed for multi value encoding.
+
+### Former “open items” — now decided
+
+| Item | Decision |
+|------|----------|
+| `maxSelect` in single mode | **No-op** (ignored). |
+| Bottom sheet animation | **CSS-only:** translateY from 100% → 0, **240ms**, `cubic-bezier(0.22, 1, 0.36, 1)`; backdrop fades **160ms**. (Tunable in SCSS only.) |
+| Flip / collision (desktop) | **Yes:** `flip` + `shift` + **`size`** so max height clamps to viewport; scroll inside list. |
+| Error retry | **Manual “Retry”** only after failure (invokes same `onSearch` with last query). No automatic retry loops. |
+| Uncontrolled mode | **Out of scope for v1.** API is controlled: `value` + `onChange`. (Optional `defaultValue` is a future enhancement, not part of this rebuild.) |
+
+### Visual / UX defaults (aligned to your screenshots)
+
+- Multi trigger: chips with per-chip dismiss; comma-joined label text is replaced by chips + overflow.
+- Single trigger: plain text label of selected option (no chip), or placeholder.
+- Checkbox-style row affordance for multi list; highlight row on hover/focus-visible.
+- Icons: **`icon`** uses **Material Symbols names** like the rest of CleanPlate **`Icon`** (your doc said Tabler—**frozen correction:** match existing **`Icon`** / `cleanplate` pattern in this repo, unless you revert this in review).
+
+---
+
+## Dependencies
+
+- Move **`@floating-ui/react`** from `devDependencies` to **`dependencies`** in `package.json` before shipping the component (can land in Phase 1 PR).
+
+---
+
+## Implementation phases (one todo each — review after)
+
+### Phase 1 — Floating UI desktop shell
+
+- Portal + `useFloating` with `flip`, `shift`, `offset`, `size`, `whileElementsMounted` / `autoUpdate`.
+- Replace in-flow dropdown positioning; dismiss on outside press and Escape (`useDismiss`).
+- **Scope limit:** Static options, existing simple single + multi behaviour, no chips yet beyond current approximation if multi still uses text summary briefly.
+- Storybook: Select still runnable; note known gaps.
+
+### Phase 2 — API & types freeze
+
+- Export `Option` type; deprecate or alias `SelectOption` → `Option` for compat.
+- Add `mode` prop; **`isMulti` maps to `mode`** for one release or deprecate `isMulti` with console warning once (pick minimal churn—frozen approach: **`mode` canonical**, keep `isMulti` as undocumented alias forwarding to `mode` OR remove if you prefer breaking change—default **canonical `mode`** + **`isMulti` deprecated** shim).
+- Storybook controls updated.
+
+### Phase 3 — Multi trigger chips + overflow
+
+- Render first `triggerMaxItems` selections as removable chips; `+N` for remainder.
+- Clear (×) and chevron behaviours per spec.
+
+### Phase 4 — Search (sync + async wiring)
+
+- Search field in panel; **sync:** filters `options` locally, no debounce on static path (debounce still applies only to `onSearch` path per your table).
+- **Async:** when `options === null`, debounced `onSearch(q)`.
+
+### Phase 5 — Async states
+
+- Loading / error / empty UI in list slot; Retry on error only.
+
+### Phase 6 — Groups + rich options
+
+- `groups` sections; icons/avatars/meta; disabled options skipped in keyboard nav and not selectable.
+
+### Phase 7 — Panel bulk actions & `maxSelect`
+
+- Select all / clear all in panel (multi); indeterminate logic for “visible” selectable set respect `disabled` rows.
+- Cap styling and blocked clicks.
+
+### Phase 8 — Keyboard completion
+
+- Arrow navigation through options; Enter to toggle/select; Tab/Escape per frozen table; roving tabindex or Floating UI list patterns.
+
+### Phase 9 — Mobile bottom sheet
+
+- Breakpoint: **`max-width: 768px`** (match common `md` boundary; overrides if you expose `breakpoints` prop later—**frozen: internal constant** first).
+- Sheet uses focus trap compatible with Floating UI dismissal; reuse inner list markup.
+
+### Phase 10 — A11y + Storybook showcases
+
+- `aria-expanded`, `aria-controls`, listbox/combobox roles consistent across modes.
+- Hidden input / form submission validated for multi.
+- Stories: static single/multi, async, groups, chips overflow, maxSelect, error, empty, sheet (viewport toggle).
+
+---
+
+## Review checkpoint protocol
+
+After each phase: run **Storybook** (`npm run storybook`), exercise **Select** story (and phase-specific knobs), confirm no regressions in **All controls showcase**, then approve next phase.
+
+---
+
+## Out of scope (explicit)
+
+- List virtualization (`react-window`, etc.).
+- Uncontrolled/defaultValue API.
+- Auto-retry on fetch errors.

package/llms.txt

@@ -177,8 +177,9 @@ 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 (single/multi, options { label, value }, supports `name`/`id`, ARIA wiring, and hidden input for native form submission), Date (dd-mm-yyyy), 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, SelectProps, SelectOption, TextAreaProps, CheckboxProps, CheckboxOption, CheckboxValue, FileProps, FileVariant, RadioProps, RadioOption, RadioValue, ToggleProps, DateProps, FormControlsStepperProps
+- 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 (dd-mm-yyyy), 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 day/month/year segments, 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cleanplate",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "CleanPlate - A Headless React UI Framework",
   "files": [
     "dist",
@@ -35,10 +35,12 @@
     "url": "https://github.com/sivadass/cleanplate/issues"
   },
   "homepage": "https://cleanplate.sivadass.in",
+  "dependencies": {
+    "@floating-ui/react": "^0.27.16"
+  },
   "devDependencies": {
     "@babel/preset-react": "^7.23.3",
     "@babel/preset-typescript": "^7.28.5",
-    "@floating-ui/react": "^0.27.16",
     "@fluentui/storybook-llms-extractor": "^0.0.2",
     "@rollup/plugin-babel": "^6.0.4",
     "@rollup/plugin-commonjs": "^25.0.7",