cleanplate 0.1.11 → 0.2.1

package/docs/Alert.md

@@ -0,0 +1,131 @@
+# Alert Component
+
+Purpose: Displays a short message with an optional variant icon and dismiss button. Use it for inline feedback (success, error, warning, info) or neutral notices. When dismissed, the alert unmounts (returns null). **Margin** uses the **framework-wide spacing suffix rule** (same for all components); see `llms.txt`.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| message | string | no | — | Main message text shown in the alert. |
+| size | "small" \| "medium" \| "large" | no | "medium" | Size of the alert and its icon/close button. |
+| variant | "success" \| "error" \| "warning" \| "info" \| "default" | no | "info" | Visual variant; each has a matching icon (e.g. success → check_circle, error → error). |
+| canDismiss | boolean | no | false | When true, shows a close button that calls onDismiss and unmounts the alert. |
+| onDismiss | function | no | — | Called when the user dismisses the alert (clicks the close button). |
+| 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: `"0"`, `["b-2"]`. |
+
+## Types
+
+### AlertSize
+```typescript
+type AlertSize = "small" | "medium" | "large";
+```
+
+### AlertVariant
+```typescript
+type AlertVariant = "success" | "error" | "warning" | "info" | "default";
+```
+
+### SpacingOption
+```typescript
+type SpacingOption = (typeof SPACING_OPTIONS)[number];
+```
+
+### AlertMargin
+```typescript
+type AlertMargin = string | SpacingOption[];
+```
+
+### AlertProps
+```typescript
+interface AlertProps {
+  message?: string;
+  size?: AlertSize;
+  variant?: AlertVariant;
+  canDismiss?: boolean;
+  onDismiss?: () => void;
+  margin?: AlertMargin;
+}
+```
+
+## Usage Examples
+
+### Basic
+
+```jsx
+import { Alert } from "cleanplate";
+
+export const Example = () => (
+  <Alert message="Your changes were saved." variant="success" />
+);
+```
+
+### Variants
+
+```jsx
+import { Alert } from "cleanplate";
+
+export const Example = () => (
+  <>
+    <Alert message="Default message" variant="default" margin="b-2" />
+    <Alert message="Info message" variant="info" margin="b-2" />
+    <Alert message="Warning message" variant="warning" margin="b-2" />
+    <Alert message="Error message" variant="error" margin="b-2" />
+    <Alert message="Success message" variant="success" />
+  </>
+);
+```
+
+### Sizes
+
+```jsx
+import { Alert } from "cleanplate";
+
+export const Example = () => (
+  <>
+    <Alert message="Small alert" variant="info" size="small" margin="b-2" />
+    <Alert message="Medium alert" variant="info" size="medium" margin="b-2" />
+    <Alert message="Large alert" variant="info" size="large" />
+  </>
+);
+```
+
+### Dismissible
+
+```jsx
+import { Alert } from "cleanplate";
+
+export const Example = () => (
+  <Alert
+    message="This can be dismissed."
+    variant="info"
+    canDismiss
+    onDismiss={() => console.log("Dismissed")}
+  />
+);
+```
+
+### With Container
+
+```jsx
+import { Alert, Container } from "cleanplate";
+
+export const Example = () => (
+  <Container padding="4">
+    <Alert message="Alert inside a container" variant="warning" margin="b-2" />
+  </Container>
+);
+```
+
+## Behavior Notes
+
+- **Icon:** Each variant maps to an icon via `getVariantIcon` (e.g. error → "error", success → "check_circle", info → "info", warning → "warning", default → "info").
+- **Dismiss:** When `canDismiss` is true, a close button is shown. Clicking it sets internal visibility to false, calls `onDismiss`, and the component returns `null` (removed from the tree).
+- **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.
+- **Root element:** A `div`; Alert does not extend HTML attributes, so only the documented props are supported.
+
+## Related Components / Links
+
+- Typography (used internally for the message text)
+- Container (layout and spacing around alerts)
+- Button (used internally for the dismiss button when canDismiss is true)
+- Icon (used for the variant icon and the close icon)

package/docs/Animated.md

@@ -0,0 +1,101 @@
+# Animated Component
+
+Purpose: Atom that adds scroll-triggered entrance (or exit) animations to any content. Uses IntersectionObserver to detect when the element enters the viewport, then applies a CSS animation class. Use it to animate headings, cards, avatars, or any wrapper content as the user scrolls. Supports polymorphic `as`, delay for staggering, and margin (suffix API).
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| animationType | AnimationType | no | "fade-in-bottom" | Animation when in view: fade-in-top, fade-in-right, fade-in-bottom, fade-in-left, fade-out-top, fade-out-right, fade-out-bottom, fade-out-left. |
+| as | React.ElementType | no | "span" | Root element or component to render. |
+| margin | string \| SpacingOption[] | no | ["0"] | Margin spacing. Suffix or array of spacing suffixes; component adds `m-` prefix. |
+| delay | number | no | 0 | Delay in ms; maps to class `delay-{delay}` (e.g. 200 → delay-200) for staggered animations. |
+| className | string | no | "" | Additional class names for the root element. |
+| isBlock | boolean | no | false | If true, applies block display. |
+| ...rest | React.HTMLAttributes<HTMLElement> | no | — | Any other HTML attributes forwarded to the root element. |
+
+## Types
+
+### SpacingOption
+```typescript
+type SpacingOption = (typeof SPACING_OPTIONS)[number];
+```
+
+### AnimatedMargin
+```typescript
+type AnimatedMargin = string | SpacingOption[];
+```
+
+### AnimationType
+```typescript
+type AnimationType = (typeof ANIMATION_TYPE_OPTIONS)[number];
+// "fade-in-top" | "fade-in-right" | "fade-in-bottom" | "fade-in-left" |
+// "fade-out-top" | "fade-out-right" | "fade-out-bottom" | "fade-out-left"
+```
+
+### AnimationDelay
+```typescript
+type AnimationDelay = (typeof ANIMATION_DELAY_OPTIONS)[number];
+// number (e.g. 100, 200, ... 3000)
+```
+
+### AnimatedProps
+```typescript
+interface AnimatedProps extends Omit<React.HTMLAttributes<HTMLElement>, "className"> {
+  animationType?: AnimationType;
+  as?: React.ElementType;
+  margin?: AnimatedMargin;
+  delay?: number;
+  className?: string;
+  isBlock?: boolean;
+}
+```
+
+## Usage Examples
+
+### Basic
+
+```jsx
+import { Animated } from "cleanplate";
+
+<Animated animationType="fade-in-bottom">
+  <h2>Animates when in view</h2>
+</Animated>
+```
+
+### Staggered delay
+
+```jsx
+<Animated animationType="fade-in-bottom">First</Animated>
+<Animated animationType="fade-in-bottom" delay={200}>Second</Animated>
+<Animated animationType="fade-in-bottom" delay={400}>Third</Animated>
+```
+
+### With `as` and isBlock
+
+```jsx
+<Animated as="div" isBlock animationType="fade-in-bottom">
+  <section>Block-level content</section>
+</Animated>
+```
+
+### Animation types
+
+```jsx
+<Animated animationType="fade-in-top">Content</Animated>
+<Animated animationType="fade-in-bottom">Content</Animated>
+<Animated animationType="fade-in-left">Content</Animated>
+<Animated animationType="fade-in-right">Content</Animated>
+```
+
+## Behavior Notes
+
+- **IntersectionObserver:** The root element is observed on mount. When it intersects the viewport, the animation class is applied and the observer unobserves it (one-shot per mount).
+- **Delay:** The `delay` value is used to build a class name `delay-{delay}`. Styles must define the corresponding `animation-delay` for that class (e.g. `.delay-200 { animation-delay: 200ms; }`).
+- **Spacing:** `margin` uses the suffix API; the component adds the `m-` prefix via `getSpacingClass`.
+
+## Related Components / Links
+
+- Container (layout around animated content)
+- Typography, Avatar, Badge, Button (common content wrapped by Animated)
+- Header, BottomSheet, MenuList (use Animated internally)

package/docs/AppShell.md

@@ -0,0 +1,145 @@
+# AppShell Component
+
+Purpose: Full-page layout that combines an optional Header (top), optional Footer (bottom), and an optional MenuList as a left sidebar, with main content in the center. Use for dashboard-style apps where the sidebar holds primary navigation and the header holds logo and utilities (e.g. user menu). Sidebar is hidden below 1024px; pass the same menu items to the header for the header’s mobile menu.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| children | ReactNode | yes | — | Main content (page area). |
+| header | ReactNode \| HeaderProps | no | — | Top bar: pass Header props object or custom ReactNode. Omit to hide header. |
+| footer | ReactNode \| FooterProps | no | — | Bottom bar: pass Footer props object or custom ReactNode. Omit to hide footer. |
+| sidebar | AppShellSidebarConfig | no | — | Sidebar config (MenuList as vertical nav on the left). Omit to hide sidebar. |
+| sidebarWidth | string | no | "240px" | Width of the sidebar (e.g. "240px", "16rem"). |
+| className | string | no | "" | Additional class name for the root element. |
+| contentClassName | string | no | "" | Additional class name for the main content wrapper. |
+
+## Types
+
+### AppShellSidebarConfig
+```typescript
+interface AppShellSidebarConfig {
+  items: MenuListItem[];      // Menu items for the sidebar
+  activeItem?: string;        // Value of the currently active item
+  onMenuClick?: (item: MenuListItem) => void;
+  size?: MenuListSize;        // small | medium | large
+  variant?: MenuListVariant;  // light | dark
+}
+```
+
+### AppShellProps
+```typescript
+interface AppShellProps {
+  children: React.ReactNode;
+  header?: React.ReactNode | HeaderProps;
+  footer?: React.ReactNode | FooterProps;
+  sidebar?: AppShellSidebarConfig;
+  sidebarWidth?: string;
+  className?: string;
+  contentClassName?: string;
+}
+```
+
+## Usage Examples
+
+### Full dashboard (sidebar + header + footer)
+
+```jsx
+import { useState } from "react";
+import { AppShell, Container, Typography, Avatar } from "cleanplate";
+
+const MENU_ITEMS = [
+  { label: "Dashboard", value: "/", icon: "speed" },
+  { label: "Settings", value: "/settings", icon: "settings" },
+];
+
+const Dashboard = () => {
+  const [active, setActive] = useState("/");
+  const onMenuClick = (item) => setActive(item.value);
+  return (
+    <AppShell
+      sidebar={{
+        items: MENU_ITEMS,
+        activeItem: active,
+        onMenuClick,
+        variant: "light",
+      }}
+      header={{
+        logoUrl="/logo.svg",
+        menuItems: MENU_ITEMS,
+        activeMenuItem: active,
+        onMenuItemClick: onMenuClick,
+        headerRight: <Avatar name="User" />,
+      }}
+      footer={{ brandName: "Acme Inc" }}
+      sidebarWidth="260px"
+    >
+      <Container padding="4">
+        <Typography variant="h4">Dashboard</Typography>
+      </Container>
+    </AppShell>
+  );
+};
+```
+
+### Sidebar only
+
+```jsx
+<AppShell
+  sidebar={{
+    items: menuItems,
+    activeItem: activeItem,
+    onMenuClick: (item) => setActiveItem(item.value),
+  }}
+  sidebarWidth="240px"
+>
+  <Container padding="4">
+    <Typography variant="p">Main content</Typography>
+  </Container>
+</AppShell>
+```
+
+### Header and footer only (no sidebar)
+
+```jsx
+<AppShell
+  header={{
+    logoUrl="/logo.svg",
+    menuItems,
+    activeMenuItem: active,
+    onMenuItemClick: (item) => setActive(item.value),
+    headerRight: <Avatar name="User" />,
+  }}
+  footer={{ brandName: "My App" }}
+>
+  <Container padding="4">
+    <Typography variant="p">Content</Typography>
+  </Container>
+</AppShell>
+```
+
+### Content only (minimal shell)
+
+```jsx
+<AppShell>
+  <Container padding="4">
+    <Typography variant="h4">Welcome</Typography>
+  </Container>
+</AppShell>
+```
+
+## Behavior Notes
+
+- **Layout:** Root is a flex column with `min-height: 100vh`. Header and footer slots are full width; body is a flex row (sidebar + main). Main area is scrollable.
+- **Header / footer:** When `header` or `footer` is a plain object with Header/Footer props (e.g. `menuItems` for header), the component renders `<Header {...header} />` or `<Footer {...footer} />`. Otherwise it renders the ReactNode as-is.
+- **Sidebar:** Rendered in an `<aside aria-label="Main navigation">` with MenuList `direction="vertical"`. Width from `sidebarWidth` (inline style).
+- **Responsive:** At viewport width ≤ 1024px the sidebar is hidden via CSS. Pass the same `menuItems` and `activeMenuItem` / `onMenuItemClick` to `header` so the header’s mobile menu provides navigation.
+- **No root spacing props:** AppShell does not expose margin/padding; use `className` or `contentClassName` for layout.
+
+## Related Components / Links
+
+- Header (rendered in header slot when header is Header props; use same menu items for mobile)
+- Footer (rendered in footer slot when footer is Footer props)
+- MenuList (used in sidebar with direction="vertical")
+- Container (wrap page content inside children)
+- Typography, Avatar (common in header and main)

package/docs/Avatar.md

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

@@ -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)