cleanplate 0.1.11 → 0.2.1

package/docs/BreadCrumb.md

@@ -0,0 +1,133 @@
+# BreadCrumb Component
+
+Purpose: Renders a semantic navigation trail (e.g. Home → Products → Current page). Use it at the top of a page to show hierarchy and let users navigate back. The last item is treated as the current page when it has no `href`. Uses `<nav aria-label="Breadcrumb">` with an ordered list; includes Schema.org BreadcrumbList microdata for SEO.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| items | BreadCrumbItem[] | yes | — | List of breadcrumb items. Each has `label`; `href` is optional (omit for current page). |
+| separator | "slash" \| "chevron" | no | "chevron" | Visual separator between items (chevron icon or "/"). |
+| ariaLabel | string | no | "Breadcrumb" | Accessible label for the navigation landmark. |
+| margin | string \| string[] | no | — | 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 name for the root nav element. |
+
+## Types
+
+### BreadCrumbItem
+```typescript
+interface BreadCrumbItem {
+  label: string;   // Display label for the crumb
+  href?: string;   // URL for the crumb; omit for the current page (typically last item)
+}
+```
+
+### BreadCrumbSeparator
+```typescript
+type BreadCrumbSeparator = "slash" | "chevron";
+```
+
+### SpacingOption
+```typescript
+type SpacingOption = (typeof SPACING_OPTIONS)[number];
+```
+
+### BreadCrumbMargin
+```typescript
+type BreadCrumbMargin = string | SpacingOption[];
+```
+
+### BreadCrumbProps
+```typescript
+interface BreadCrumbProps {
+  items: BreadCrumbItem[];
+  separator?: BreadCrumbSeparator;
+  ariaLabel?: string;
+  margin?: BreadCrumbMargin;
+  className?: string;
+}
+```
+
+## Usage Examples
+
+### Basic
+
+```jsx
+import { BreadCrumb } from "cleanplate";
+
+const items = [
+  { label: "Home", href: "/" },
+  { label: "Products", href: "/products" },
+  { label: "Current Product" },
+];
+
+export const Example = () => <BreadCrumb items={items} />;
+```
+
+### Slash separator
+
+```jsx
+import { BreadCrumb } from "cleanplate";
+
+<BreadCrumb
+  items={[
+    { label: "Home", href: "/" },
+    { label: "Docs", href: "/docs" },
+    { label: "Getting started" },
+  ]}
+  separator="slash"
+/>
+```
+
+### Short trail
+
+```jsx
+<BreadCrumb
+  items={[
+    { label: "Home", href: "/" },
+    { label: "Current page" },
+  ]}
+/>
+```
+
+### With Container
+
+```jsx
+import { BreadCrumb, Container, Typography } from "cleanplate";
+
+<Container padding="4">
+  <BreadCrumb
+    items={[
+      { label: "Home", href: "/" },
+      { label: "Products", href: "/products" },
+      { label: "Current" },
+    ]}
+    margin="b-2"
+  />
+  <Typography variant="p">Page content below the breadcrumb.</Typography>
+</Container>
+```
+
+### Custom aria label
+
+```jsx
+<BreadCrumb
+  items={[{ label: "Home", href: "/" }, { label: "Here" }]}
+  ariaLabel="Page location"
+/>
+```
+
+## Behavior Notes
+
+- **Current page:** The last item in `items` with no `href` is rendered as the current page (non-link) with `aria-current="page"`. Items without `href` elsewhere in the list are rendered as plain text.
+- **Links:** Items with `href` are rendered as `<a href="...">` for navigation and accessibility.
+- **Semantic markup:** Root is `<nav aria-label={ariaLabel}>` with `<ol>` and `<li>`. Schema.org `BreadcrumbList` and `ListItem` (itemScope, itemType, itemProp) are applied for SEO.
+- **Separator:** Rendered with `aria-hidden="true"`. Chevron uses the Icon component (`chevron_right`); slash is the "/" character.
+- **Spacing:** `margin` accepts the **spacing suffix**; the component adds the `m-` prefix via `getSpacingClass`.
+
+## Related Components / Links
+
+- Container (layout and spacing around the breadcrumb)
+- Typography (page title or content below the breadcrumb)
+- Icon (used internally for the chevron separator)
+- Header (breadcrumbs are often placed inside or next to the header)

package/docs/Button.md

@@ -0,0 +1,189 @@
+# Button Component
+
+Purpose: A customizable action trigger for user interactions. Supports visual variants, size options, loading/disabled states, fluid layout, spacing utilities, and standard button behaviors.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| children | React.ReactNode | no | — | Content to display inside the button. |
+| isLoading | boolean | no | false | Shows a loading spinner and disables the button. |
+| isDisabled | boolean | no | false | Disables the button and prevents click events. |
+| isFluid | boolean | no | false | Makes the button take full width of its container. |
+| size | "small" \| "medium" | no | "medium" | Size variant of the button. |
+| variant | "solid" \| "outline" \| "ghost" \| "icon" | no | "solid" | Visual style variant of the button (`icon` is a style variant, not an icon prop). |
+| margin | string \| string[] | no | "m-0" | Spacing utility token(s), such as `m-0` or `["m-1", "m-b-2"]`. |
+| onClick | function | no | — | Called with the click event when button is clicked. Prevents execution if `isDisabled` or `isLoading` is true. |
+| className | string | no | "" | Additional class names for the root element. |
+| type | "button" \| "submit" \| "reset" | no | "button" | HTML button type attribute. |
+| ...rest | React.ButtonHTMLAttributes | no | — | All other standard HTML button attributes are supported. |
+
+## Types
+
+### ButtonSize
+```typescript
+type ButtonSize = "small" | "medium";
+```
+
+### ButtonVariant
+```typescript
+type ButtonVariant = "solid" | "outline" | "ghost" | "icon";
+```
+
+### ButtonMargin
+```typescript
+type ButtonMargin = string | SpacingOption[];
+```
+
+### SpacingOption
+```typescript
+type SpacingOption = typeof SPACING_OPTIONS[number];
+```
+
+### ButtonProps
+```typescript
+interface ButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type" | "onClick"> {
+  children?: React.ReactNode;
+  isLoading?: boolean;
+  isDisabled?: boolean;
+  isFluid?: boolean;
+  size?: ButtonSize;
+  variant?: ButtonVariant;
+  margin?: ButtonMargin;
+  onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
+  className?: string;
+  type?: "button" | "submit" | "reset";
+}
+```
+
+## Usage Examples
+
+### Basic button
+
+```jsx
+import { Button } from "cleanplate";
+
+export const Example = () => (
+  <Button onClick={() => console.log("Clicked")}>
+    Click me
+  </Button>
+);
+```
+
+### Variants
+
+```jsx
+import { Button } from "cleanplate";
+
+export const Example = () => (
+  <>
+    <Button variant="solid">Solid</Button>
+    <Button variant="outline">Outline</Button>
+    <Button variant="ghost">Ghost</Button>
+    <Button variant="icon">Icon</Button>
+  </>
+);
+```
+
+### Icon variant (icon-only action)
+
+```jsx
+import { Button, Icon } from "cleanplate";
+
+export const Example = () => (
+  <Button variant="icon" aria-label="Close dialog">
+    <Icon name="close" />
+  </Button>
+);
+```
+
+### Sizes
+
+```jsx
+import { Button } from "cleanplate";
+
+export const Example = () => (
+  <>
+    <Button size="small">Small</Button>
+    <Button size="medium">Medium</Button>
+  </>
+);
+```
+
+### Loading state
+
+```jsx
+import { Button } from "cleanplate";
+
+export const Example = () => (
+  <Button isLoading>
+    Loading...
+  </Button>
+);
+```
+
+### Disabled state
+
+```jsx
+import { Button } from "cleanplate";
+
+export const Example = () => (
+  <Button isDisabled>
+    Disabled
+  </Button>
+);
+```
+
+### Fluid button
+
+```jsx
+import { Button } from "cleanplate";
+
+export const Example = () => (
+  <Button isFluid>
+    Full Width Button
+  </Button>
+);
+```
+
+### With margin spacing
+
+```jsx
+import { Button } from "cleanplate";
+
+export const Example = () => (
+  <>
+    <Button margin="m-2">With margin</Button>
+    <Button margin={["m-1", "m-b-3"]}>With multiple margins</Button>
+  </>
+);
+```
+
+### Submit button
+
+```jsx
+import { Button } from "cleanplate";
+
+export const Example = () => (
+  <form onSubmit={(e) => { e.preventDefault(); console.log("Submitted"); }}>
+    <Button type="submit">Submit</Button>
+  </form>
+);
+```
+
+## Behavior Notes
+
+- When `isLoading` is true, an internal loading icon (`progress_activity`) is displayed and the button is automatically disabled.
+- When `isDisabled` is true, click events are prevented and the button appears visually disabled.
+- If both `isDisabled` and `isLoading` are true, the button is disabled and the loading icon is shown.
+- The `onClick` handler is not called if the button is disabled or loading, even if the event is triggered.
+- The button extends standard HTML button attributes, so you can use props like `aria-label`, `data-*`, etc.
+- The `type` prop defaults to `"button"` to prevent accidental form submissions. Use `type="submit"` for form submission buttons.
+- Margin spacing accepts either a single string token (e.g., `"m-2"`) or an array of tokens (e.g., `["m-1", "m-b-3"]`).
+- `variant="icon"` is a visual style variant. For icon-only buttons, pass an accessible name using `aria-label`.
+- In `size="medium"` + `variant="icon"`, styling uses compact horizontal padding and a 44px minimum width.
+
+## Related Components / Links
+
+- Icon (used internally for loading spinner)
+- FormControls (often used alongside buttons in forms)

package/docs/ConfirmDialog.md

@@ -0,0 +1,139 @@
+# ConfirmDialog Component
+
+Purpose: A modal dialog for confirmation actions (e.g. delete, discard, proceed). Shows a title, optional description, primary and secondary buttons, and optional close button. Use it for user confirmations, destructive actions, and warnings. Supports overlay click and Escape to close, body scroll lock when open, and focus management.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| isOpen | boolean | no | false | Whether the dialog is visible. |
+| onClose | () => void | no | — | Called when the dialog should close (close button, overlay, Escape, or after primary/secondary click). |
+| title | string | no | "Confirm Action" | Dialog title. |
+| description | string | no | "" | Optional description below the title. |
+| primaryButtonLabel | string | no | "Confirm" | Label for the primary (confirm) button. |
+| onPrimaryButtonClick | () => void | no | — | Called when the primary button is clicked; onClose is also called. |
+| secondaryButtonLabel | string | no | "Cancel" | Label for the secondary (cancel) button; empty string hides it. |
+| onSecondaryButtonClick | () => void | no | — | Called when the secondary button is clicked; onClose is also called. |
+| size | "small" \| "medium" \| "large" | no | "small" | Size of the dialog. |
+| variant | "default" \| "destructive" \| "warning" | no | "default" | Visual variant. |
+| showCloseButton | boolean | no | true | Whether to show the X close button. |
+| closeOnOverlayClick | boolean | no | true | Whether clicking the overlay closes the dialog. |
+| closeOnEscape | boolean | no | true | Whether pressing Escape closes the dialog. |
+| className | string | no | "" | Additional class names for the dialog panel. |
+| overlayClassName | string | no | "" | Additional class names for the overlay. |
+
+## Types
+
+### ConfirmDialogSize
+```typescript
+type ConfirmDialogSize = "small" | "medium" | "large";
+```
+
+### ConfirmDialogVariant
+```typescript
+type ConfirmDialogVariant = "default" | "destructive" | "warning";
+```
+
+### ConfirmDialogProps
+```typescript
+interface ConfirmDialogProps {
+  isOpen?: boolean;
+  onClose?: () => void;
+  title?: string;
+  description?: string;
+  primaryButtonLabel?: string;
+  onPrimaryButtonClick?: () => void;
+  secondaryButtonLabel?: string;
+  onSecondaryButtonClick?: () => void;
+  size?: ConfirmDialogSize;
+  variant?: ConfirmDialogVariant;
+  showCloseButton?: boolean;
+  closeOnOverlayClick?: boolean;
+  closeOnEscape?: boolean;
+  className?: string;
+  overlayClassName?: string;
+}
+```
+
+## Usage Examples
+
+### Basic
+
+```jsx
+import { ConfirmDialog, Button } from "cleanplate";
+import { useState } from "react";
+
+const App = () => {
+  const [isOpen, setIsOpen] = useState(false);
+  const handleConfirm = () => { /* ... */ setIsOpen(false); };
+  return (
+    <>
+      <Button onClick={() => setIsOpen(true)}>Delete</Button>
+      <ConfirmDialog
+        isOpen={isOpen}
+        onClose={() => setIsOpen(false)}
+        title="Delete Item"
+        description="Are you sure? This cannot be undone."
+        primaryButtonLabel="Delete"
+        onPrimaryButtonClick={handleConfirm}
+        secondaryButtonLabel="Cancel"
+      />
+    </>
+  );
+};
+```
+
+### Variants
+
+```jsx
+<ConfirmDialog variant="default" title="Save?" ... />
+<ConfirmDialog variant="destructive" title="Delete Account?" ... />
+<ConfirmDialog variant="warning" title="Proceed Anyway?" ... />
+```
+
+### Sizes
+
+```jsx
+<ConfirmDialog size="small" title="Quick confirm" ... />
+<ConfirmDialog size="medium" title="Standard confirm" ... />
+<ConfirmDialog size="large" title="Important decision" ... />
+```
+
+### No description, custom buttons
+
+```jsx
+<ConfirmDialog
+  isOpen={isOpen}
+  onClose={() => setIsOpen(false)}
+  title="Are you sure?"
+  primaryButtonLabel="Yes"
+  onPrimaryButtonClick={handleConfirm}
+  secondaryButtonLabel="No"
+/>
+```
+
+### Close behavior
+
+```jsx
+<ConfirmDialog
+  showCloseButton={true}
+  closeOnOverlayClick={true}
+  closeOnEscape={true}
+  onClose={handleClose}
+  ...
+/>
+```
+
+## 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, the overlay (if closeOnOverlayClick), Escape (if closeOnEscape), or either action button (after their handler runs).
+- **Body scroll:** When open, `document.body.style.overflow` is set to `"hidden"`; restored on close.
+- **Focus:** On open, focus moves to the dialog 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.
+
+## Related Components / Links
+
+- Button (used to open the dialog and for primary/secondary actions inside)
+- Typography (used for title and description)
+- Icon (used for the close button)

package/docs/Container.md

@@ -0,0 +1,230 @@
+# Container Component
+
+Purpose: A layout wrapper that controls display type, width, spacing (margin, padding, gap), and flex alignment. Use it to structure content, create flex layouts, and apply consistent spacing. Below the mobile breakpoint (600px), width variants collapse to full width for a responsive default. **Spacing (margin, padding, gap)** uses the **framework-wide suffix rule** (same for all CleanPlate components); see `llms.txt`.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| children | React.ReactNode | no | — | Content to render inside the container. |
+| margin | string \| string[] | no | "m-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: `"0"`, `["1", "b-2"]`. |
+| padding | string \| string[] | no | "p-4" | Spacing **suffix** for inner padding. The component adds the `p-` prefix (e.g. `"4"` → p-4, `"x-2"` → p-x-2). Use a single string or array: `"4"`, `["2", "x-4"]`. |
+| display | "block" \| "flex" \| "inline-block" \| "" | no | "" | Layout mode. Use `"flex"` for flexbox; leave empty for no display class. |
+| align | "start" \| "center" \| "end" \| "" | no | "" | Flex align-items. Only applies when `display="flex"`. |
+| justify | "space-between" \| "center" \| "space-around" \| "space-evenly" \| "flex-end" \| "flex-start" \| "" | no | "" | Flex justify-content. Only applies when `display="flex"`. |
+| width | "small" \| "medium" \| "large" \| "extra-large" \| "quarter" \| "half" \| "three-quarters" \| "full" \| "" | no | "" | Width variant. At viewports ≤600px, all variants become full width. |
+| gap | string \| string[] | no | "4" | Spacing **suffix** for gap between flex children. The component adds the `g-` prefix (e.g. `"4"` → g-4). Meaningful when `display="flex"`. Use `"4"` or `["2", "3"]` for multiple. |
+| showBorder | boolean | no | false | When true, shows a border around the container. |
+| className | string | no | "" | Additional class names for the root element. |
+| onClick | function | no | — | Click handler for the root div. |
+| style | React.CSSProperties | no | — | Inline styles for the root element. |
+| ...rest | React.HTMLAttributes<HTMLDivElement> | no | — | Any other div attributes (e.g. `id`, `data-*`, `aria-*`) are forwarded. |
+
+## Types
+
+### SpacingOption
+```typescript
+type SpacingOption = (typeof SPACING_OPTIONS)[number];
+```
+
+### ContainerDisplay
+```typescript
+type ContainerDisplay = "inline-block" | "block" | "flex";
+```
+
+### ContainerWidth
+```typescript
+type ContainerWidth =
+  | "small"
+  | "medium"
+  | "large"
+  | "extra-large"
+  | "quarter"
+  | "half"
+  | "three-quarters"
+  | "full";
+```
+
+### ContainerJustify
+```typescript
+type ContainerJustify =
+  | "space-between"
+  | "center"
+  | "space-around"
+  | "space-evenly"
+  | "flex-end"
+  | "flex-start";
+```
+
+### ContainerAlign
+```typescript
+type ContainerAlign = "start" | "center" | "end";
+```
+
+### ContainerSpacing
+```typescript
+type ContainerSpacing = string | SpacingOption[];
+```
+
+### ContainerProps
+```typescript
+interface ContainerProps extends React.HTMLAttributes<HTMLDivElement> {
+  children?: React.ReactNode;
+  margin?: ContainerSpacing;
+  padding?: ContainerSpacing;
+  display?: ContainerDisplay | "";
+  align?: ContainerAlign | "";
+  justify?: ContainerJustify | "";
+  width?: ContainerWidth | "";
+  showBorder?: boolean;
+  className?: string;
+  onClick?: (e: React.MouseEvent<HTMLDivElement>) => void;
+  style?: React.CSSProperties;
+  gap?: ContainerSpacing;
+}
+```
+
+## Usage Examples
+
+### Block container
+
+```jsx
+import { Container } from "cleanplate";
+
+export const Example = () => (
+  <Container display="block" padding="4" showBorder>
+    <p>Block container: full width, content stacks vertically.</p>
+  </Container>
+);
+```
+
+### Flex container with alignment
+
+```jsx
+import { Container } from "cleanplate";
+import { Button } from "cleanplate";
+
+export const Example = () => (
+  <Container
+    display="flex"
+    justify="space-between"
+    align="center"
+    padding="3"
+    gap="2"
+    showBorder
+  >
+    <span>Left</span>
+    <Button size="small">Action</Button>
+  </Container>
+);
+```
+
+### Width variants
+
+```jsx
+import { Container } from "cleanplate";
+
+export const Example = () => (
+  <>
+    <Container width="small" showBorder padding="3">Small</Container>
+    <Container width="medium" showBorder padding="3">Medium</Container>
+    <Container width="half" showBorder padding="3">Half</Container>
+    <Container width="full" showBorder padding="3">Full</Container>
+  </>
+);
+```
+
+### Inline-block (side by side)
+
+```jsx
+import { Container } from "cleanplate";
+
+export const Example = () => (
+  <Container display="inline-block" showBorder padding="2" margin="r-2">
+    Block 1
+  </Container>
+  <Container display="inline-block" showBorder padding="2">
+    Block 2
+  </Container>
+);
+```
+
+### Margin and padding
+
+```jsx
+import { Container } from "cleanplate";
+
+export const Example = () => (
+  <>
+    <Container margin="2" padding="4" showBorder>
+      Single suffix values
+    </Container>
+    <Container margin={["1", "b-3"]} padding={["2", "x-4"]} showBorder>
+      Multiple suffixes (component adds m- / p- prefix)
+    </Container>
+  </>
+);
+```
+
+### Flex grid (quarters)
+
+```jsx
+import { Container } from "cleanplate";
+
+export const Example = () => (
+  <Container display="flex" padding="2" gap="2" showBorder>
+    <Container width="quarter" showBorder padding="3">1</Container>
+    <Container width="quarter" showBorder padding="3">2</Container>
+    <Container width="quarter" showBorder padding="3">3</Container>
+    <Container width="quarter" showBorder padding="3">4</Container>
+  </Container>
+);
+```
+
+### Clickable container
+
+```jsx
+import { Container } from "cleanplate";
+
+export const Example = () => (
+  <Container
+    showBorder
+    padding="4"
+    onClick={() => console.log("Clicked")}
+  >
+    Clickable area
+  </Container>
+);
+```
+
+### With custom class and style
+
+```jsx
+import { Container } from "cleanplate";
+
+export const Example = () => (
+  <Container
+    className="my-wrapper"
+    style={{ minHeight: 200 }}
+    padding="4"
+    showBorder
+  >
+    Custom wrapper
+  </Container>
+);
+```
+
+## Behavior Notes
+
+- **Responsive width:** For viewport width ≤600px (mobile breakpoint), all `width` variants are overridden to `100%` in CSS. No prop change is required.
+- **Flex:** When `display="flex"`, the root uses `display: flex` and `flex-wrap: wrap`. Use `align` and `justify` to control alignment; use `gap` for spacing between children.
+- **Spacing:** `margin`, `padding`, and `gap` accept the **spacing suffix** (the component adds the `m-`, `p-`, or `g-` prefix via `getSpacingClass`). Use a single string (e.g. `"4"`, `"0"`, `"b-2"`) or an array of suffixes (e.g. `["1", "b-2"]`). Valid suffixes include `"0"`–`"9"`, `"auto"`, and directional forms like `"x-2"`, `"y-3"`, `"t-0"`, `"r-1"`, `"b-2"`, `"l-3"` (see `SPACING_OPTIONS`). **Note:** The component’s default props are currently `"m-0"` and `"p-4"` (full tokens); internally the util expects suffixes, so when passing values explicitly use suffix form (e.g. `"0"`, `"4"`).
+- **Empty layout props:** Passing `""` or omitting `display`, `align`, `justify`, or `width` means no corresponding class is applied.
+- **Border:** `showBorder` only affects border visibility; the container always reserves border space (border is 1px solid, transparent when not shown).
+- The root element is a `div`; all standard HTML div attributes and ref are supported via `...rest`.
+
+## Related Components / Links
+
+- Typography (often used inside Container for text)
+- Button (commonly placed inside flex Containers)
+- MediaObject (often wrapped in Container for layout)