# CleanPlate Component Documentation Index

This file is published in the **`cleanplate` npm package** (next to `package.json`). Consumers and coding agents should use `node_modules/cleanplate/llms.txt` or a CDN URL pinned to their installed semver (see the README “LLM / AI-friendly docs & agents” section).

This file contains an index of all available component documentation for the CleanPlate UI framework.

## Project Overview

CleanPlate is a Headless React UI Framework providing reusable, accessible, and customizable components for building modern web applications.

## Guidelines for AI / LLM code generation

When generating code that uses CleanPlate components, **use component props instead of inline `style`** for layout, spacing, and alignment. The framework exposes these via props; inline styles bypass design tokens and consistency.

### Spacing (margin, padding, gap) — common rule for all components

**This rule applies to every CleanPlate component** that accepts `margin`, `padding`, or `gap` (Typography, Button, Container, Alert, Avatar, Accordion, Header, Footer, and others). All of them use the same **suffix-only** API; the component adds the prefix internally.

- **Correct:** `margin="0"`, `margin="b-2"`, `margin={["b-2", "t-1"]}`, `padding="4"`, `gap="2"`. The component turns these into m-0, m-b-2, p-4, g-2, etc.
- **Wrong:** `margin="m-0"`, `padding="p-4"`, `gap="g-2"` — do not include the m-, p-, or g- prefix.
- Common suffixes: "0", "1", "2", "3", "4", "b-1", "b-2", "t-2", "y-2", "x-2".
- Use the `margin` / `padding` / `gap` prop instead of `style={{ marginBottom, paddingTop, gap }}` for spacing.

### Typography
- **Text alignment:** Use the `align` prop. Example: `<Typography align="center">` not `style={{ textAlign: "center" }}`. Values: `"left"`, `"center"`, `"right"`.
- **Spacing:** Use `margin` with the spacing suffix (see above; same rule as all components).
- **Bold:** Use `isBold` prop, not `style={{ fontWeight: "bold" }}`.

### Other components
- **Container:** Use `padding`, `margin`, `gap`, `align`, `justify`, `display`, `width` props (spacing uses suffix rule above).
- **Button, Alert, Badge, etc.:** Each has documented props (e.g. variant, size, margin). Prefer these over inline style. Any `margin` or `padding` prop follows the suffix rule. See `docs/<ComponentName>.md` for the full prop list.

### Example (correct)
```jsx
<Typography variant="h4" align="center" margin="b-2">Login</Typography>
```

### Example (avoid)
```jsx
<Typography variant="h4" style={{ textAlign: "center", marginBottom: "1rem" }}>Login</Typography>
```

## Component Documentation

All component documentation is located in the `docs/` folder. The following documentation files are available:

### Button Component
- File: `docs/Button.md`
- Purpose: A highly customizable and interactive UI element designed to handle user actions with various styles, sizes, and variants. Supports loading states, disabled states, and click events.
- Key Features: Variants (solid, outline, ghost, icon), sizes (small, medium), loading states, disabled states, fluid layout, margin spacing
- Types: ButtonProps, ButtonSize, ButtonVariant, ButtonMargin, SpacingOption

### Typography Component
- File: `docs/Typography.md`
- Purpose: Provides a consistent set of text styles for headings, paragraphs, and inline elements, ensuring clear hierarchy, readability, and brand-aligned communication across the interface.
- Key Features: Variants (h1-h6, p, span, small), text alignment, word breaking, bold text, margin spacing
- Types: TypographyProps, TypographyVariant, TypographyAlign, TypographyWordBreak, TypographyMargin, SpacingOption

### Icon Component
- File: `docs/Icon.md`
- Purpose: A versatile and reusable element for displaying scalable vector icons, supporting various sizes, colors, and custom classes. Uses Google Material Symbols.
- Key Features: Material Symbols integration, sizes (small, medium, large), colors (black, white, gray, blue, green, red, yellow, orange)
- Types: IconProps, IconSize, IconColor
- Note: Requires Material Symbols font to be included in the project

### MediaObject Component
- File: `docs/MediaObject.md`
- 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`
- Purpose: Displays user initials, an image, or a Material icon in a consistent circle. Use for user identity in headers, lists, MediaObject, or anywhere you need a compact avatar.
- Key Features: Display modes (initials, image, icon), sizes (small, medium), margin spacing (suffix API: e.g. "0" → m-0), optional onClick; backgrounds from CSS (className overrides), no inline style prop
- Types: AvatarProps, AvatarSize, AvatarMargin, SpacingOption; icon prop uses MaterialIconName from Icon
- Related Components: Used by MediaObject; often used with Container, Icon

### Container Component
- File: `docs/Container.md`
- Purpose: A layout wrapper that controls display type, width, spacing (margin, padding, gap), and flex alignment. Use it to structure content, create flex layouts, and apply consistent spacing.
- Key Features: Display (block, flex, inline-block), width variants, margin/padding/gap spacing (suffix API: e.g. "4" → p-4, "0" → m-0), flex align/justify, responsive width at 600px
- Types: ContainerProps, ContainerDisplay, ContainerWidth, ContainerJustify, ContainerAlign, ContainerSpacing, SpacingOption

### Dropdown Component
- File: `docs/Dropdown.md`
- Purpose: Floating panel that shows content relative to a trigger. Use for menus, option lists, or any content that opens on click.
- Key Features: 12 placements, flip/shift to stay in viewport, three trigger modes (trigger element, renderTrigger, triggerLabel), close on outside click or Escape; **recommended account menu content** (user meta Typography + padding aligned to vertical MenuList + divider + MenuList; same for Header and AppShell `headerRight`)
- Types: DropdownProps, DropdownPlacement, DropdownTriggerProps, DropdownRenderTriggerParams
- Related Components: Button (trigger), Avatar (account trigger), MenuList (content), Header, AppShell

### Alert Component
- File: `docs/Alert.md`
- Purpose: Displays a short message with optional variant icon and dismiss button. Use for inline feedback (success, error, warning, info) or neutral notices.
- Key Features: Variants (default, info, warning, error, success), sizes (small, medium), dismissible with onDismiss, margin spacing (suffix API), unmounts on dismiss
- Types: AlertProps, AlertSize, AlertVariant, AlertMargin, SpacingOption
- Related Components: Typography, Container, Button, Icon (used internally)

### Spinner Component
- File: `docs/Spinner.md`
- Purpose: Loading indicator that shows a rotating Material icon. Use for progress or activity states.
- Key Features: Six icon options (progress_activity, autorenew, sync, refresh, cached, loop), sizes (small, medium, large), variants (light, dark), margin spacing (suffix API)
- Types: SpinnerProps, SpinnerSize, SpinnerVariant, SpinnerIcon, SpinnerMargin, SpacingOption
- Related Components: Container, Icon (used internally)

### Stepper Component
- File: `docs/Stepper.md`
- Purpose: Displays a sequence of steps for wizards or multi-step flows. Each step has label, key, and optional active/completed state; steps can be clickable.
- 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`
- Purpose: Renders a semantic navigation trail (e.g. Home → Products → Current page). Use at the top of a page to show hierarchy and let users navigate back. Last item without href is the current page.
- Key Features: Semantic nav/ol/li, aria-current="page", Schema.org BreadcrumbList, separators (chevron, slash), items (label, optional href), margin spacing (suffix API)
- Types: BreadCrumbProps, BreadCrumbItem, BreadCrumbSeparator, BreadCrumbMargin, SpacingOption
- Related Components: Container, Typography, Icon (used internally), Header

### Accordion Component
- File: `docs/Accordion.md`
- Purpose: Collapsible panels from array of title and content items. For FAQ sections, feature lists, or expandable content.
- Key Features: items (title, content), allowMultiple, defaultExpandedIndex, iconVariant (expand, plus), variant (grouped, spaced), titleTag (span, h2–h6 for SEO), margin, padding (suffix API), className
- Types: AccordionProps, AccordionItem, AccordionIconVariant, AccordionVariant, AccordionTitleTag, AccordionMargin, AccordionPadding
- Related Components: Container, Typography, Icon (used internally)

### ConfirmDialog Component
- File: `docs/ConfirmDialog.md`
- Purpose: Modal dialog for confirmation actions (delete, discard, proceed). Title, description, primary/secondary buttons, optional close button; overlay and Escape to close.
- Key Features: Variants (default, destructive, warning), sizes (small, medium, large), showCloseButton, closeOnOverlayClick, closeOnEscape, focus and body scroll management
- Types: ConfirmDialogProps, ConfirmDialogSize, ConfirmDialogVariant
- Related Components: Button, Typography, Icon (used internally)

### Modal Component
- File: `docs/Modal.md`
- Purpose: Full-featured modal overlay for forms, long content, or custom dialogs. Optional title, close button, footer primary/secondary buttons; overlay and Escape to close.
- Key Features: Sizes (small, medium, large, fullscreen), showCloseButton, closeOnOverlayClick, closeOnEscape, margin spacing, contentClassName/overlayClassName, focus and body scroll management
- Types: ModalProps, ModalSize, ModalMargin, SpacingOption
- Related Components: ConfirmDialog (simpler confirm-only), Button, Typography, Icon (used internally)

### Pagination Component
- File: `docs/Pagination.md`
- Purpose: Navigate large content sets by pages. Shows total count, prev/next and page-number buttons with ellipsis, and optional rows-per-page select. Controlled via currentPage and rowsPerPage.
- Key Features: Variants (default, minimal), rowsPerPageOptions, onPageChange(page, rowsPerPage), onRowsPerPageChange(rowsPerPage), margin spacing (suffix API)
- Types: PaginationProps, PaginationVariant, PaginationMargin, PaginationRowsPerPageOption, SpacingOption
- Related Components: Table (often used with Pagination), Container, Button, FormControls.Select, Typography, Icon (used internally)

### Table Component
- File: `docs/Table.md`
- Purpose: Displays structured data in a table with configurable columns, optional built-in pagination, and responsive mobile view (MediaObject cards when viewport < 768px and mobileColumns set).
- Key Features: columns (id, title, textAlign, widthPercentage, customRender), data (TableRow[]), variants (default, compact), mobileColumns, onRowClick, pagination props (totalItems, currentPage, onPageChange, etc.), hidePagination, margin (suffix API)
- Types: TableProps, TableColumn, TableRow, TableVariant, TableMargin, TableColumnTextAlign, TableMobileColumns, TableMobileColumnKey, TableMobileColumnField, SpacingOption
- Related Components: Pagination (built-in), MediaObject (mobile view), Typography, Container, Badge (often in customRender)

### Badge Component
- File: `docs/Badge.md`
- Purpose: Short label with colored background for status, tags, or counts. Inline-block, five variants.
- Key Features: label, variant (default, info, success, warning, error), className
- Types: BadgeProps, BadgeVariant
- Related Components: Table (often in customRender for status columns), Container (layout for multiple badges)

### Pills Component
- File: `docs/Pills.md`
- Purpose: Single tag/chip with modes: read-only (label only), edit (input + submit), remove (label + close). For tags, filters, editable chips.
- Key Features: mode (read-only, edit, remove), label, placeholder, onSubmit(value), onRemove(), isLoading, isDisabled, margin (suffix API)
- Types: PillsProps, PillsMode, PillsMargin, SpacingOption
- Related Components: Container (layout), FormControls.Input, Button, Icon, Spinner, Typography (used internally)

### Animated Component
- File: `docs/Animated.md`
- Purpose: Atom that adds scroll-triggered entrance/exit animations. Uses IntersectionObserver; applies animation class when element enters viewport.
- Key Features: animationType (fade-in/out top, right, bottom, left), as (polymorphic root), delay (ms for stagger), margin (suffix API), isBlock
- Types: AnimatedProps, AnimatedMargin, AnimationType, AnimationDelay, SpacingOption
- Related Components: Container, Typography, Avatar (content); Header, BottomSheet, MenuList (use Animated internally)

### FormControls
- File: `docs/FormControls.md`
- 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
- File: `docs/Toast.md`
- Purpose: Displays transient messages in a portal (fixed top-right). Use ref.addMessage({ mode, message }) imperatively.
- Key Features: Imperative API (addMessage), variants (info, error, warning, success), autoClose, autoCloseTime, portal rendering, click to dismiss
- Types: ToastProps, ToastRefHandle, ToastMessage, ToastVariant
- Related Components: Alert (inline feedback), Button (trigger), Container (layout)

### MenuList Component
- File: `docs/MenuList.md`
- Purpose: Renders a list of navigational items with optional icons, active state highlighting, and customizable layout.
- Key Features: items (label, value, icon), activeItem, direction (horizontal, vertical), sizes (small, medium, large), variants (light, dark), margin (suffix API), onMenuClick(item), Animated entrance
- Types: MenuListProps, MenuListItem, MenuListSize, MenuListVariant, MenuListDirection, MenuListMargin
- Related Components: Dropdown (content), Header (navigation), Container, Typography, Icon, Animated (used internally)

### Header Component
- File: `docs/Header.md`
- Purpose: Responsive navigation header with logo, menu items, and customizable left/center/right slots.
- Key Features: logoUrl, menuItems, activeMenuItem, onMenuItemClick, headerLeft, headerCenter, headerRight, showCenterMenu, sizes (small, medium, large), variants (light, dark), margin (suffix API), responsive mobile menu; **headerRight** account menus: Dropdown + Avatar + user meta + vertical MenuList (see `docs/Dropdown.md`)
- Types: HeaderProps, HeaderSize, HeaderVariant, HeaderMargin
- Related Components: MenuList (center and mobile menu), Dropdown, Avatar (headerRight), AppShell, Button, Icon, Animated (used internally)

### PageHeader Component
- File: `docs/PageHeader.md`
- Purpose: Two-column page header: left (title, subtitle), right (primary CTA, more menu with three-dots icon). For page/section headings and actions.
- Key Features: title, subtitle (string or ReactNode), primaryCta (ReactNode), moreMenuItems (label, onClick) or moreMenuContent, right column aligned right, className
- Types: PageHeaderProps, PageHeaderMoreMenuItem
- Related Components: Button, Typography, Dropdown, Icon (used internally), Container

### BottomSheet Component
- File: `docs/BottomSheet.md`
- Purpose: Slides up from the bottom of the screen for additional content, forms, or actions.
- Key Features: isOpen, onClose, snap points (30%, 60%, 90%), drag-to-close, touch and mouse support, body scroll lock, margin (suffix API)
- Types: BottomSheetProps, BottomSheetMargin
- Related Components: Modal, ConfirmDialog, Button, Container, Typography

### Footer Component
- File: `docs/Footer.md`
- Purpose: Customizable footer with copyright, optional powered-by link, and custom content via children.
- Key Features: brandName, poweredByLabel, poweredByLink, children, sizes (small, medium, large), variants (light, dark), margin (suffix API)
- Types: FooterProps, FooterSize, FooterVariant, FooterMargin
- Related Components: Container (footer columns), Typography (used internally), Header (app layout)

### AppShell Component
- File: `docs/AppShell.md`
- Purpose: Full-page layout combining optional Header (top), Footer (bottom), and MenuList as left sidebar with main content. For dashboard-style apps.
- Key Features: header (Header props or ReactNode), footer (Footer props or ReactNode), sidebar (AppShellSidebarConfig: items, activeItem, onMenuClick, size, variant), sidebarWidth, mobileSidebarDrawer / mobileSidebarDrawerLabel, responsive (sidebar column hidden ≤1024px; default Floating UI drawer when no HeaderProps header, else header mobile menu); with Header + sidebar use Header `showCenterMenu: false` to avoid duplicate desktop nav; **headerRight** uses same account Dropdown pattern as standalone Header (`docs/Dropdown.md`)
- Types: AppShellProps, AppShellSidebarConfig
- Related Components: Header, Footer, MenuList (sidebar), Dropdown, Container, Typography, Avatar

## Documentation Format

All documentation files follow a consistent format:
1. Component name and purpose
2. Props/Inputs table with types, defaults, and descriptions
3. TypeScript type definitions
4. Usage examples covering common use cases
5. Behavior notes explaining important details
6. Related components and links

## Quick Reference

| Component | File | Primary Use Case |
|-----------|------|------------------|
| Button | `docs/Button.md` | User actions and interactions |
| Typography | `docs/Typography.md` | Text content and headings |
| Icon | `docs/Icon.md` | Visual icons and symbols |
| MediaObject | `docs/MediaObject.md` | Media + content layouts |
| Avatar | `docs/Avatar.md` | User identity (initials, image, or icon) |
| Container | `docs/Container.md` | Layout, spacing, and flex structure |
| 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` | 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 |
| Modal | `docs/Modal.md` | Forms, long content, and custom dialogs |
| Pagination | `docs/Pagination.md` | Page navigation for tables and lists |
| Table | `docs/Table.md` | Structured tabular data with optional pagination and mobile view |
| 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, **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 |
| PageHeader | `docs/PageHeader.md` | Page title, subtitle, primary CTA, and more menu |
| BottomSheet | `docs/BottomSheet.md` | Slide-up panel for forms and actions |
| Footer | `docs/Footer.md` | App footer with copyright and optional links |
| AppShell | `docs/AppShell.md` | Dashboard layout with header, sidebar, footer, and main content |

## Additional Resources

- Component source code: `src/components/`
- Storybook documentation: Available at the project's Storybook instance
- Type definitions: `src/types/` and component-specific type exports
- Storybook static build: `storybook-static/`
- Component stories: `src/stories/`

## Installation

```bash
npm install cleanplate
```

## Usage

```jsx
import { Button, Typography, Icon, MediaObject, Avatar, Container, Dropdown, Alert, Spinner, Stepper, BreadCrumb, Accordion, ConfirmDialog, Modal, Pagination, Table, Badge, Pills, Animated, FormControls, Toast, MenuList, Header, PageHeader, BottomSheet, Footer, AppShell } from "cleanplate";
```