cleanplate 0.2.0 → 0.2.2

package/docs/Badge.md

@@ -0,0 +1,83 @@
+# Badge Component
+
+Purpose: Displays a short label with a colored background. Use it for status (e.g. success, error, warning), tags, or counts. Renders as an inline-block element with five variants (default, info, success, warning, error). Optional `className` for custom styling.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| label | string | no | — | Text shown inside the badge. |
+| variant | "default" \| "info" \| "warning" \| "error" \| "success" | no | "default" | Visual variant (gray, blue, orange, red, green). |
+| className | string | no | "" | Additional class names for the root element. |
+
+## Types
+
+### BadgeVariant
+```typescript
+type BadgeVariant = "default" | "info" | "warning" | "error" | "success";
+```
+
+### BadgeProps
+```typescript
+interface BadgeProps {
+  label?: string;
+  variant?: BadgeVariant;
+  className?: string;
+}
+```
+
+## Usage Examples
+
+### Basic
+
+```jsx
+import { Badge } from "cleanplate";
+
+<Badge label="New" />
+<Badge label="Active" variant="success" />
+```
+
+### Variants
+
+```jsx
+<Badge label="Default" variant="default" />
+<Badge label="Info" variant="info" />
+<Badge label="Success" variant="success" />
+<Badge label="Warning" variant="warning" />
+<Badge label="Error" variant="error" />
+```
+
+### With Table (customRender)
+
+```jsx
+import { Table, Badge } from "cleanplate";
+
+const columns = [
+  { id: "name", title: "Name" },
+  {
+    id: "status",
+    title: "Status",
+    customRender: (rowData, column) => (
+      <Badge label={String(rowData.status)} variant="success" />
+    ),
+  },
+];
+<Table columns={columns} data={data} />;
+```
+
+### Custom className
+
+```jsx
+<Badge label="Custom" variant="info" className="my-badge" />
+```
+
+## Behavior Notes
+
+- **Element:** Renders as a `<p>` with `display: inline-block` in styles.
+- **Label:** Optional; can be omitted or empty.
+- **Variants:** Each variant maps to a CSS class that sets background color via design tokens (e.g. `var(--blue)` for info, `var(--green)` for success).
+
+## Related Components / Links
+
+- Table (often use Badge in column `customRender` for status or tag columns)
+- Container (for layout when showing multiple badges)

package/docs/BottomSheet.md

@@ -0,0 +1,78 @@
+# BottomSheet Component
+
+Purpose: Slides up from the bottom of the screen. Use for additional content, forms, or actions without leaving the current context. Controlled by `isOpen` and `onClose`. Supports drag-to-close, snap points (30%, 60%, 90% of viewport), touch and mouse gestures, body scroll lock when open, and margin spacing.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| isOpen | boolean | yes | — | Whether the bottom sheet is open. |
+| onClose | () => void | no | — | Called when the user drags to close (past threshold). |
+| margin | string \| SpacingOption[] | no | — | Spacing suffix(s) for outer margin; component adds m- prefix. |
+| className | string | no | "" | Additional class names for the sheet panel. |
+| children | ReactNode | no | — | Content rendered inside the sheet. |
+
+## Types
+
+### BottomSheetMargin
+```typescript
+type BottomSheetMargin = string | SpacingOption[];
+```
+
+### BottomSheetProps
+```typescript
+interface BottomSheetProps {
+  isOpen: boolean;
+  onClose?: () => void;
+  margin?: BottomSheetMargin;
+  className?: string;
+  children?: React.ReactNode;
+}
+```
+
+## Usage Examples
+
+### Basic
+
+```jsx
+import { useState } from "react";
+import { BottomSheet, Button } from "cleanplate";
+
+const App = () => {
+  const [isOpen, setIsOpen] = useState(false);
+  return (
+    <>
+      <Button onClick={() => setIsOpen(true)}>Open</Button>
+      <BottomSheet isOpen={isOpen} onClose={() => setIsOpen(false)}>
+        <p>Content here</p>
+      </BottomSheet>
+    </>
+  );
+};
+```
+
+### With Container and Typography
+
+```jsx
+<BottomSheet isOpen={isOpen} onClose={handleClose}>
+  <Container padding="4">
+    <Typography variant="h5" margin="m-0 m-b-2">Title</Typography>
+    <Typography variant="p">Body text</Typography>
+  </Container>
+</BottomSheet>
+```
+
+## Behavior Notes
+
+- **isOpen / onClose:** Controlled visibility. `onClose` is called when the user drags past the close threshold.
+- **Snap points:** Sheet snaps to 30%, 60%, or 90% of viewport height.
+- **DOM:** Overlay div wrapping the sheet panel; handle area for drag; content area for children.
+- **Body overflow:** Set to `hidden` when open, restored on close or unmount.
+- **Margin:** Uses the suffix API (e.g. `"0"` → m-0).
+
+## Related Components / Links
+
+- Modal (full overlay dialog)
+- ConfirmDialog (simple confirmation overlay)
+- Button (commonly used to trigger opening)
+- Container, Typography (layout and content inside the sheet)

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)