cleanplate 0.1.10 → 0.2.0

package/docs/MediaObject.md

@@ -1,303 +0,0 @@
-# MediaObject Component
-
-Purpose: A flexible layout pattern that combines media (icon, image, or avatar) with content (title and description). Perfect for displaying user profiles, product cards, notifications, and any content that needs a media element alongside text.
-
-## Props / Inputs
-
-| Prop | Type | Required | Default | Description |
-| --- | --- | --- | --- | --- |
-| title | string | yes | — | The main title text displayed in the content area. |
-| mediaIcon | string | no | "" | Icon name from Material Symbols to display as the media element. |
-| mediaImage | string | no | "" | Image URL to display as the media element. |
-| mediaAvatar | string | no | "" | Name used to generate an avatar with initials and background color. |
-| description | string | no | — | Secondary text displayed below the title. |
-| margin | string \| string[] | no | "0" | Spacing utility token(s) for outer margin, such as `m-0` or `["m-1", "m-b-2"]`. |
-| padding | string \| string[] | no | "0" | Spacing utility token(s) for inner padding, such as `p-0` or `["p-1", "p-b-2"]`. |
-| className | string | no | "media-object" | Additional class names for the root element. |
-| onClick | function | no | — | Called with the click event when the media object is clicked. |
-| ...rest | React.HTMLAttributes<HTMLDivElement> | no | — | All other standard HTML div attributes are supported and passed through to the rendered element. |
-
-## Types
-
-### MediaObjectMargin
-```typescript
-type MediaObjectMargin = string | SpacingOption[];
-```
-
-### MediaObjectPadding
-```typescript
-type MediaObjectPadding = string | SpacingOption[];
-```
-
-### SpacingOption
-```typescript
-type SpacingOption = typeof SPACING_OPTIONS[number];
-```
-
-### MediaObjectProps
-```typescript
-interface MediaObjectProps extends React.HTMLAttributes<HTMLDivElement> {
-  mediaIcon?: string;
-  mediaImage?: string;
-  mediaAvatar?: string;
-  title: string;
-  description?: string;
-  margin?: MediaObjectMargin;
-  padding?: MediaObjectPadding;
-  className?: string;
-  onClick?: (e: React.MouseEvent<HTMLDivElement>) => void;
-}
-```
-
-## Usage Examples
-
-### With icon
-
-```jsx
-import { MediaObject } from "cleanplate";
-
-export const Example = () => (
-  <MediaObject
-    mediaIcon="person"
-    title="User Profile"
-    description="Manage your account settings and preferences"
-  />
-);
-```
-
-### With image
-
-```jsx
-import { MediaObject } from "cleanplate";
-
-export const Example = () => (
-  <MediaObject
-    mediaImage="https://example.com/avatar.jpg"
-    title="John Doe"
-    description="Senior Developer at Tech Corp"
-  />
-);
-```
-
-### With avatar (initials)
-
-```jsx
-import { MediaObject } from "cleanplate";
-
-export const Example = () => (
-  <MediaObject
-    mediaAvatar="John Doe"
-    title="John Doe"
-    description="Senior Developer with 5+ years of experience"
-  />
-);
-```
-
-### Title only
-
-```jsx
-import { MediaObject } from "cleanplate";
-
-export const Example = () => (
-  <MediaObject
-    mediaIcon="settings"
-    title="Settings"
-  />
-);
-```
-
-### With margin and padding
-
-```jsx
-import { MediaObject } from "cleanplate";
-
-export const Example = () => (
-  <>
-    <MediaObject
-      mediaIcon="star"
-      title="Featured Item"
-      description="This item has custom spacing"
-      margin="m-3"
-      padding="p-2"
-    />
-    <MediaObject
-      mediaIcon="heart"
-      title="Another Item"
-      description="With multiple margin tokens"
-      margin={["m-1", "m-b-3"]}
-      padding={["p-1", "p-x-2"]}
-    />
-  </>
-);
-```
-
-### Clickable media object
-
-```jsx
-import { MediaObject } from "cleanplate";
-
-export const Example = () => (
-  <MediaObject
-    mediaImage="https://example.com/product.jpg"
-    title="Wireless Headphones"
-    description="High-quality wireless headphones"
-    onClick={() => console.log("Media object clicked")}
-  />
-);
-```
-
-### User profile card
-
-```jsx
-import { MediaObject } from "cleanplate";
-import { Button } from "cleanplate";
-
-export const Example = () => (
-  <div style={{ 
-    border: "1px solid #e0e0e0", 
-    borderRadius: "8px",
-    padding: "16px"
-  }}>
-    <MediaObject
-      mediaImage="https://example.com/avatar.jpg"
-      title="John Doe"
-      description="Senior Developer • john.doe@example.com"
-    />
-    <Button variant="outline" size="small" margin="m-t-3">
-      Edit Profile
-    </Button>
-  </div>
-);
-```
-
-### Product card
-
-```jsx
-import { MediaObject } from "cleanplate";
-import { Typography } from "cleanplate";
-import { Button } from "cleanplate";
-
-export const Example = () => (
-  <div style={{ 
-    border: "1px solid #e0e0e0", 
-    borderRadius: "8px",
-    padding: "16px"
-  }}>
-    <MediaObject
-      mediaImage="https://example.com/product.jpg"
-      title="Wireless Headphones"
-      description="High-quality wireless headphones with noise cancellation"
-    />
-    <div style={{ marginTop: "12px", display: "flex", justifyContent: "space-between", alignItems: "center" }}>
-      <Typography variant="h5">$199.99</Typography>
-      <Button size="small" variant="outline">Add to Cart</Button>
-    </div>
-  </div>
-);
-```
-
-### Notification list
-
-```jsx
-import { MediaObject } from "cleanplate";
-
-export const Example = () => (
-  <div>
-    <MediaObject
-      mediaIcon="notifications"
-      title="New Message"
-      description="You have received a new message from Jane Smith"
-      margin="m-b-2"
-    />
-    <MediaObject
-      mediaIcon="schedule"
-      title="Meeting Reminder"
-      description="Team standup in 30 minutes"
-      margin="m-b-2"
-    />
-    <MediaObject
-      mediaIcon="done"
-      title="Task Completed"
-      description="Your project 'Website Redesign' has been updated"
-    />
-  </div>
-);
-```
-
-### Settings items
-
-```jsx
-import { MediaObject } from "cleanplate";
-
-export const Example = () => (
-  <div>
-    <MediaObject
-      mediaIcon="settings"
-      title="Account Settings"
-      description="Manage your account preferences and security settings"
-      margin="m-b-2"
-    />
-    <MediaObject
-      mediaIcon="lock"
-      title="Privacy & Security"
-      description="Control your privacy settings and security options"
-      margin="m-b-2"
-    />
-    <MediaObject
-      mediaIcon="notifications"
-      title="Notifications"
-      description="Configure how and when you receive notifications"
-    />
-  </div>
-);
-```
-
-### List of users
-
-```jsx
-import { MediaObject } from "cleanplate";
-
-export const Example = () => {
-  const users = [
-    { name: "John Doe", role: "Developer", avatar: "https://example.com/avatar1.jpg" },
-    { name: "Jane Smith", role: "Designer", avatar: "https://example.com/avatar2.jpg" },
-    { name: "Mike Johnson", role: "Manager", avatar: "https://example.com/avatar3.jpg" }
-  ];
-
-  return (
-    <div>
-      {users.map((user, index) => (
-        <MediaObject
-          key={index}
-          mediaImage={user.avatar}
-          title={user.name}
-          description={user.role}
-          margin={index < users.length - 1 ? "m-b-2" : "m-0"}
-        />
-      ))}
-    </div>
-  );
-};
-```
-
-## Behavior Notes
-
-- The `title` prop is required and will always be displayed in bold text.
-- The `description` prop is optional. If not provided, only the title will be displayed.
-- You can provide one of `mediaIcon`, `mediaImage`, or `mediaAvatar` to display the media element. If multiple are provided, the component will prioritize in this order: `mediaAvatar` > `mediaImage` > `mediaIcon`.
-- The component uses the `Avatar` component internally to render the media element, which supports icons, images, and generated avatars with initials.
-- The component uses the `Typography` component internally for the title and description text.
-- The title is rendered with `isBold={true}` by default.
-- The description is rendered with `variant="small"`.
-- The component renders as a `<div>` element with a flex layout structure.
-- Margin and padding spacing accept either a single string token (e.g., `"m-2"`) or an array of tokens (e.g., `["m-1", "m-b-3"]`).
-- The `onClick` handler makes the entire media object clickable, useful for interactive lists or cards.
-- All standard HTML div attributes can be passed through, allowing for custom `id`, `data-*`, `aria-*`, and other attributes.
-- The component is designed to be responsive and adapts to different screen sizes.
-
-## Related Components / Links
-
-- Avatar (used internally for the media element)
-- Typography (used internally for title and description)
-- Button (often used alongside MediaObject in cards)
-- Container (commonly used to wrap MediaObject components)

package/docs/Modal.md

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

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

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