cleanplate 0.1.11 → 0.2.1

package/docs/Icon.md

@@ -0,0 +1,225 @@
+# Icon Component
+
+Purpose: A versatile and reusable element for displaying scalable vector icons, supporting various sizes, colors, and custom classes. It seamlessly integrates into user interfaces to enhance visual appeal and provide intuitive, meaningful representations using Google Material Symbols.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| name | MaterialIconName | no | "" | The name of the Material Symbol icon to display. Use a value from `MATERIAL_ICON_NAMES` or `ICON_CATEGORIES` (see **Icon names and categories** below). |
+| size | "small" \| "medium" \| "large" | no | "medium" | Size variant of the icon. |
+| color | "black" \| "white" \| "gray" \| "blue" \| "green" \| "red" \| "yellow" \| "orange" | no | "black" | Color variant of the icon. |
+| className | string | no | "" | Additional class names for the root element. |
+| ...rest | React.HTMLAttributes<HTMLSpanElement> | no | — | All other standard HTML span attributes are supported and passed through to the rendered element. |
+
+## Types
+
+### IconSize
+```typescript
+type IconSize = "small" | "medium" | "large";
+```
+
+### IconColor
+```typescript
+type IconColor = "black" | "white" | "gray" | "blue" | "green" | "red" | "yellow" | "orange";
+```
+
+### IconProps
+```typescript
+interface IconProps extends React.HTMLAttributes<HTMLSpanElement> {
+  name?: MaterialIconName;
+  size?: IconSize;
+  className?: string;
+  color?: IconColor;
+}
+```
+
+### MaterialIconName
+Icon names are typed as `MaterialIconName` (a union of all valid Material Symbols Outlined names). The package also exports `MATERIAL_ICON_NAMES` (array of all names) and `ICON_CATEGORIES` (icons grouped by purpose) from the Icon component’s generated `material-icon-names` module.
+
+## Icon names and categories
+
+Icon names are sourced from the generated `material-icon-names` module. Icons are grouped into **categories** to make it easier to pick a name for the `name` prop. Use these when suggesting or choosing icons.
+
+| Category | Description | Example icon names |
+| --- | --- | --- |
+| **navigation** | Back, forward, menu, home, close | `arrow_back`, `arrow_forward`, `home`, `menu`, `close` |
+| **action** | Add, edit, delete, search, settings, refresh | `add`, `edit`, `delete`, `search`, `settings`, `refresh` |
+| **communication** | Chat, email, message | `chat`, `chat_bubble`, `email`, `message` |
+| **content** | Copy, cut, paste | `content_copy`, `content_cut`, `content_paste` |
+| **device** | Phone, devices, thermostat | `phone`, `devices`, `device_thermostat`, `phonelink` |
+| **editor** | Format, align, list, bold, italic | `format_bold`, `format_align_center`, `format_list_bulleted` |
+| **file** | Folder, insert, drive | `folder`, `folder_open`, `insert_drive_file`, `insert_photo` |
+| **hardware** | Keyboard, computer | `keyboard`, `computer`, `keyboard_arrow_down` |
+| **image** | Photo, camera, image | `image`, `photo`, `photo_camera`, `photo_library` |
+| **maps** | Map, place | `map`, `place`, `maps_ugc` |
+| **notification** | Notifications, alerts | `notifications`, `notifications_active`, `notification_add` |
+| **social** | Person, group, share | `person`, `person_add`, `group`, `share` |
+| **toggle** | Check, checkbox, toggle | `check`, `check_circle`, `check_box`, `toggle_on` |
+| **av** | Play, pause, volume | `play_arrow`, `pause`, `volume_up`, `volume_off` |
+| **alert** | Error, warning | `error`, `error_outline`, `warning`, `warning_amber` |
+| **other** | All remaining Material Symbols not in the above categories | Many additional names (e.g. `star`, `favorite`, `bookmark`, `progress_activity`) |
+
+- Icon names are generated from the **Material Symbols Outlined** variable font (thousands of names). The `material-icon-names` module is generated by the project’s `generate-icons` script.
+- For **full autocomplete** in TypeScript, use the `MaterialIconName` type or import `MATERIAL_ICON_NAMES` / `ICON_CATEGORIES` from `cleanplate` (or from the package’s icon module).
+- Names use **underscores** (e.g. `cloud_upload`), not spaces.
+- See [Google Fonts – Material Symbols & Icons](https://fonts.google.com/icons) for the full visual reference.
+
+## Installation
+
+Before using the Icon component, you need to include the Material Symbols font in your project. Add the following link tag to the `<head>` of your `index.html`:
+
+```html
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0" />
+```
+
+## Usage Examples
+
+### Basic icon
+
+```jsx
+import { Icon } from "cleanplate";
+
+export const Example = () => (
+  <Icon name="settings" />
+);
+```
+
+### Different sizes
+
+```jsx
+import { Icon } from "cleanplate";
+
+export const Example = () => (
+  <>
+    <Icon name="home" size="small" />
+    <Icon name="home" size="medium" />
+    <Icon name="home" size="large" />
+  </>
+);
+```
+
+### Different colors
+
+```jsx
+import { Icon } from "cleanplate";
+
+export const Example = () => (
+  <>
+    <Icon name="favorite" color="black" />
+    <Icon name="favorite" color="red" />
+    <Icon name="favorite" color="blue" />
+    <Icon name="favorite" color="green" />
+  </>
+);
+```
+
+### Common icons
+
+```jsx
+import { Icon } from "cleanplate";
+
+export const Example = () => (
+  <>
+    <Icon name="home" />
+    <Icon name="settings" />
+    <Icon name="search" />
+    <Icon name="menu" />
+    <Icon name="close" />
+    <Icon name="add" />
+    <Icon name="delete" />
+    <Icon name="edit" />
+    <Icon name="download" />
+    <Icon name="cloud_upload" />
+  </>
+);
+```
+
+### With custom className
+
+```jsx
+import { Icon } from "cleanplate";
+
+export const Example = () => (
+  <Icon
+    name="star"
+    className="custom-icon-class"
+    size="large"
+    color="yellow"
+  />
+);
+```
+
+### With HTML attributes
+
+```jsx
+import { Icon } from "cleanplate";
+
+export const Example = () => (
+  <>
+    <Icon
+      name="info"
+      aria-label="Information icon"
+      data-testid="info-icon"
+      onClick={() => console.log("Icon clicked")}
+    />
+    <Icon
+      name="error"
+      id="error-icon"
+      title="Error occurred"
+    />
+  </>
+);
+```
+
+### In buttons
+
+```jsx
+import { Icon } from "cleanplate";
+import { Button } from "cleanplate";
+
+export const Example = () => (
+  <>
+    <Button>
+      <Icon name="save" size="small" />
+      Save
+    </Button>
+    <Button>
+      <Icon name="download" />
+      Download
+    </Button>
+  </>
+);
+```
+
+### With Typography
+
+```jsx
+import { Icon } from "cleanplate";
+import { Typography } from "cleanplate";
+
+export const Example = () => (
+  <Typography variant="p">
+    <Icon name="check_circle" color="green" size="small" />
+    {" "}Task completed
+  </Typography>
+);
+```
+
+## Behavior Notes
+
+- The component uses the **Material Symbols Outlined** font, which must be included in your project for icons to display correctly.
+- Icon names must match the names from the [Material Symbols set](https://fonts.google.com/icons) (e.g. `progress_activity`, `cloud_upload`). Use underscores instead of spaces. Use the **Icon names and categories** table above to find names by purpose.
+- The component renders as a `<span>` element, making it an inline element by default.
+- If no `name` is provided, the icon will render as an empty span.
+- The `color` prop applies predefined color classes. For custom colors, use the `className` prop with your own CSS.
+- All standard HTML span attributes (like `onClick`, `aria-label`, `data-*`, etc.) are supported and passed through.
+- Icons are scalable and will inherit the font size from their container if custom sizing is needed.
+- The component is designed to work seamlessly with other CleanPlate components like Button, Typography, and Alert.
+
+## Related Components / Links
+
+- Button (commonly uses icons for visual enhancement)
+- Typography (often combined with icons for inline content)
+- Alert (uses icons to indicate different alert types)
+- [Material Symbols & Icons](https://fonts.google.com/icons) – Browse available icon names (Material Symbols Outlined)

package/docs/MediaObject.md

@@ -0,0 +1,303 @@
+# MediaObject Component
+
+Purpose: A flexible layout pattern that combines media (icon, image, or avatar) with content (title and description). Perfect for displaying user profiles, product cards, notifications, and any content that needs a media element alongside text.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| title | string | yes | — | The main title text displayed in the content area. |
+| mediaIcon | string | no | "" | Icon name from Material Symbols to display as the media element. |
+| mediaImage | string | no | "" | Image URL to display as the media element. |
+| mediaAvatar | string | no | "" | Name used to generate an avatar with initials and background color. |
+| description | string | no | — | Secondary text displayed below the title. |
+| margin | string \| string[] | no | "0" | Spacing utility token(s) for outer margin, such as `m-0` or `["m-1", "m-b-2"]`. |
+| padding | string \| string[] | no | "0" | Spacing utility token(s) for inner padding, such as `p-0` or `["p-1", "p-b-2"]`. |
+| className | string | no | "media-object" | Additional class names for the root element. |
+| onClick | function | no | — | Called with the click event when the media object is clicked. |
+| ...rest | React.HTMLAttributes<HTMLDivElement> | no | — | All other standard HTML div attributes are supported and passed through to the rendered element. |
+
+## Types
+
+### MediaObjectMargin
+```typescript
+type MediaObjectMargin = string | SpacingOption[];
+```
+
+### MediaObjectPadding
+```typescript
+type MediaObjectPadding = string | SpacingOption[];
+```
+
+### SpacingOption
+```typescript
+type SpacingOption = typeof SPACING_OPTIONS[number];
+```
+
+### MediaObjectProps
+```typescript
+interface MediaObjectProps extends React.HTMLAttributes<HTMLDivElement> {
+  mediaIcon?: string;
+  mediaImage?: string;
+  mediaAvatar?: string;
+  title: string;
+  description?: string;
+  margin?: MediaObjectMargin;
+  padding?: MediaObjectPadding;
+  className?: string;
+  onClick?: (e: React.MouseEvent<HTMLDivElement>) => void;
+}
+```
+
+## Usage Examples
+
+### With icon
+
+```jsx
+import { MediaObject } from "cleanplate";
+
+export const Example = () => (
+  <MediaObject
+    mediaIcon="person"
+    title="User Profile"
+    description="Manage your account settings and preferences"
+  />
+);
+```
+
+### With image
+
+```jsx
+import { MediaObject } from "cleanplate";
+
+export const Example = () => (
+  <MediaObject
+    mediaImage="https://example.com/avatar.jpg"
+    title="John Doe"
+    description="Senior Developer at Tech Corp"
+  />
+);
+```
+
+### With avatar (initials)
+
+```jsx
+import { MediaObject } from "cleanplate";
+
+export const Example = () => (
+  <MediaObject
+    mediaAvatar="John Doe"
+    title="John Doe"
+    description="Senior Developer with 5+ years of experience"
+  />
+);
+```
+
+### Title only
+
+```jsx
+import { MediaObject } from "cleanplate";
+
+export const Example = () => (
+  <MediaObject
+    mediaIcon="settings"
+    title="Settings"
+  />
+);
+```
+
+### With margin and padding
+
+```jsx
+import { MediaObject } from "cleanplate";
+
+export const Example = () => (
+  <>
+    <MediaObject
+      mediaIcon="star"
+      title="Featured Item"
+      description="This item has custom spacing"
+      margin="m-3"
+      padding="p-2"
+    />
+    <MediaObject
+      mediaIcon="heart"
+      title="Another Item"
+      description="With multiple margin tokens"
+      margin={["m-1", "m-b-3"]}
+      padding={["p-1", "p-x-2"]}
+    />
+  </>
+);
+```
+
+### Clickable media object
+
+```jsx
+import { MediaObject } from "cleanplate";
+
+export const Example = () => (
+  <MediaObject
+    mediaImage="https://example.com/product.jpg"
+    title="Wireless Headphones"
+    description="High-quality wireless headphones"
+    onClick={() => console.log("Media object clicked")}
+  />
+);
+```
+
+### User profile card
+
+```jsx
+import { MediaObject } from "cleanplate";
+import { Button } from "cleanplate";
+
+export const Example = () => (
+  <div style={{ 
+    border: "1px solid #e0e0e0", 
+    borderRadius: "8px",
+    padding: "16px"
+  }}>
+    <MediaObject
+      mediaImage="https://example.com/avatar.jpg"
+      title="John Doe"
+      description="Senior Developer • john.doe@example.com"
+    />
+    <Button variant="outline" size="small" margin="m-t-3">
+      Edit Profile
+    </Button>
+  </div>
+);
+```
+
+### Product card
+
+```jsx
+import { MediaObject } from "cleanplate";
+import { Typography } from "cleanplate";
+import { Button } from "cleanplate";
+
+export const Example = () => (
+  <div style={{ 
+    border: "1px solid #e0e0e0", 
+    borderRadius: "8px",
+    padding: "16px"
+  }}>
+    <MediaObject
+      mediaImage="https://example.com/product.jpg"
+      title="Wireless Headphones"
+      description="High-quality wireless headphones with noise cancellation"
+    />
+    <div style={{ marginTop: "12px", display: "flex", justifyContent: "space-between", alignItems: "center" }}>
+      <Typography variant="h5">$199.99</Typography>
+      <Button size="small" variant="outline">Add to Cart</Button>
+    </div>
+  </div>
+);
+```
+
+### Notification list
+
+```jsx
+import { MediaObject } from "cleanplate";
+
+export const Example = () => (
+  <div>
+    <MediaObject
+      mediaIcon="notifications"
+      title="New Message"
+      description="You have received a new message from Jane Smith"
+      margin="m-b-2"
+    />
+    <MediaObject
+      mediaIcon="schedule"
+      title="Meeting Reminder"
+      description="Team standup in 30 minutes"
+      margin="m-b-2"
+    />
+    <MediaObject
+      mediaIcon="done"
+      title="Task Completed"
+      description="Your project 'Website Redesign' has been updated"
+    />
+  </div>
+);
+```
+
+### Settings items
+
+```jsx
+import { MediaObject } from "cleanplate";
+
+export const Example = () => (
+  <div>
+    <MediaObject
+      mediaIcon="settings"
+      title="Account Settings"
+      description="Manage your account preferences and security settings"
+      margin="m-b-2"
+    />
+    <MediaObject
+      mediaIcon="lock"
+      title="Privacy & Security"
+      description="Control your privacy settings and security options"
+      margin="m-b-2"
+    />
+    <MediaObject
+      mediaIcon="notifications"
+      title="Notifications"
+      description="Configure how and when you receive notifications"
+    />
+  </div>
+);
+```
+
+### List of users
+
+```jsx
+import { MediaObject } from "cleanplate";
+
+export const Example = () => {
+  const users = [
+    { name: "John Doe", role: "Developer", avatar: "https://example.com/avatar1.jpg" },
+    { name: "Jane Smith", role: "Designer", avatar: "https://example.com/avatar2.jpg" },
+    { name: "Mike Johnson", role: "Manager", avatar: "https://example.com/avatar3.jpg" }
+  ];
+
+  return (
+    <div>
+      {users.map((user, index) => (
+        <MediaObject
+          key={index}
+          mediaImage={user.avatar}
+          title={user.name}
+          description={user.role}
+          margin={index < users.length - 1 ? "m-b-2" : "m-0"}
+        />
+      ))}
+    </div>
+  );
+};
+```
+
+## Behavior Notes
+
+- The `title` prop is required and will always be displayed in bold text.
+- The `description` prop is optional. If not provided, only the title will be displayed.
+- You can provide one of `mediaIcon`, `mediaImage`, or `mediaAvatar` to display the media element. If multiple are provided, the component will prioritize in this order: `mediaAvatar` > `mediaImage` > `mediaIcon`.
+- The component uses the `Avatar` component internally to render the media element, which supports icons, images, and generated avatars with initials.
+- The component uses the `Typography` component internally for the title and description text.
+- The title is rendered with `isBold={true}` by default.
+- The description is rendered with `variant="small"`.
+- The component renders as a `<div>` element with a flex layout structure.
+- Margin and padding spacing accept either a single string token (e.g., `"m-2"`) or an array of tokens (e.g., `["m-1", "m-b-3"]`).
+- The `onClick` handler makes the entire media object clickable, useful for interactive lists or cards.
+- All standard HTML div attributes can be passed through, allowing for custom `id`, `data-*`, `aria-*`, and other attributes.
+- The component is designed to be responsive and adapts to different screen sizes.
+
+## Related Components / Links
+
+- Avatar (used internally for the media element)
+- Typography (used internally for title and description)
+- Button (often used alongside MediaObject in cards)
+- Container (commonly used to wrap MediaObject components)

package/docs/MenuList.md

@@ -0,0 +1,113 @@
+# MenuList Component
+
+Purpose: Renders a list of navigational items with optional icons, active state highlighting, and customizable layout. Use for nav menus, sidebars, or link lists. Supports horizontal and vertical directions, sizes (small, medium, large), variants (light, dark), and margin spacing. Items use Animated with fade-in-left on mount.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| items | MenuListItem[] | yes | — | List of menu items; each has label, value, optional icon. |
+| activeItem | string | no | — | Value of the currently active item (matches item.value). |
+| size | "small" \| "medium" \| "large" | no | — | Size of menu items. |
+| variant | "light" \| "dark" | no | — | Visual variant. |
+| direction | "horizontal" \| "vertical" | no | "horizontal" | Layout direction of the list. |
+| margin | string \| SpacingOption[] | no | — | Spacing suffix(s) for outer margin; component adds m- prefix. |
+| className | string | no | "" | Additional class names for the root element. |
+| onMenuClick | (item: MenuListItem) => void | no | — | Called when a menu item is clicked; receives the clicked item. |
+
+## Types
+
+### MenuListItem
+```typescript
+interface MenuListItem {
+  label: string;
+  value: string;
+  icon?: MaterialIconName;  // optional Material icon name
+}
+```
+
+### MenuListSize
+```typescript
+type MenuListSize = "small" | "medium" | "large";
+```
+
+### MenuListVariant
+```typescript
+type MenuListVariant = "light" | "dark";
+```
+
+### MenuListDirection
+```typescript
+type MenuListDirection = "horizontal" | "vertical";
+```
+
+### MenuListProps
+```typescript
+interface MenuListProps {
+  items: MenuListItem[];
+  activeItem?: string;
+  size?: MenuListSize;
+  variant?: MenuListVariant;
+  direction?: MenuListDirection;
+  margin?: MenuListMargin;
+  className?: string;
+  onMenuClick?: (item: MenuListItem) => void;
+}
+```
+
+## Usage Examples
+
+### Basic
+
+```jsx
+import { useState } from "react";
+import { MenuList } from "cleanplate";
+
+const ITEMS = [
+  { label: "Dashboard", value: "/", icon: "speed" },
+  { label: "Projects", value: "/projects", icon: "receipt_long" },
+];
+
+const Nav = () => {
+  const [activeItem, setActiveItem] = useState("/");
+  return (
+    <MenuList
+      items={ITEMS}
+      activeItem={activeItem}
+      onMenuClick={(item) => setActiveItem(item.value)}
+    />
+  );
+};
+```
+
+### Directions and variants
+
+```jsx
+<MenuList items={items} direction="horizontal" activeItem={activeItem} onMenuClick={handleClick} />
+<MenuList items={items} direction="vertical" activeItem={activeItem} onMenuClick={handleClick} />
+<MenuList items={items} variant="light" activeItem={activeItem} onMenuClick={handleClick} />
+<MenuList items={items} variant="dark" activeItem={activeItem} onMenuClick={handleClick} />
+```
+
+### Sizes
+
+```jsx
+<MenuList items={items} size="small" activeItem={activeItem} onMenuClick={handleClick} />
+<MenuList items={items} size="medium" activeItem={activeItem} onMenuClick={handleClick} />
+<MenuList items={items} size="large" activeItem={activeItem} onMenuClick={handleClick} />
+```
+
+## Behavior Notes
+
+- **Items:** Each item must have `label` and `value`. `icon` is optional (Material icon name).
+- **onMenuClick:** Called with the clicked item. Use it to update `activeItem` or navigate.
+- **DOM:** A `div` wrapping a `ul` of `li` elements; each `li` contains an anchor.
+- **Animated:** Each item is wrapped in Animated with `fade-in-left` and staggered delay.
+- **Margin:** Uses the suffix API (e.g. `"0"` → m-0, `"b-2"` → m-b-2).
+
+## Related Components / Links
+
+- Dropdown (often uses MenuList inside for menu items)
+- Header (commonly uses MenuList for navigation)
+- Container (layout around the menu)
+- Typography, Icon, Animated (used internally)