cleanplate 0.1.11 → 0.2.1

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)

package/docs/Spinner.md

@@ -0,0 +1,115 @@
+# Spinner Component
+
+Purpose: A loading indicator that shows a rotating Material icon. Use it for progress or activity states. Supports six icon options (all animate when rotated), sizes, light/dark variant, and margin spacing.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| size | "small" \| "medium" \| "large" | no | "medium" | Size of the spinner. |
+| variant | "light" \| "dark" | no | "light" | Visual variant; use dark on dark backgrounds. |
+| icon | SpinnerIcon | no | "progress_activity" | Icon to display as the spinner. One of: progress_activity, autorenew, sync, refresh, cached, loop. |
+| margin | string \| string[] | no | "0" | Spacing **suffix** for outer margin. The component adds the `m-` prefix (e.g. `"0"` → m-0, `"b-2"` → m-b-2). Use a single string or array. |
+| className | string | no | "" | Additional class names for the wrapper. |
+
+## Types
+
+### SpinnerSize
+```typescript
+type SpinnerSize = "small" | "medium" | "large";
+```
+
+### SpinnerVariant
+```typescript
+type SpinnerVariant = "light" | "dark";
+```
+
+### SpinnerIcon
+```typescript
+type SpinnerIcon =
+  | "progress_activity"
+  | "autorenew"
+  | "sync"
+  | "refresh"
+  | "cached"
+  | "loop";
+```
+
+### SpacingOption
+```typescript
+type SpacingOption = (typeof SPACING_OPTIONS)[number];
+```
+
+### SpinnerMargin
+```typescript
+type SpinnerMargin = string | SpacingOption[];
+```
+
+### SpinnerProps
+```typescript
+interface SpinnerProps {
+  size?: SpinnerSize;
+  variant?: SpinnerVariant;
+  icon?: SpinnerIcon;
+  margin?: SpinnerMargin;
+  className?: string;
+}
+```
+
+## Usage Examples
+
+### Basic
+
+```jsx
+import { Spinner } from "cleanplate";
+
+export const Example = () => <Spinner size="medium" variant="light" />;
+```
+
+### Icon options
+
+All of these icons rotate via the same CSS animation.
+
+```jsx
+import { Spinner } from "cleanplate";
+
+<Spinner />                     // progress_activity (default)
+<Spinner icon="autorenew" />    // Circular arrows
+<Spinner icon="sync" />         // Sync arrows
+<Spinner icon="refresh" />      // Refresh arrows
+<Spinner icon="cached" />       // Cache/refresh arrows
+<Spinner icon="loop" />         // Circular loop
+```
+
+### Sizes and variants
+
+```jsx
+<Spinner size="small" />
+<Spinner size="medium" />
+<Spinner size="large" />
+<Spinner variant="light" />
+<Spinner variant="dark" />
+```
+
+### With Container
+
+```jsx
+import { Spinner, Container } from "cleanplate";
+
+export const Example = () => (
+  <Container padding="4">
+    <Spinner icon="sync" size="medium" margin="b-2" />
+  </Container>
+);
+```
+
+## Behavior Notes
+
+- **Animation:** The icon is rotated continuously via CSS (class `cp-spinner-icon`). All six icon options work with this rotation.
+- **Layout:** Spinner renders a Container wrapping an Icon; size and variant classes apply to the wrapper.
+- **Spacing:** `margin` accepts the **spacing suffix**; the component adds the `m-` prefix via `getSpacingClass`. Use suffix form (e.g. `"0"`, `"b-2"`) when passing values.
+
+## Related Components / Links
+
+- Container (used internally as the wrapper; use for layout around the spinner)
+- Icon (used internally to render the Material icon that rotates)