cleanplate 0.1.10 → 0.2.0

package/docs/Avatar.md

@@ -1,130 +0,0 @@
-# Avatar Component
-
-Purpose: Displays user initials, an image, or a Material icon in a consistent circle. Use it for user identity in headers, lists, MediaObject, or anywhere you need a compact avatar. Supports sizes, spacing (margin), and optional click handling.
-
-## Props / Inputs
-
-| Prop | Type | Required | Default | Description |
-| --- | --- | --- | --- | --- |
-| name | string | no | "" | Display name; used for initials and `title` when no image/icon. Also used for image `alt` and for generating background color when showing initials. |
-| image | string | no | "" | Image URL; when set, shows image instead of initials or icon. |
-| icon | MaterialIconName | no | — | Material icon name; when set (and no image), shows icon instead of initials. |
-| size | "small" \| "medium" | no | "medium" | Size of the avatar. |
-| 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"`, `["2", "b-3"]`. |
-| onClick | function | no | — | Click handler for the root div. |
-| className | string | no | "" | Additional class names for the root element. |
-| ...rest | React.HTMLAttributes<HTMLDivElement> | no | — | Any other div attributes (e.g. `id`, `data-*`, `aria-*`, `style`) are forwarded. |
-
-## Types
-
-### SpacingOption
-```typescript
-type SpacingOption = (typeof SPACING_OPTIONS)[number];
-```
-
-### AvatarSize
-```typescript
-type AvatarSize = "small" | "medium";
-```
-
-### AvatarMargin
-```typescript
-type AvatarMargin = string | SpacingOption[];
-```
-
-### AvatarProps
-```typescript
-interface AvatarProps extends React.HTMLAttributes<HTMLDivElement> {
-  name?: string;
-  image?: string;
-  icon?: MaterialIconName;  // from "../icon/material-icon-names"
-  size?: AvatarSize;
-  margin?: AvatarMargin;
-  onClick?: (e: React.MouseEvent<HTMLDivElement>) => void;
-  className?: string;
-}
-```
-
-## Usage Examples
-
-### Name (initials)
-
-```jsx
-import { Avatar } from "cleanplate";
-
-export const Example = () => (
-  <>
-    <Avatar name="John Doe" size="medium" />
-    <Avatar name="Jane Smith" size="small" margin="2" />
-  </>
-);
-```
-
-### Icon
-
-```jsx
-import { Avatar } from "cleanplate";
-
-export const Example = () => (
-  <>
-    <Avatar icon="person" size="medium" />
-    <Avatar icon="account_circle" size="small" />
-  </>
-);
-```
-
-### Image
-
-```jsx
-import { Avatar } from "cleanplate";
-
-export const Example = () => (
-  <Avatar
-    name="John Doe"
-    image="https://example.com/photo.jpg"
-    size="medium"
-  />
-);
-```
-
-### Clickable avatar
-
-```jsx
-import { Avatar } from "cleanplate";
-
-export const Example = () => (
-  <Avatar
-    name="John Doe"
-    size="medium"
-    onClick={() => console.log("Avatar clicked")}
-  />
-);
-```
-
-### With Container
-
-```jsx
-import { Avatar, Container } from "cleanplate";
-
-export const Example = () => (
-  <Container display="flex" gap="2" align="center">
-    <Avatar name="Alice" size="small" margin="0" />
-    <Avatar icon="person" size="medium" margin="0" />
-    <Avatar image="https://example.com/bob.jpg" name="Bob" size="medium" margin="0" />
-  </Container>
-);
-```
-
-## Behavior Notes
-
-- **Display priority:** If `image` is set, the image is shown. Else if `icon` is set, the Material icon is shown. Otherwise initials from `name` are shown.
-- **Initials:** Derived from the first letter of each word in `name` (up to 2 characters), e.g. "John Doe" → "JD".
-- **Background color:** When showing initials, background color is generated deterministically from `name` (hash-based).
-- **Spacing:** `margin` accepts the **spacing suffix**; the component adds the `m-` prefix via `getSpacingClass`. Use suffix form (e.g. `"0"`, `"2"`, `"b-3"`) when passing values explicitly.
-- **Root element:** A `div`; all standard HTML div attributes and ref are supported via `...rest`.
-
-## Related Components / Links
-
-- MediaObject (often uses Avatar via `mediaAvatar` for the media slot)
-- Container (layout and spacing around avatars)
-- Icon (Avatar can show an icon via the `icon` prop; uses Material icon names)

package/docs/Badge.md

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

@@ -1,175 +0,0 @@
-# Button Component
-
-Purpose: A highly customizable and interactive UI element designed to handle user actions with various styles, sizes, and variants. Supports loading states, disabled states, and click events.
-
-## 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. |
-| 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>
-  </>
-);
-```
-
-### 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, a progress spinner icon 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 spinner 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"]`).
-
-## Related Components / Links
-
-- Icon (used internally for loading spinner)
-- FormControls (often used alongside buttons in forms)

package/docs/ConfirmDialog.md

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