cleanplate 0.2.0 → 0.2.2

package/docs/MenuList.md

@@ -0,0 +1,113 @@
+# MenuList Component
+
+Purpose: Renders a list of navigational items with optional icons, active state highlighting, and customizable layout. Use for nav menus, sidebars, or link lists. Supports horizontal and vertical directions, sizes (small, medium, large), variants (light, dark), and margin spacing. Items use Animated with fade-in-left on mount.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| items | MenuListItem[] | yes | — | List of menu items; each has label, value, optional icon. |
+| activeItem | string | no | — | Value of the currently active item (matches item.value). |
+| size | "small" \| "medium" \| "large" | no | — | Size of menu items. |
+| variant | "light" \| "dark" | no | — | Visual variant. |
+| direction | "horizontal" \| "vertical" | no | "horizontal" | Layout direction of the list. |
+| margin | string \| SpacingOption[] | no | — | Spacing suffix(s) for outer margin; component adds m- prefix. |
+| className | string | no | "" | Additional class names for the root element. |
+| onMenuClick | (item: MenuListItem) => void | no | — | Called when a menu item is clicked; receives the clicked item. |
+
+## Types
+
+### MenuListItem
+```typescript
+interface MenuListItem {
+  label: string;
+  value: string;
+  icon?: MaterialIconName;  // optional Material icon name
+}
+```
+
+### MenuListSize
+```typescript
+type MenuListSize = "small" | "medium" | "large";
+```
+
+### MenuListVariant
+```typescript
+type MenuListVariant = "light" | "dark";
+```
+
+### MenuListDirection
+```typescript
+type MenuListDirection = "horizontal" | "vertical";
+```
+
+### MenuListProps
+```typescript
+interface MenuListProps {
+  items: MenuListItem[];
+  activeItem?: string;
+  size?: MenuListSize;
+  variant?: MenuListVariant;
+  direction?: MenuListDirection;
+  margin?: MenuListMargin;
+  className?: string;
+  onMenuClick?: (item: MenuListItem) => void;
+}
+```
+
+## Usage Examples
+
+### Basic
+
+```jsx
+import { useState } from "react";
+import { MenuList } from "cleanplate";
+
+const ITEMS = [
+  { label: "Dashboard", value: "/", icon: "speed" },
+  { label: "Projects", value: "/projects", icon: "receipt_long" },
+];
+
+const Nav = () => {
+  const [activeItem, setActiveItem] = useState("/");
+  return (
+    <MenuList
+      items={ITEMS}
+      activeItem={activeItem}
+      onMenuClick={(item) => setActiveItem(item.value)}
+    />
+  );
+};
+```
+
+### Directions and variants
+
+```jsx
+<MenuList items={items} direction="horizontal" activeItem={activeItem} onMenuClick={handleClick} />
+<MenuList items={items} direction="vertical" activeItem={activeItem} onMenuClick={handleClick} />
+<MenuList items={items} variant="light" activeItem={activeItem} onMenuClick={handleClick} />
+<MenuList items={items} variant="dark" activeItem={activeItem} onMenuClick={handleClick} />
+```
+
+### Sizes
+
+```jsx
+<MenuList items={items} size="small" activeItem={activeItem} onMenuClick={handleClick} />
+<MenuList items={items} size="medium" activeItem={activeItem} onMenuClick={handleClick} />
+<MenuList items={items} size="large" activeItem={activeItem} onMenuClick={handleClick} />
+```
+
+## Behavior Notes
+
+- **Items:** Each item must have `label` and `value`. `icon` is optional (Material icon name).
+- **onMenuClick:** Called with the clicked item. Use it to update `activeItem` or navigate.
+- **DOM:** A `div` wrapping a `ul` of `li` elements; each `li` contains an anchor.
+- **Animated:** Each item is wrapped in Animated with `fade-in-left` and staggered delay.
+- **Margin:** Uses the suffix API (e.g. `"0"` → m-0, `"b-2"` → m-b-2).
+
+## Related Components / Links
+
+- Dropdown (often uses MenuList inside for menu items)
+- Header (commonly uses MenuList for navigation)
+- Container (layout around the menu)
+- Typography, Icon, Animated (used internally)

package/docs/Modal.md

@@ -0,0 +1,152 @@
+# Modal Component
+
+Purpose: A full-featured modal overlay for forms, long content, or custom dialogs. Use it when you need a larger, flexible dialog than ConfirmDialog—with optional title, close button, footer actions, and configurable close behavior (overlay click, Escape). Supports body scroll lock and focus management when open.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| children | React.ReactNode | yes | — | Modal body content. |
+| isOpen | boolean | no | false | Whether the modal is visible. |
+| onClose | () => void | no | — | Called when the modal should close (close button, overlay, or Escape). |
+| title | string | no | "" | Title displayed in the modal header. |
+| size | "small" \| "medium" \| "large" \| "fullscreen" | no | "medium" | Size of the modal panel. |
+| showCloseButton | boolean | no | true | Whether to show the X close button in the header. |
+| closeOnOverlayClick | boolean | no | true | Whether clicking the overlay closes the modal. |
+| closeOnEscape | boolean | no | true | Whether pressing Escape closes the modal. |
+| margin | string \| SpacingOption[] | no | "m-0" | Margin around the modal. Use full class string (e.g. "m-0") or array of spacing suffixes; component adds `m-` prefix. |
+| className | string | no | "" | Additional class names for the modal panel. |
+| overlayClassName | string | no | "" | Additional class names for the overlay. |
+| contentClassName | string | no | "" | Additional class names for the content wrapper. |
+| primaryButtonLabel | string | no | "" | Label for the primary footer button; empty hides it. |
+| onPrimaryButtonClick | () => void | no | — | Called when the primary footer button is clicked. |
+| secondaryButtonLabel | string | no | "" | Label for the secondary footer button; empty hides it. |
+| onSecondaryButtonClick | () => void | no | — | Called when the secondary footer button is clicked. |
+
+## Types
+
+### SpacingOption
+```typescript
+type SpacingOption = (typeof SPACING_OPTIONS)[number];
+```
+
+### ModalSize
+```typescript
+type ModalSize = "small" | "medium" | "large" | "fullscreen";
+```
+
+### ModalMargin
+```typescript
+type ModalMargin = string | SpacingOption[];
+```
+
+### ModalProps
+```typescript
+interface ModalProps {
+  children: React.ReactNode;
+  isOpen?: boolean;
+  onClose?: () => void;
+  title?: string;
+  size?: ModalSize;
+  showCloseButton?: boolean;
+  closeOnOverlayClick?: boolean;
+  closeOnEscape?: boolean;
+  margin?: ModalMargin;
+  className?: string;
+  overlayClassName?: string;
+  contentClassName?: string;
+  primaryButtonLabel?: string;
+  onPrimaryButtonClick?: () => void;
+  secondaryButtonLabel?: string;
+  onSecondaryButtonClick?: () => void;
+}
+```
+
+## Usage Examples
+
+### Basic
+
+```jsx
+import { Modal, Button, Typography } from "cleanplate";
+import { useState } from "react";
+
+const App = () => {
+  const [isOpen, setIsOpen] = useState(false);
+  return (
+    <>
+      <Button onClick={() => setIsOpen(true)}>Open Modal</Button>
+      <Modal
+        isOpen={isOpen}
+        onClose={() => setIsOpen(false)}
+        title="Modal Title"
+      >
+        <Typography variant="p">Modal body content goes here.</Typography>
+      </Modal>
+    </>
+  );
+};
+```
+
+### Sizes
+
+```jsx
+<Modal size="small" title="Small" isOpen={isOpen} onClose={onClose}>...</Modal>
+<Modal size="medium" title="Medium" isOpen={isOpen} onClose={onClose}>...</Modal>
+<Modal size="large" title="Large" isOpen={isOpen} onClose={onClose}>...</Modal>
+<Modal size="fullscreen" title="Fullscreen" isOpen={isOpen} onClose={onClose}>...</Modal>
+```
+
+### With footer buttons
+
+```jsx
+<Modal
+  isOpen={isOpen}
+  onClose={() => setIsOpen(false)}
+  title="Save Changes"
+  primaryButtonLabel="Save"
+  onPrimaryButtonClick={handleSave}
+  secondaryButtonLabel="Cancel"
+  onSecondaryButtonClick={() => setIsOpen(false)}
+>
+  <Typography variant="p">Review and save your changes.</Typography>
+</Modal>
+```
+
+### Close behavior
+
+```jsx
+<Modal
+  showCloseButton={true}
+  closeOnOverlayClick={true}
+  closeOnEscape={true}
+  onClose={handleClose}
+  ...
+/>
+```
+
+### Form inside modal
+
+```jsx
+<Modal isOpen={isOpen} onClose={() => setIsOpen(false)} title="Contact Form" size="medium">
+  <form onSubmit={handleSubmit}>
+    {/* form fields */}
+    <Button type="submit">Submit</Button>
+  </form>
+</Modal>
+```
+
+## Behavior Notes
+
+- **Rendering:** When `isOpen` is false, the component returns `null` (nothing in the DOM).
+- **Close:** onClose is called when the user clicks the X button (if showCloseButton), the overlay (if closeOnOverlayClick), or Escape (if closeOnEscape). Footer buttons do not auto-close; call onClose in their handlers if desired.
+- **Body scroll:** When open, `document.body.style.overflow` is set to `"hidden"`; restored on close.
+- **Focus:** On open, focus moves to the modal panel (ref + tabIndex={-1}); on close, focus returns to the previously focused element.
+- **ARIA:** The overlay has `role="dialog"`, `aria-modal="true"`, and `aria-labelledby` pointing to the title when present.
+- **Spacing:** `margin` accepts a full class string (e.g. "m-0") or an array of spacing suffixes; the component uses `getSpacingClass` with prefix `m-`.
+
+## Related Components / Links
+
+- ConfirmDialog (simpler confirmation-only modal with title, description, primary/secondary actions)
+- Button (often used to open the modal and for footer actions)
+- Typography (used for title and body content)
+- Icon (used for the close button)

package/docs/PageHeader.md

@@ -0,0 +1,134 @@
+# PageHeader Component
+
+Purpose: Two-column page header with left column (title and optional subtitle) and right column (primary CTA and optional more menu with three-dots icon). Use at the top of a page or section. Right column is aligned to the right edge. Title and subtitle accept string or ReactNode; more menu can be a list of items (label, onClick) or custom content via moreMenuContent.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| title | ReactNode | yes | — | Page title (left column). String or custom ReactNode. |
+| subtitle | ReactNode | no | — | Optional subtitle below the title (left column). |
+| primaryCta | ReactNode | no | — | Primary call-to-action, e.g. a Button (right column). |
+| moreMenuItems | PageHeaderMoreMenuItem[] | no | — | More menu items; renders three-dots (more_vert) icon and dropdown. Each item has label and optional onClick; menu closes after click. |
+| moreMenuContent | ReactNode | no | — | Custom content for the more menu dropdown instead of moreMenuItems (right column). |
+| className | string | no | "" | Additional class name for the root element. |
+
+## Types
+
+### PageHeaderMoreMenuItem
+```typescript
+interface PageHeaderMoreMenuItem {
+  label: string;      // Menu item label
+  onClick?: () => void;  // Called when clicked; menu closes after
+}
+```
+
+### PageHeaderProps
+```typescript
+interface PageHeaderProps {
+  title: React.ReactNode;
+  subtitle?: React.ReactNode;
+  primaryCta?: React.ReactNode;
+  moreMenuItems?: PageHeaderMoreMenuItem[];
+  moreMenuContent?: React.ReactNode;
+  className?: string;
+}
+```
+
+## Usage Examples
+
+### Full header
+
+```jsx
+import { PageHeader, Button } from "cleanplate";
+
+<PageHeader
+  title="Projects"
+  subtitle="Manage and track your team projects"
+  primaryCta={<Button>New project</Button>}
+  moreMenuItems={[
+    { label: "Export", onClick: () => exportData() },
+    { label: "Archive", onClick: () => archive() },
+    { label: "Settings", onClick: () => openSettings() },
+  ]}
+/>
+```
+
+### Title and subtitle only
+
+```jsx
+<PageHeader
+  title="Settings"
+  subtitle="Configure your account and preferences"
+/>
+```
+
+### With primary CTA only
+
+```jsx
+<PageHeader
+  title="Documents"
+  subtitle="All your documents in one place"
+  primaryCta={<Button>Upload</Button>}
+/>
+```
+
+### With more menu only
+
+```jsx
+<PageHeader
+  title="Report"
+  subtitle="Generated on 17 Feb 2025"
+  moreMenuItems={[
+    { label: "Print", onClick: handlePrint },
+    { label: "Download PDF", onClick: handleDownload },
+    { label: "Share", onClick: handleShare },
+  ]}
+/>
+```
+
+### Custom title (ReactNode)
+
+```jsx
+<PageHeader
+  title={
+    <span style={{ display: "flex", alignItems: "center", gap: "8px" }}>
+      <span>📋</span>
+      Custom title
+    </span>
+  }
+  subtitle="Optional subtitle"
+  primaryCta={<Button>Action</Button>}
+/>
+```
+
+### Custom more menu content
+
+```jsx
+<PageHeader
+  title="Page"
+  primaryCta={<Button>Save</Button>}
+  moreMenuContent={
+    <div style={{ padding: "8px" }}>
+      <a href="/export">Export</a>
+      <hr />
+      <button type="button">Settings</button>
+    </div>
+  }
+/>
+```
+
+## Behavior Notes
+
+- **Layout:** Root is a `<header>`. Flex row: left (title + subtitle), right (CTA + more trigger). Right column uses margin-left: auto for right alignment.
+- **Title / subtitle:** If string, rendered with Typography (h4 / p). If ReactNode, rendered in a div with the same layout class.
+- **More menu:** When moreMenuItems is set, renders a Dropdown with an icon Button (more_vert) and a list; each item onClick runs and the dropdown closes. When moreMenuContent is set, that content is shown in the dropdown. Use one or the other.
+- **Accessibility:** More trigger has aria-expanded and aria-haspopup; list uses role="menu" and role="menuitem".
+
+## Related Components / Links
+
+- Button (typically for primaryCta)
+- Typography (used internally for string title and subtitle)
+- Dropdown (used internally for the more menu)
+- Icon (more_vert trigger)
+- Container (wrap PageHeader and page content)

package/docs/Pagination.md

@@ -0,0 +1,142 @@
+# Pagination Component
+
+Purpose: Lets users navigate large sets of content by splitting them into pages. Shows total count, previous/next and page-number buttons (with ellipsis for long ranges), and an optional “rows per page” select. Use it below tables, lists, or search results. Fully controlled via `currentPage` and `rowsPerPage` with `onPageChange` and `onRowsPerPageChange`.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| totalItems | number | yes | — | Total number of items across all pages. |
+| totalLabel | string | no | "Items" | Label for the total count (e.g. "Items", "Results"). |
+| currentPage | number | yes | — | Current 1-based page number (controlled). |
+| rowsPerPage | number | no | 10 | Number of rows per page. |
+| rowsPerPageOptions | PaginationRowsPerPageOption[] | no | [{ label: "10", value: 10 }, ...] | Options for the rows-per-page select; each has `label` and `value` (number). |
+| onPageChange | (page, rowsPerPage) => void | yes | — | Called when the page changes; receives (page, rowsPerPage). |
+| onRowsPerPageChange | (rowsPerPage: number) => void | no | — | Called when the user changes rows per page; receives the new value. |
+| variant | "default" \| "minimal" | no | "default" | Visual variant. |
+| margin | string \| SpacingOption[] | no | "0" | Margin spacing. Suffix or array of spacing suffixes; component adds `m-` prefix (e.g. "0" → m-0). |
+| className | string | no | "" | Additional class names for the root element. |
+
+## Types
+
+### SpacingOption
+```typescript
+type SpacingOption = (typeof SPACING_OPTIONS)[number];
+```
+
+### PaginationVariant
+```typescript
+type PaginationVariant = "default" | "minimal";
+```
+
+### PaginationMargin
+```typescript
+type PaginationMargin = string | SpacingOption[];
+```
+
+### PaginationRowsPerPageOption
+```typescript
+interface PaginationRowsPerPageOption {
+  label: string;
+  value: number;
+}
+```
+
+### PaginationProps
+```typescript
+interface PaginationProps {
+  totalItems: number;
+  totalLabel?: string;
+  currentPage: number;
+  rowsPerPage?: number;
+  rowsPerPageOptions?: PaginationRowsPerPageOption[];
+  onPageChange: (page: number, rowsPerPage: number) => void;
+  onRowsPerPageChange?: (rowsPerPage: number) => void;
+  variant?: PaginationVariant;
+  margin?: PaginationMargin;
+  className?: string;
+}
+```
+
+## Usage Examples
+
+### Basic
+
+```jsx
+import { Pagination } from "cleanplate";
+import { useState } from "react";
+
+const App = () => {
+  const [currentPage, setCurrentPage] = useState(1);
+  const [rowsPerPage, setRowsPerPage] = useState(10);
+
+  return (
+    <Pagination
+      totalItems={120}
+      totalLabel="Items"
+      currentPage={currentPage}
+      rowsPerPage={rowsPerPage}
+      onPageChange={(page) => setCurrentPage(page)}
+      onRowsPerPageChange={(rpp) => {
+        setRowsPerPage(rpp);
+        setCurrentPage(1);
+      }}
+    />
+  );
+};
+```
+
+### Variants
+
+```jsx
+<Pagination variant="default" totalItems={120} currentPage={currentPage} rowsPerPage={rowsPerPage} onPageChange={handlePageChange} onRowsPerPageChange={handleRowsPerPageChange} />
+<Pagination variant="minimal" totalItems={120} currentPage={currentPage} rowsPerPage={rowsPerPage} onPageChange={handlePageChange} onRowsPerPageChange={handleRowsPerPageChange} />
+```
+
+### Custom rows per page options
+
+```jsx
+const options = [
+  { label: "10", value: 10 },
+  { label: "25", value: 25 },
+  { label: "50", value: 50 },
+  { label: "100", value: 100 },
+];
+
+<Pagination
+  totalItems={500}
+  currentPage={currentPage}
+  rowsPerPage={rowsPerPage}
+  rowsPerPageOptions={options}
+  onPageChange={handlePageChange}
+  onRowsPerPageChange={handleRowsPerPageChange}
+/>
+```
+
+### With Table
+
+```jsx
+import { Table, Pagination } from "cleanplate";
+
+// Table can hide its built-in pagination (hidePagination) and you render Pagination below with your own state.
+<Pagination
+  totalItems={totalCount}
+  currentPage={page}
+  rowsPerPage={pageSize}
+  onPageChange={(p, rpp) => { setPage(p); }}
+  onRowsPerPageChange={(rpp) => { setPageSize(rpp); setPage(1); }}
+/>
+```
+
+## Behavior Notes
+
+- **Controlled:** You must hold `currentPage` (and typically `rowsPerPage`) in state and pass them in; update them in `onPageChange` and `onRowsPerPageChange`.
+- **onPageChange:** Called when the user clicks a page number or prev/next; receives `(page, rowsPerPage)`. Update `currentPage` in state.
+- **onRowsPerPageChange:** Called when the user selects a new rows-per-page value; receives the new number. Update `rowsPerPage` and usually set `currentPage` to 1.
+- **Page buttons:** First page, last page, and a range around the current page are shown; gaps are represented as ellipsis (disabled "..." button).
+- **Spacing:** `margin` uses the suffix API; the component adds the `m-` prefix via `getSpacingClass`.
+
+## Related Components / Links
+
+- Table (often used with Pagination for tabular data; Table can show Pagination via `hidePagination={false}` or you can render Pagination separately)
+- Container, Button, FormControls.Select, Typography, Icon (used internally)

package/docs/Pills.md

@@ -0,0 +1,104 @@
+# Pills Component
+
+Purpose: A single tag or chip that can show a label only (read-only), an inline input with submit (edit), or a label with a close button (remove). Use it for tags, filters, or editable chips where the user can add or remove items. Submit in edit mode via Enter or check button; remove via close button. Optional `isLoading` and `isDisabled`; margin uses the suffix API.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| margin | string \| SpacingOption[] | no | "0" | Margin spacing. Suffix or array of spacing suffixes; component adds `m-` prefix. |
+| className | string | no | "" | Additional class names for the root element. |
+| label | string | no | "" | Label in read-only/remove mode; initial value in edit mode. |
+| placeholder | string | no | "Add tag" | Placeholder for the input in edit mode. |
+| onSubmit | (value: string) => void | no | — | Called when user submits in edit mode (Enter or check); receives current input value. |
+| onRemove | () => void | no | — | Called when user clicks close in remove mode. |
+| isDisabled | boolean | no | false | Disables the input and action button. |
+| isLoading | boolean | no | false | Shows spinner instead of icon in edit/remove mode. |
+| mode | "read-only" \| "edit" \| "remove" | no | "read-only" | read-only (label only), edit (input + check), remove (label + close). |
+
+## Types
+
+### SpacingOption
+```typescript
+type SpacingOption = (typeof SPACING_OPTIONS)[number];
+```
+
+### PillsMargin
+```typescript
+type PillsMargin = string | SpacingOption[];
+```
+
+### PillsMode
+```typescript
+type PillsMode = "read-only" | "edit" | "remove";
+```
+
+### PillsProps
+```typescript
+interface PillsProps {
+  margin?: PillsMargin;
+  className?: string;
+  label?: string;
+  placeholder?: string;
+  onSubmit?: (value: string) => void;
+  onRemove?: () => void;
+  isDisabled?: boolean;
+  isLoading?: boolean;
+  mode?: PillsMode;
+}
+```
+
+## Usage Examples
+
+### Basic
+
+```jsx
+import { Pills } from "cleanplate";
+
+<Pills label="Taxi" mode="read-only" />
+<Pills mode="edit" placeholder="Add tag" onSubmit={(v) => console.log(v)} />
+<Pills label="Tag" mode="remove" onRemove={() => {}} />
+```
+
+### Controlled (edit)
+
+```jsx
+import { Pills } from "cleanplate";
+import { useState } from "react";
+
+const [tag, setTag] = useState("Taxi");
+<Pills
+  label={tag}
+  mode="edit"
+  placeholder="Add tag"
+  onSubmit={(v) => setTag(v)}
+  onRemove={() => setTag("")}
+/>
+```
+
+### Modes
+
+```jsx
+<Pills label="Tag" mode="read-only" />
+<Pills label="" mode="edit" placeholder="Add tag" onSubmit={onSubmit} />
+<Pills label="Tag" mode="remove" onRemove={onRemove} />
+```
+
+### Loading and disabled
+
+```jsx
+<Pills mode="edit" isLoading />
+<Pills label="Tag" mode="remove" isDisabled onRemove={() => {}} />
+```
+
+## Behavior Notes
+
+- **Edit mode:** Internal state holds the input value. On submit (Enter or check), `onSubmit(value)` is called and internal value is cleared. Parent can pass new `label` to reflect saved value.
+- **Remove mode:** Close button calls `onRemove()`; parent typically clears or unmounts the pill.
+- **Spacing:** `margin` uses the suffix API; the component adds the `m-` prefix via `getSpacingClass`.
+
+## Related Components / Links
+
+- Container (layout for multiple pills)
+- FormControls.Input, Button, Icon, Spinner (used internally)
+- Typography (used for label in read-only/remove mode)