cleanplate 0.1.11 → 0.2.1

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)

package/docs/Typography.md

@@ -0,0 +1,231 @@
+# Typography Component
+
+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.
+
+**For AI / LLM:** Prefer component props over inline `style`. Use `align="center"` for text alignment (not `style={{ textAlign: "center" }}`). For spacing, use the `margin` prop with the **framework-wide spacing suffix rule** (same for all CleanPlate components): pass suffix only (e.g. `margin="b-2"`), not `style={{ marginBottom }}` and not `"m-0"` or `"m-b-2"` — the component adds the `m-` prefix. See `llms.txt` for the full spacing rule.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| children | React.ReactNode | no | — | Text content to display. |
+| variant | "h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6" \| "p" \| "span" \| "small" | no | "p" | HTML element type to render. Determines the semantic meaning and default styling. |
+| margin | string \| string[] | no | "m-0" | Spacing **suffix** only (same rule as all components). Component adds `m-` prefix. E.g. `"0"`, `"b-2"`, `["1", "b-3"]`. Do not pass `"m-0"`. |
+| className | string | no | "" | Additional class names for the root element. |
+| isBold | boolean | no | false | Applies bold font weight to the text. |
+| align | "left" \| "center" \| "right" | no | "left" | Text alignment within its container. |
+| wordBreak | "normal" \| "all" \| "wrap" | no | "normal" | Controls how words break when text overflows. |
+| ...rest | any | no | — | All other standard HTML attributes are supported and passed through to the rendered element. |
+
+## Types
+
+### TypographyVariant
+```typescript
+type TypographyVariant = "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "p" | "span" | "small";
+```
+
+### TypographyAlign
+```typescript
+type TypographyAlign = "left" | "right" | "center";
+```
+
+### TypographyWordBreak
+```typescript
+type TypographyWordBreak = "normal" | "all" | "wrap";
+```
+
+### TypographyMargin
+```typescript
+type TypographyMargin = string | SpacingOption[];
+```
+
+### SpacingOption
+```typescript
+type SpacingOption = typeof SPACING_OPTIONS[number];
+```
+
+### TypographyProps
+```typescript
+interface TypographyProps {
+  children?: React.ReactNode;
+  variant?: TypographyVariant;
+  margin?: TypographyMargin;
+  className?: string;
+  isBold?: boolean;
+  align?: TypographyAlign;
+  wordBreak?: TypographyWordBreak;
+  [key: string]: any; // Allow other HTML attributes to be passed through
+}
+```
+
+## Usage Examples
+
+### Headings
+
+```jsx
+import { Typography } from "cleanplate";
+
+export const Example = () => (
+  <>
+    <Typography variant="h1">Heading 1</Typography>
+    <Typography variant="h2">Heading 2</Typography>
+    <Typography variant="h3">Heading 3</Typography>
+    <Typography variant="h4">Heading 4</Typography>
+    <Typography variant="h5">Heading 5</Typography>
+    <Typography variant="h6">Heading 6</Typography>
+  </>
+);
+```
+
+### Paragraph (default)
+
+```jsx
+import { Typography } from "cleanplate";
+
+export const Example = () => (
+  <Typography>
+    This is a paragraph. When no variant is specified, it defaults to a paragraph element.
+  </Typography>
+);
+```
+
+### Small text
+
+```jsx
+import { Typography } from "cleanplate";
+
+export const Example = () => (
+  <Typography variant="small">
+    This is small text, typically used for captions or fine print.
+  </Typography>
+);
+```
+
+### Inline span
+
+```jsx
+import { Typography } from "cleanplate";
+
+export const Example = () => (
+  <Typography variant="span">
+    This text is rendered as an inline span element.
+  </Typography>
+);
+```
+
+### Text alignment
+
+```jsx
+import { Typography } from "cleanplate";
+
+export const Example = () => (
+  <>
+    <Typography align="left">Left aligned text</Typography>
+    <Typography align="center">Center aligned text</Typography>
+    <Typography align="right">Right aligned text</Typography>
+  </>
+);
+```
+
+### Bold text
+
+```jsx
+import { Typography } from "cleanplate";
+
+export const Example = () => (
+  <>
+    <Typography>Normal weight text</Typography>
+    <Typography isBold>Bold text</Typography>
+  </>
+);
+```
+
+### Word breaking
+
+```jsx
+import { Typography } from "cleanplate";
+
+export const Example = () => (
+  <>
+    <Typography wordBreak="normal">
+      Normal word breaking behavior
+    </Typography>
+    <Typography wordBreak="all">
+      Break words at any point if needed
+    </Typography>
+    <Typography wordBreak="wrap">
+      Wrap text with word breaking
+    </Typography>
+  </>
+);
+```
+
+### With margin spacing (suffix only)
+
+Use the spacing **suffix**; the component adds the `m-` prefix. E.g. `"2"` → m-2, `"b-2"` → m-b-2.
+
+```jsx
+import { Typography } from "cleanplate";
+
+export const Example = () => (
+  <>
+    <Typography variant="h1" margin="2">
+      Heading with margin
+    </Typography>
+    <Typography margin={["1", "b-3"]}>
+      Paragraph with multiple margins
+    </Typography>
+  </>
+);
+```
+
+### Combined properties (prefer props over style)
+
+```jsx
+import { Typography } from "cleanplate";
+
+export const Example = () => (
+  <Typography
+    variant="h2"
+    isBold
+    align="center"
+    margin="4"
+  >
+    Centered, bold heading with margin
+  </Typography>
+);
+```
+
+### With HTML attributes
+
+```jsx
+import { Typography } from "cleanplate";
+
+export const Example = () => (
+  <Typography
+    variant="p"
+    id="description"
+    data-testid="typography-description"
+    aria-label="Product description"
+  >
+    This paragraph has additional HTML attributes.
+  </Typography>
+);
+```
+
+## Behavior Notes
+
+- When no `variant` is specified, the component defaults to rendering a `<p>` (paragraph) element.
+- The `variant` prop determines both the HTML element type (h1, h2, p, etc.) and the default styling applied.
+- The component uses semantic HTML elements, which is important for accessibility and SEO.
+- All standard HTML attributes can be passed through via the spread operator (`...rest`), allowing for custom `id`, `data-*`, `aria-*`, and other attributes.
+- **Use props, not inline style:** Use `align` for text alignment (e.g. `align="center"`), and `margin` for spacing. Do not use `style={{ textAlign, marginBottom }}` for these.
+- The `align` prop controls text alignment using CSS classes. Values: `"left"`, `"center"`, `"right"`.
+- The `wordBreak` prop provides control over how text wraps when it exceeds container width.
+- **Margin uses the framework-wide spacing rule (all components):** Pass suffix only: `"0"`, `"2"`, `"b-2"`, `["1", "b-3"]` etc. The component adds the `m-` prefix. Do not pass `"m-2"` or `"m-b-2"`.
+- The `isBold` prop applies bold font weight, which can be combined with any variant.
+
+## Related Components / Links
+
+- Container (often used to wrap typography content)
+- MediaObject (commonly uses Typography for text content)