cleanplate 0.1.7 → 0.1.8

package/docs/Button.md

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

@@ -0,0 +1,194 @@
+# 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 | string | no | "" | The name of the Material Symbol icon to display. See [Google Material Icons](https://fonts.google.com/icons) for available icon names. |
+| 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?: string;
+  size?: IconSize;
+  className?: string;
+  color?: IconColor;
+}
+```
+
+## 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 Google Material Symbols (Material Icons) font, which must be included in your project for icons to display correctly.
+- Icon names should match the exact names from the [Google Material Icons library](https://fonts.google.com/icons). Use underscores instead of spaces (e.g., `cloud_upload` not `cloud upload`).
+- 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)
+- [Google Material Icons](https://fonts.google.com/icons) - Browse available icon names

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)