cleanplate 0.1.10 → 0.2.0

package/docs/Spinner.md

@@ -1,115 +0,0 @@
-# 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

@@ -1,131 +0,0 @@
-# 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

@@ -1,194 +0,0 @@
-# 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/Typography.md

@@ -1,226 +0,0 @@
-# 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.
-
-## 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 utility token(s), such as `m-0` or `["m-1", "m-b-2"]`. |
-| 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
-
-```jsx
-import { Typography } from "cleanplate";
-
-export const Example = () => (
-  <>
-    <Typography variant="h1" margin="m-2">
-      Heading with margin
-    </Typography>
-    <Typography margin={["m-1", "m-b-3"]}>
-      Paragraph with multiple margins
-    </Typography>
-  </>
-);
-```
-
-### Combined properties
-
-```jsx
-import { Typography } from "cleanplate";
-
-export const Example = () => (
-  <Typography
-    variant="h2"
-    isBold
-    align="center"
-    margin="m-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.
-- The `align` prop controls text alignment using CSS classes, not inline styles.
-- The `wordBreak` prop provides control over how text wraps when it exceeds container width.
-- Margin spacing accepts either a single string token (e.g., `"m-2"`) or an array of tokens (e.g., `["m-1", "m-b-3"]`).
-- 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)