cleanplate 0.1.10 → 0.2.0

package/docs/Container.md

@@ -1,230 +0,0 @@
-# Container Component
-
-Purpose: A layout wrapper that controls display type, width, spacing (margin, padding, gap), and flex alignment. Use it to structure content, create flex layouts, and apply consistent spacing. Below the mobile breakpoint (600px), width variants collapse to full width for a responsive default.
-
-## Props / Inputs
-
-| Prop | Type | Required | Default | Description |
-| --- | --- | --- | --- | --- |
-| children | React.ReactNode | no | — | Content to render inside the container. |
-| 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"`, `["1", "b-2"]`. |
-| padding | string \| string[] | no | "p-4" | Spacing **suffix** for inner padding. The component adds the `p-` prefix (e.g. `"4"` → p-4, `"x-2"` → p-x-2). Use a single string or array: `"4"`, `["2", "x-4"]`. |
-| display | "block" \| "flex" \| "inline-block" \| "" | no | "" | Layout mode. Use `"flex"` for flexbox; leave empty for no display class. |
-| align | "start" \| "center" \| "end" \| "" | no | "" | Flex align-items. Only applies when `display="flex"`. |
-| justify | "space-between" \| "center" \| "space-around" \| "space-evenly" \| "flex-end" \| "flex-start" \| "" | no | "" | Flex justify-content. Only applies when `display="flex"`. |
-| width | "small" \| "medium" \| "large" \| "extra-large" \| "quarter" \| "half" \| "three-quarters" \| "full" \| "" | no | "" | Width variant. At viewports ≤600px, all variants become full width. |
-| gap | string \| string[] | no | "4" | Spacing **suffix** for gap between flex children. The component adds the `g-` prefix (e.g. `"4"` → g-4). Meaningful when `display="flex"`. Use `"4"` or `["2", "3"]` for multiple. |
-| showBorder | boolean | no | false | When true, shows a border around the container. |
-| className | string | no | "" | Additional class names for the root element. |
-| onClick | function | no | — | Click handler for the root div. |
-| style | React.CSSProperties | no | — | Inline styles for the root element. |
-| ...rest | React.HTMLAttributes<HTMLDivElement> | no | — | Any other div attributes (e.g. `id`, `data-*`, `aria-*`) are forwarded. |
-
-## Types
-
-### SpacingOption
-```typescript
-type SpacingOption = (typeof SPACING_OPTIONS)[number];
-```
-
-### ContainerDisplay
-```typescript
-type ContainerDisplay = "inline-block" | "block" | "flex";
-```
-
-### ContainerWidth
-```typescript
-type ContainerWidth =
-  | "small"
-  | "medium"
-  | "large"
-  | "extra-large"
-  | "quarter"
-  | "half"
-  | "three-quarters"
-  | "full";
-```
-
-### ContainerJustify
-```typescript
-type ContainerJustify =
-  | "space-between"
-  | "center"
-  | "space-around"
-  | "space-evenly"
-  | "flex-end"
-  | "flex-start";
-```
-
-### ContainerAlign
-```typescript
-type ContainerAlign = "start" | "center" | "end";
-```
-
-### ContainerSpacing
-```typescript
-type ContainerSpacing = string | SpacingOption[];
-```
-
-### ContainerProps
-```typescript
-interface ContainerProps extends React.HTMLAttributes<HTMLDivElement> {
-  children?: React.ReactNode;
-  margin?: ContainerSpacing;
-  padding?: ContainerSpacing;
-  display?: ContainerDisplay | "";
-  align?: ContainerAlign | "";
-  justify?: ContainerJustify | "";
-  width?: ContainerWidth | "";
-  showBorder?: boolean;
-  className?: string;
-  onClick?: (e: React.MouseEvent<HTMLDivElement>) => void;
-  style?: React.CSSProperties;
-  gap?: ContainerSpacing;
-}
-```
-
-## Usage Examples
-
-### Block container
-
-```jsx
-import { Container } from "cleanplate";
-
-export const Example = () => (
-  <Container display="block" padding="4" showBorder>
-    <p>Block container: full width, content stacks vertically.</p>
-  </Container>
-);
-```
-
-### Flex container with alignment
-
-```jsx
-import { Container } from "cleanplate";
-import { Button } from "cleanplate";
-
-export const Example = () => (
-  <Container
-    display="flex"
-    justify="space-between"
-    align="center"
-    padding="3"
-    gap="2"
-    showBorder
-  >
-    <span>Left</span>
-    <Button size="small">Action</Button>
-  </Container>
-);
-```
-
-### Width variants
-
-```jsx
-import { Container } from "cleanplate";
-
-export const Example = () => (
-  <>
-    <Container width="small" showBorder padding="3">Small</Container>
-    <Container width="medium" showBorder padding="3">Medium</Container>
-    <Container width="half" showBorder padding="3">Half</Container>
-    <Container width="full" showBorder padding="3">Full</Container>
-  </>
-);
-```
-
-### Inline-block (side by side)
-
-```jsx
-import { Container } from "cleanplate";
-
-export const Example = () => (
-  <Container display="inline-block" showBorder padding="2" margin="r-2">
-    Block 1
-  </Container>
-  <Container display="inline-block" showBorder padding="2">
-    Block 2
-  </Container>
-);
-```
-
-### Margin and padding
-
-```jsx
-import { Container } from "cleanplate";
-
-export const Example = () => (
-  <>
-    <Container margin="2" padding="4" showBorder>
-      Single suffix values
-    </Container>
-    <Container margin={["1", "b-3"]} padding={["2", "x-4"]} showBorder>
-      Multiple suffixes (component adds m- / p- prefix)
-    </Container>
-  </>
-);
-```
-
-### Flex grid (quarters)
-
-```jsx
-import { Container } from "cleanplate";
-
-export const Example = () => (
-  <Container display="flex" padding="2" gap="2" showBorder>
-    <Container width="quarter" showBorder padding="3">1</Container>
-    <Container width="quarter" showBorder padding="3">2</Container>
-    <Container width="quarter" showBorder padding="3">3</Container>
-    <Container width="quarter" showBorder padding="3">4</Container>
-  </Container>
-);
-```
-
-### Clickable container
-
-```jsx
-import { Container } from "cleanplate";
-
-export const Example = () => (
-  <Container
-    showBorder
-    padding="4"
-    onClick={() => console.log("Clicked")}
-  >
-    Clickable area
-  </Container>
-);
-```
-
-### With custom class and style
-
-```jsx
-import { Container } from "cleanplate";
-
-export const Example = () => (
-  <Container
-    className="my-wrapper"
-    style={{ minHeight: 200 }}
-    padding="4"
-    showBorder
-  >
-    Custom wrapper
-  </Container>
-);
-```
-
-## Behavior Notes
-
-- **Responsive width:** For viewport width ≤600px (mobile breakpoint), all `width` variants are overridden to `100%` in CSS. No prop change is required.
-- **Flex:** When `display="flex"`, the root uses `display: flex` and `flex-wrap: wrap`. Use `align` and `justify` to control alignment; use `gap` for spacing between children.
-- **Spacing:** `margin`, `padding`, and `gap` accept the **spacing suffix** (the component adds the `m-`, `p-`, or `g-` prefix via `getSpacingClass`). Use a single string (e.g. `"4"`, `"0"`, `"b-2"`) or an array of suffixes (e.g. `["1", "b-2"]`). Valid suffixes include `"0"`–`"9"`, `"auto"`, and directional forms like `"x-2"`, `"y-3"`, `"t-0"`, `"r-1"`, `"b-2"`, `"l-3"` (see `SPACING_OPTIONS`). **Note:** The component’s default props are currently `"m-0"` and `"p-4"` (full tokens); internally the util expects suffixes, so when passing values explicitly use suffix form (e.g. `"0"`, `"4"`).
-- **Empty layout props:** Passing `""` or omitting `display`, `align`, `justify`, or `width` means no corresponding class is applied.
-- **Border:** `showBorder` only affects border visibility; the container always reserves border space (border is 1px solid, transparent when not shown).
-- The root element is a `div`; all standard HTML div attributes and ref are supported via `...rest`.
-
-## Related Components / Links
-
-- Typography (often used inside Container for text)
-- Button (commonly placed inside flex Containers)
-- MediaObject (often wrapped in Container for layout)

package/docs/Dropdown.md

@@ -1,175 +0,0 @@
-# Dropdown Component
-
-Purpose: A floating panel that shows content relative to a trigger. Use it for menus, option lists, or any content that opens on click. Supports 12 placements, optional flip/shift to stay in viewport, and three trigger modes: a `trigger` element, a `renderTrigger` function, or a `triggerLabel` for a default button.
-
-## Props / Inputs
-
-| Prop | Type | Required | Default | Description |
-| --- | --- | --- | --- | --- |
-| trigger | React.ReactElement | no | — | Trigger element to clone; ref and onClick are attached. Omit when using `renderTrigger` or `triggerLabel`. |
-| content | React.ReactElement | yes | — | Content shown in the floating panel. Receives `onClose` and `className` when cloned. |
-| placement | DropdownPlacement | no | "bottom-end" | Preferred position relative to trigger (e.g. "bottom-end", "top-start"). |
-| offset | number | no | 4 | Gap in pixels between trigger and panel. |
-| shift | boolean | no | true | When true, shift panel to stay inside viewport. |
-| flip | boolean | no | true | When true, flip to opposite side when there is no space. |
-| closeOnClickOutside | boolean | no | true | Close when user clicks outside trigger and panel. |
-| closeOnEscape | boolean | no | true | Close when user presses Escape. |
-| className | string | no | "" | Class name for the wrapper div. |
-| contentClassName | string | no | "" | Class name applied to the cloned content element. |
-| renderTrigger | (params: DropdownRenderTriggerParams) => React.ReactNode | no | — | Render prop for a custom trigger; receives `isOpen`, `isAnimating`, `placement`, `toggle`, `close`, `triggerProps`. |
-| triggerLabel | string | no | — | Label for the default button trigger. Use when neither `trigger` nor `renderTrigger` is provided. |
-
-## Types
-
-### DropdownPlacement
-```typescript
-type DropdownPlacement =
-  | "top" | "top-start" | "top-end"
-  | "bottom" | "bottom-start" | "bottom-end"
-  | "left" | "left-start" | "left-end"
-  | "right" | "right-start" | "right-end";
-```
-
-### DropdownTriggerProps
-```typescript
-interface DropdownTriggerProps {
-  ref: RefObject<HTMLElement | null>;
-  onClick: (e: React.MouseEvent<HTMLElement>) => void;
-  className: string;
-  role: string;
-  "aria-expanded": boolean;
-  "aria-haspopup": string;
-}
-```
-
-### DropdownRenderTriggerParams
-```typescript
-interface DropdownRenderTriggerParams {
-  isOpen: boolean;
-  isAnimating: boolean;
-  placement: DropdownPlacement;
-  toggle: () => void;
-  close: () => void;
-  triggerProps: DropdownTriggerProps;
-}
-```
-
-### DropdownProps
-```typescript
-interface DropdownProps {
-  trigger?: React.ReactElement;
-  content: React.ReactElement;
-  placement?: DropdownPlacement;
-  offset?: number;
-  shift?: boolean;
-  flip?: boolean;
-  closeOnClickOutside?: boolean;
-  closeOnEscape?: boolean;
-  className?: string;
-  contentClassName?: string;
-  renderTrigger?: (params: DropdownRenderTriggerParams) => React.ReactNode;
-  triggerLabel?: string;
-}
-```
-
-## Usage Examples
-
-### With trigger element
-
-```jsx
-import { Dropdown, Button } from "cleanplate";
-
-const MenuContent = ({ onClose }) => (
-  <div style={{ padding: "var(--space-2)" }}>
-    <button onClick={onClose}>Close</button>
-    <p>Menu items here</p>
-  </div>
-);
-
-export const Example = () => (
-  <Dropdown
-    trigger={<Button>Open Menu</Button>}
-    content={<MenuContent />}
-    placement="bottom-end"
-  />
-);
-```
-
-### With triggerLabel
-
-```jsx
-import { Dropdown } from "cleanplate";
-
-export const Example = () => (
-  <Dropdown
-    triggerLabel="Select Option"
-    content={<MenuContent />}
-    placement="bottom-end"
-  />
-);
-```
-
-### With renderTrigger
-
-```jsx
-import { Dropdown, Button } from "cleanplate";
-
-export const Example = () => (
-  <Dropdown
-    renderTrigger={({ isOpen, triggerProps }) => (
-      <Button {...triggerProps}>
-        {isOpen ? "Close" : "Open"}
-      </Button>
-    )}
-    content={<MenuContent />}
-  />
-);
-```
-
-### Placement and offset
-
-```jsx
-<Dropdown
-  trigger={<Button>Menu</Button>}
-  content={<MenuContent />}
-  placement="top-start"
-  offset={8}
-/>
-```
-
-### Disable flip / shift
-
-```jsx
-<Dropdown
-  trigger={<Button>Menu</Button>}
-  content={<MenuContent />}
-  placement="top"
-  flip={false}
-  shift={false}
-/>
-```
-
-### Close behavior
-
-```jsx
-<Dropdown
-  trigger={<Button>Menu</Button>}
-  content={<MenuContent />}
-  closeOnClickOutside={false}
-  closeOnEscape={true}
-/>
-```
-
-## Behavior Notes
-
-- **Trigger modes:** Exactly one of `trigger`, `renderTrigger`, or `triggerLabel` must be used; the component throws if none are provided.
-- **Content:** The `content` element is cloned; the component injects `onClose` and merges `className` so the panel can close and be styled.
-- **Positioning:** Placement is applied via CSS classes; when `flip` or `shift` are true, the component adjusts placement/position so the panel stays in view.
-- **Accessibility:** The trigger receives `aria-expanded` and `aria-haspopup`; the panel has `role="menu"`. Escape and (optionally) click-outside close the dropdown.
-- **Animation:** Opening/closing uses CSS classes (`dropdown-opening` / `dropdown-closing`); a short delay (e.g. 150ms) is used before unmounting so the close animation can run.
-
-## Related Components / Links
-
-- Button (commonly used as trigger or inside renderTrigger)
-- MenuList (often used inside dropdown content for menu items)
-- Icon (used in the default trigger when `triggerLabel` is set for arrow icons)

package/docs/Icon.md

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