cleanplate 0.2.0 → 0.2.1

package/dist/components/icon/material-icon-names.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"material-icon-names.d.ts","sourceRoot":"","sources":["../../../src/components/icon/material-icon-names.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,eAAO,MAAM,mBAAmB,g/lEAolItB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;CAonIlB,CAAC;AAEX;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,gBAAgB,CAEzE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,OAAO,eAAe,GAAG,SAAS,MAAM,EAAE,CAE5F"}
+{"version":3,"file":"material-icon-names.d.ts","sourceRoot":"","sources":["../../../src/components/icon/material-icon-names.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,eAAO,MAAM,mBAAmB,sjoEAqpItB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;CAqrIlB,CAAC;AAEX;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,gBAAgB,CAEzE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,OAAO,eAAe,GAAG,SAAS,MAAM,EAAE,CAE5F"}

package/docs/Accordion.md

@@ -0,0 +1,125 @@
+# Accordion Component
+
+Purpose: Displays collapsible panels from an array of title and content items. Use for FAQ sections, feature lists, or expandable content. Supports grouped or spaced layout, icon styles (expand arrows or plus/minus), semantic headings (h2–h6) for SEO FAQ pages, allowMultiple, and margin/padding spacing.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| items | AccordionItem[] | yes | — | Array of { title, content } items. |
+| allowMultiple | boolean | no | false | Allow multiple panels open at once. |
+| defaultExpandedIndex | number \| number[] | no | 0 | Index(es) of panel(s) open initially. |
+| iconVariant | "expand" \| "plus" | no | "expand" | Icon style: expand (arrows) or plus (+/-). |
+| variant | "grouped" \| "spaced" | no | "grouped" | Visual layout: grouped (one unit) or spaced (separate items, e.g. FAQ). |
+| titleTag | "span" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6" | no | "span" | Semantic HTML for title; h2–h6 for SEO FAQ pages. |
+| margin | string \| SpacingOption[] | no | — | Spacing suffix(s) for outer margin; component adds m- prefix. |
+| padding | string \| SpacingOption[] | no | — | Spacing suffix(s) for inner padding; component adds p- prefix. |
+| className | string | no | "" | Additional class names for the root element. |
+
+## Types
+
+### AccordionItem
+```typescript
+interface AccordionItem {
+  title: string;
+  content: React.ReactNode;
+}
+```
+
+### AccordionIconVariant
+```typescript
+type AccordionIconVariant = "expand" | "plus";
+```
+
+### AccordionVariant
+```typescript
+type AccordionVariant = "grouped" | "spaced";
+```
+
+### AccordionTitleTag
+```typescript
+type AccordionTitleTag = "span" | "h2" | "h3" | "h4" | "h5" | "h6";
+```
+
+### AccordionMargin / AccordionPadding
+```typescript
+type AccordionMargin = string | SpacingOption[];
+type AccordionPadding = string | SpacingOption[];
+```
+
+### AccordionProps
+```typescript
+interface AccordionProps {
+  items: AccordionItem[];
+  allowMultiple?: boolean;
+  defaultExpandedIndex?: number | number[];
+  iconVariant?: AccordionIconVariant;
+  variant?: AccordionVariant;
+  titleTag?: AccordionTitleTag;
+  margin?: AccordionMargin;
+  padding?: AccordionPadding;
+  className?: string;
+}
+```
+
+## Usage Examples
+
+### Basic
+
+```jsx
+import { Accordion } from "cleanplate";
+
+const items = [
+  { title: "Section 1", content: "Content for section 1." },
+  { title: "Section 2", content: "Content for section 2." },
+];
+
+<Accordion items={items} />
+```
+
+### FAQ (SEO-friendly)
+
+```jsx
+<Accordion
+  items={faqItems}
+  variant="spaced"
+  titleTag="h3"
+  iconVariant="plus"
+/>
+```
+
+### Variants and icons
+
+```jsx
+<Accordion items={items} variant="grouped" />
+<Accordion items={items} variant="spaced" />
+<Accordion items={items} iconVariant="expand" />
+<Accordion items={items} iconVariant="plus" />
+```
+
+### Initial panel(s)
+
+```jsx
+<Accordion items={items} defaultExpandedIndex={1} />
+<Accordion items={items} allowMultiple defaultExpandedIndex={[0, 2]} />
+```
+
+### With spacing
+
+```jsx
+<Accordion items={items} margin="b-2" padding="4" />
+```
+
+## Behavior Notes
+
+- **items:** Each item has `title` (string) and `content` (string or ReactNode). String content is wrapped in Typography.
+- **titleTag:** When h2–h6, titles render as headings for SEO; header uses role="button" with keyboard support.
+- **variant:** grouped = single bordered block; spaced = separate items with gap.
+- **defaultExpandedIndex:** Single number or array; controls which panel(s) are open on initial render.
+- **Margin/padding:** Uses suffix API (e.g. `"0"` → m-0, `"4"` → p-4).
+
+## Related Components / Links
+
+- Container (layout around accordion)
+- Typography (used internally for title and string content)
+- Icon (used for expand/collapse indicator)

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)