cleanplate 0.2.0 → 0.2.2

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)

package/docs/Stepper.md

@@ -0,0 +1,131 @@
+# Stepper Component
+
+Purpose: Displays a sequence of steps (e.g. for a wizard or checkout). Each step has a label, optional active/completed state, and can be clickable. Use it for multi-step flows and progress indication. Supports horizontal and vertical layout.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| variant | "horizontal" \| "vertical" | no | — | Layout direction. |
+| 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 root element. |
+| config | StepperStepConfig[] | yes | — | Step definitions: each has label, key, and optionally isCompleted, isActive. |
+| onClick | (step: StepperStepConfig) => void | no | — | Called when a step is clicked; receives the step config. |
+
+## Types
+
+### StepperStepConfig
+```typescript
+interface StepperStepConfig {
+  label: string;        // Display label
+  key: string;          // Unique key (e.g. href fragment or route path)
+  isCompleted?: boolean;
+  isActive?: boolean;
+}
+```
+
+### StepperVariant
+```typescript
+type StepperVariant = "horizontal" | "vertical";
+```
+
+### SpacingOption
+```typescript
+type SpacingOption = (typeof SPACING_OPTIONS)[number];
+```
+
+### StepperMargin
+```typescript
+type StepperMargin = string | SpacingOption[];
+```
+
+### StepperProps
+```typescript
+interface StepperProps {
+  variant?: StepperVariant;
+  margin?: StepperMargin;
+  className?: string;
+  config: StepperStepConfig[];
+  onClick?: (step: StepperStepConfig) => void;
+}
+```
+
+## Usage Examples
+
+### Basic
+
+```jsx
+import { Stepper } from "cleanplate";
+
+const config = [
+  { label: "Details", key: "/details", isActive: true },
+  { label: "Review", key: "/review", isCompleted: true },
+  { label: "Confirm", key: "/confirm" },
+];
+
+export const Example = () => (
+  <Stepper config={config} variant="horizontal" />
+);
+```
+
+### With onClick
+
+```jsx
+import { Stepper } from "cleanplate";
+import { useState } from "react";
+
+const Example = () => {
+  const [active, setActive] = useState("step1");
+  const config = [
+    { label: "Step 1", key: "step1", isActive: active === "step1" },
+    { label: "Step 2", key: "step2", isActive: active === "step2" },
+  ];
+  return (
+    <Stepper config={config} onClick={(step) => setActive(step.key)} />
+  );
+};
+```
+
+### Horizontal and vertical
+
+```jsx
+<Stepper config={config} variant="horizontal" />
+<Stepper config={config} variant="vertical" />
+```
+
+### With completed steps
+
+```jsx
+<Stepper
+  config={[
+    { label: "Step 1", key: "1", isCompleted: true },
+    { label: "Step 2", key: "2", isCompleted: true },
+    { label: "Step 3", key: "3", isActive: true },
+    { label: "Step 4", key: "4" },
+  ]}
+  variant="horizontal"
+/>
+```
+
+### With Container
+
+```jsx
+import { Stepper, Container } from "cleanplate";
+
+<Container padding="4">
+  <Stepper config={config} variant="horizontal" margin="b-2" />
+</Container>
+```
+
+## Behavior Notes
+
+- **Links:** Each step label is an `<a href={step.key}>`. The component calls `preventDefault()` on click and invokes `onClick(step)` so you can control navigation (e.g. router) without following the href.
+- **Completed:** When `step.isCompleted` is true, the step number is replaced with a done icon.
+- **Active:** When `step.isActive` is true, the step gets the active CSS class.
+- **Spacing:** `margin` accepts the **spacing suffix**; the component adds the `m-` prefix via `getSpacingClass`.
+
+## Related Components / Links
+
+- Container (layout and spacing around the stepper)
+- Typography (headings above or near the stepper)
+- Icon (used internally for the done icon on completed steps)

package/docs/Table.md

@@ -0,0 +1,194 @@
+# Table Component
+
+Purpose: Displays structured data in a table with configurable columns, optional built-in pagination, and a responsive mobile view. Each row is an object; column `id` values match row keys for default cell rendering. Use `customRender` per column for badges, buttons, or custom content. When viewport is under 768px and `mobileColumns` is set, rows are shown as MediaObject cards instead of a table. Optional `onRowClick(rowData)` for clickable rows.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| columns | TableColumn[] | yes | — | Column definitions (id, title, textAlign?, widthPercentage?, customRender?). |
+| data | TableRow[] | yes | — | Array of row objects; keys should match column `id`s. |
+| variant | "default" \| "compact" | no | "default" | Visual variant. |
+| 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. |
+| onRowClick | (rowData: TableRow) => void | no | — | Called when a row is clicked; receives the row object. |
+| totalItems | number | no | 0 | Total item count for built-in Pagination; 0 or omitted hides pagination. |
+| totalLabel | string | no | "Items" | Label for the pagination total (e.g. "Items"). |
+| currentPage | number | no | 1 | Current 1-based page (controlled). |
+| rowsPerPage | number | no | 10 | Rows per page. |
+| rowsPerPageOptions | PaginationRowsPerPageOption[] | no | — | Options for rows-per-page select (same shape as Pagination). |
+| onPageChange | (page, rowsPerPage) => void | no | — | Called when page changes; receives (page, rowsPerPage). |
+| onRowsPerPageChange | (rowsPerPage: number) => void | no | — | Called when rows per page changes. |
+| hidePagination | boolean | no | false | If true, hides the built-in pagination bar even when totalItems > 0. |
+| mobileColumns | TableMobileColumns \| null | no | null | When set and viewport < 768px, rows render as MediaObjects; keys map row keys to title, description, media. |
+
+## Types
+
+### SpacingOption
+```typescript
+type SpacingOption = (typeof SPACING_OPTIONS)[number];
+```
+
+### TableVariant
+```typescript
+type TableVariant = "default" | "compact";
+```
+
+### TableMargin
+```typescript
+type TableMargin = string | SpacingOption[];
+```
+
+### TableColumnTextAlign
+```typescript
+type TableColumnTextAlign = "left" | "center" | "right";
+```
+
+### TableRow
+```typescript
+type TableRow = Record<string, unknown>;
+```
+
+### TableColumn
+```typescript
+interface TableColumn {
+  id: string;
+  title: string;
+  textAlign?: TableColumnTextAlign;
+  customRender?: (rowData: TableRow, column: TableColumn) => React.ReactNode;
+  widthPercentage?: string;
+}
+```
+
+### TableMobileColumns
+```typescript
+interface TableMobileColumns {
+  title: string;           // row key for MediaObject title
+  description?: string;    // row key for description
+  mediaAvatar?: string;    // row key for avatar value
+  mediaIcon?: string;      // static icon name for all rows
+  mediaImage?: string;     // static image URL
+  className?: string;
+  margin?: TableMargin;
+  padding?: string | SpacingOption[];
+}
+```
+
+### TableProps
+```typescript
+interface TableProps {
+  variant?: TableVariant;
+  margin?: TableMargin;
+  className?: string;
+  columns: TableColumn[];
+  data: TableRow[];
+  onRowClick?: (rowData: TableRow) => void;
+  totalItems?: number;
+  totalLabel?: string;
+  currentPage?: number;
+  rowsPerPage?: number;
+  rowsPerPageOptions?: PaginationRowsPerPageOption[];
+  onPageChange?: (page: number, rowsPerPage: number) => void;
+  onRowsPerPageChange?: (rowsPerPage: number) => void;
+  hidePagination?: boolean;
+  mobileColumns?: TableMobileColumns | null;
+}
+```
+
+## Usage Examples
+
+### Basic
+
+```jsx
+import { Table } from "cleanplate";
+
+const columns = [
+  { id: "name", title: "Name" },
+  { id: "email", title: "Email" },
+];
+
+const data = [
+  { name: "John Doe", email: "john@doe.com" },
+  { name: "Jane Doe", email: "jane@doe.com" },
+];
+
+<Table columns={columns} data={data} />
+```
+
+### With pagination
+
+```jsx
+import { Table } from "cleanplate";
+import { useState } from "react";
+
+const [currentPage, setCurrentPage] = useState(1);
+const [rowsPerPage, setRowsPerPage] = useState(10);
+
+<Table
+  columns={columns}
+  data={data}
+  totalItems={100}
+  currentPage={currentPage}
+  rowsPerPage={rowsPerPage}
+  onPageChange={(page) => setCurrentPage(page)}
+  onRowsPerPageChange={(rpp) => {
+    setRowsPerPage(rpp);
+    setCurrentPage(1);
+  }}
+/>
+```
+
+### Custom cell (customRender)
+
+```jsx
+const columns = [
+  { id: "name", title: "Name", widthPercentage: "50%" },
+  {
+    id: "status",
+    title: "Status",
+    textAlign: "right",
+    customRender: (rowData, column) => (
+      <Badge label={String(rowData.status)} variant="success" />
+    ),
+  },
+];
+<Table columns={columns} data={data} />;
+```
+
+### Mobile view (mobileColumns)
+
+```jsx
+<Table
+  columns={columns}
+  data={data}
+  mobileColumns={{
+    title: "name",
+    description: "email",
+    mediaAvatar: "avatarUrl",
+  }}
+/>
+```
+
+### Row click
+
+```jsx
+<Table
+  columns={columns}
+  data={data}
+  onRowClick={(rowData) => console.log(rowData)}
+/>
+```
+
+## Behavior Notes
+
+- **Required:** `columns` and `data` are required. Each column must have `id` and `title`; row keys should match `id` for default cell display.
+- **Pagination:** Built-in Pagination is shown when `totalItems` > 0 and `hidePagination` is false. Pass `onPageChange` and optionally `onRowsPerPageChange`; keep `currentPage` and `rowsPerPage` in parent state.
+- **Mobile:** When viewport width < 768px and `mobileColumns` is set, the table is replaced by a list of MediaObject items; `title` (and optionally `description`, `mediaAvatar`) are row keys whose values are passed to MediaObject.
+- **customRender:** Receives `(rowData, column)` and returns a React node; use for badges, buttons, or any custom cell content.
+- **Spacing:** `margin` uses the suffix API; the component adds the `m-` prefix via `getSpacingClass`.
+
+## Related Components / Links
+
+- Pagination (used inside Table when totalItems > 0 and hidePagination is false; same props as standalone Pagination)
+- MediaObject (used for mobile view when mobileColumns is set)
+- Typography, Container (used for headers and cells; Container often used in customRender with Badge)

package/docs/Toast.md

@@ -0,0 +1,96 @@
+# Toast Component
+
+Purpose: Displays transient messages in a portal (fixed top-right). Use a ref to call `addMessage({ mode, message })` imperatively. The parent does not manage toast state; the component handles rendering, stacking, and optional auto-close. Use for success/error feedback, notifications, or short-lived messages.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| autoClose | boolean | no | false | Whether toasts auto-close after autoCloseTime. |
+| autoCloseTime | number | no | 5000 | Duration in ms before auto-closing when autoClose is true. |
+
+## Imperative API
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| addMessage | (toast: ToastMessage) => void | Add a toast. toast has `mode` (info \| error \| warning \| success) and `message` (string). |
+
+## Types
+
+### ToastVariant
+```typescript
+type ToastVariant = "info" | "error" | "warning" | "success";
+```
+
+### ToastMessage
+```typescript
+interface ToastMessage {
+  mode: ToastVariant;
+  message: string;
+}
+```
+
+### ToastRefHandle
+```typescript
+interface ToastRefHandle {
+  addMessage: (toast: ToastMessage) => void;
+}
+```
+
+### ToastProps
+```typescript
+interface ToastProps {
+  autoClose?: boolean;
+  autoCloseTime?: number;
+}
+```
+
+## Usage Examples
+
+### Basic
+
+```jsx
+import { useRef } from "react";
+import { Toast, Button } from "cleanplate";
+
+const App = () => {
+  const toastRef = useRef(null);
+  const showToast = () => {
+    toastRef.current?.addMessage({ mode: "success", message: "Saved!" });
+  };
+  return (
+    <>
+      <Button onClick={showToast}>Save</Button>
+      <Toast ref={toastRef} />
+    </>
+  );
+};
+```
+
+### Variants
+
+```jsx
+toastRef.current?.addMessage({ mode: "info", message: "Info message" });
+toastRef.current?.addMessage({ mode: "error", message: "Error message" });
+toastRef.current?.addMessage({ mode: "warning", message: "Warning message" });
+toastRef.current?.addMessage({ mode: "success", message: "Success message" });
+```
+
+### With auto close
+
+```jsx
+<Toast ref={toastRef} autoClose autoCloseTime={5000} />
+```
+
+## Behavior Notes
+
+- **Imperative handle:** `forwardRef` + `useImperativeHandle` expose `addMessage` on the ref. The parent never manages a toast list.
+- **Portal:** Toasts render in a div prepended to `document.body`, fixed at top-right (16px).
+- **Icon:** Each mode maps to an icon via `getVariantIcon` (error → "error", success → "check_circle", info → "info").
+- **Click to dismiss:** Clicking a toast removes it.
+
+## Related Components / Links
+
+- Alert (inline feedback; use when the message should stay in the layout)
+- Button (commonly used to trigger toasts)
+- Container (layout around trigger buttons)