cleanplate 0.1.11 → 0.2.1

package/docs/Dropdown.md

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

@@ -0,0 +1,93 @@
+# Footer Component
+
+Purpose: Customizable footer with copyright text, optional powered-by link, and custom content via children. Use for app footers with branding, legal links, or column layouts. Supports sizes (small, medium, large), variants (light, dark), and margin spacing.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| margin | string \| SpacingOption[] | no | "0" | Spacing suffix(s) for outer margin; component adds m- prefix. |
+| size | "small" \| "medium" \| "large" | no | "large" | Size of the footer. |
+| variant | "light" \| "dark" | no | "light" | Visual variant. |
+| brandName | string | no | "" | Brand name shown in copyright (e.g. "Acme Inc"). |
+| poweredByLabel | string | no | "" | Label for the powered-by link (e.g. "Powered by X"). |
+| poweredByLink | string | no | "" | URL for the powered-by link; shown when poweredByLabel is also set. |
+| children | ReactNode | no | — | Custom content rendered above the copyright line. |
+| className | string | no | "" | Additional class names for the root element. |
+
+## Types
+
+### FooterSize
+```typescript
+type FooterSize = "small" | "medium" | "large";
+```
+
+### FooterVariant
+```typescript
+type FooterVariant = "light" | "dark";
+```
+
+### FooterMargin
+```typescript
+type FooterMargin = string | SpacingOption[];
+```
+
+### FooterProps
+```typescript
+interface FooterProps {
+  margin?: FooterMargin;
+  size?: FooterSize;
+  variant?: FooterVariant;
+  brandName?: string;
+  poweredByLabel?: string;
+  poweredByLink?: string;
+  children?: React.ReactNode;
+  className?: string;
+}
+```
+
+## Usage Examples
+
+### Basic
+
+```jsx
+import { Footer } from "cleanplate";
+
+<Footer brandName="Acme Inc" />
+```
+
+### With powered-by link
+
+```jsx
+<Footer
+  brandName="Acme Inc"
+  poweredByLabel="Powered by Sivadass"
+  poweredByLink="https://sivadass.in"
+/>
+```
+
+### With custom content
+
+```jsx
+<Footer brandName="Acme Inc">
+  <Container display="flex" gap="4">
+    <Container width="quarter">
+      <Typography variant="h6" margin={["0", "b-2"]}>Links</Typography>
+      <ul><li><a href="/contact">Contact</a></li></ul>
+    </Container>
+  </Container>
+</Footer>
+```
+
+## Behavior Notes
+
+- **Copyright:** Uses current year and `brandName` in "© {year} {brandName}. All rights reserved."
+- **Powered-by:** Link shows only when both `poweredByLabel` and `poweredByLink` are set; link has `rel="noopener noreferrer"`.
+- **children:** Rendered in a wrapper div above the copyright line.
+- **Margin:** Uses the suffix API (e.g. `"0"` → m-0).
+
+## Related Components / Links
+
+- Container (layout for footer columns or custom content)
+- Typography (used internally for copyright)
+- Header (often paired with Footer for app layout)

package/docs/FormControls.md

@@ -0,0 +1,115 @@
+# FormControls
+
+FormControls is a set of form primitives exported as a namespace: `FormControls.Input`, `FormControls.Select`, `FormControls.TextArea`, `FormControls.Date`, `FormControls.Checkbox`, `FormControls.Radio`, `FormControls.File`, `FormControls.Toggle`, `FormControls.Stepper`. Use them to build forms with consistent styling, labels, validation messages, and optional fluid layout. Common props across controls: label, isDisabled, isRequired, isFluid, className, error.
+
+## Controls overview
+
+| Control | Purpose | Key props |
+| --- | --- | --- |
+| Input | Single-line text | placeholder, value, onChange(e), type |
+| TextArea | Multi-line text | placeholder, value, onChange(e) |
+| Select | Single or multi select dropdown | options ({ label, value }[]), value, onChange(option \| option[]), isMulti, placeholder |
+| Date | Day/month/year picker (DD-MMM-YYYY) | defaultValue, onChange(dateValue: string) |
+| Checkbox | Single checkbox | value (boolean), onChange(checked: boolean) |
+| Radio | Radio input | name, value, onChange(e) |
+| File | File input | onChange(e) |
+| Toggle | Toggle input | name, value, onChange(e) |
+| Stepper | Text input for step flows | placeholder, value, onChange(e) |
+
+## Types
+
+### SelectOption
+```typescript
+interface SelectOption {
+  label: string;
+  value: string | number;
+}
+```
+
+### SelectProps
+```typescript
+interface SelectProps {
+  onChange?: (option: SelectOption | SelectOption[]) => void;
+  value?: SelectOption | SelectOption[] | null;
+  label?: string;
+  options?: SelectOption[];
+  placeholder?: string;
+  isMulti?: boolean;
+  isRequired?: boolean;
+  isDisabled?: boolean;
+  isFluid?: boolean;
+  error?: string;
+  className?: string;
+  triggerClassName?: string;
+  triggerActiveClassName?: string;
+  contentsClassName?: string;
+}
+```
+
+### InputProps
+```typescript
+interface InputProps {
+  name?: string;
+  id?: string;
+  onChange?: (e: React.ChangeEvent<HTMLInputElement>) => void;
+  onKeyDown?: (e: React.KeyboardEvent<HTMLInputElement>) => void;
+  value?: string;
+  defaultValue?: string;
+  label?: string;
+  placeholder?: string;
+  type?: string;
+  isRequired?: boolean;
+  isDisabled?: boolean;
+  isFluid?: boolean;
+  className?: string;
+  error?: string;
+}
+```
+
+### Other control types
+- **TextAreaProps**, **FileProps**, **RadioProps**, **ToggleProps**: label, value/defaultValue, onChange, isDisabled, isRequired, isFluid, className, error (where applicable).
+- **CheckboxProps**: value (boolean), onChange(checked: boolean).
+- **DateProps**: defaultValue (string "dd-mm-yyyy"), onChange(dateValue: string).
+- **FormControlsStepperProps**: label, placeholder, value, onChange(e).
+
+## Usage Examples
+
+### Input and Select
+
+```jsx
+import { FormControls } from "cleanplate";
+
+<FormControls.Input label="Email" placeholder="user@example.com" isRequired />
+<FormControls.Select
+  label="Fruit"
+  placeholder="Select"
+  options={[{ label: "Apple", value: "apple" }, { label: "Mango", value: "mango" }]}
+  onChange={(option) => console.log(option)}
+/>
+```
+
+### TextArea, Checkbox, Date
+
+```jsx
+<FormControls.TextArea label="Message" placeholder="Hello" />
+<FormControls.Checkbox label="Accept terms?" value={checked} onChange={setChecked} />
+<FormControls.Date label="DOB" defaultValue="31-05-1992" onChange={(v) => {}} />
+```
+
+### Used by other components
+
+Pagination uses `FormControls.Select` for rows-per-page. Pills uses `FormControls.Input` in edit mode.
+
+## Behavior Notes
+
+- **Select:** options are `{ label, value }`; single select passes one option to onChange, multi passes an array. value can be option or array for multi.
+- **Date:** Returns string "dd-mm-yyyy" to onChange; uses internal day/month/year Selects.
+- **Error:** When `error` is set, the field shows error styling and message below.
+- **isFluid:** Full-width field wrapper.
+
+## Related Components / Links
+
+- Pills (uses FormControls.Input in edit mode)
+- Pagination (uses FormControls.Select for rows-per-page)
+- Container (layout around form fields)
+- Button (submit/cancel in forms)

package/docs/Header.md

@@ -0,0 +1,115 @@
+# Header Component
+
+Purpose: Responsive navigation header with logo, menu items, and customizable left, center, and right slots. Use for app navigation. Supports sizes, variants, margin spacing, and a responsive mobile menu that slides in from the left. Uses MenuList for nav items; headerLeft, headerCenter, headerRight for custom content.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| logoUrl | string | no | — | URL for the logo image (shown when headerLeft is not provided). |
+| activeMenuItem | string | no | — | Value of the currently active menu item (matches item.value). |
+| onMenuItemClick | (item: MenuListItem) => void | no | — | Called when a menu item is clicked; receives the clicked item. |
+| className | string | no | "" | Additional class names for the root element. |
+| headerLeft | ReactNode | no | — | Custom content for the left area (replaces logo when provided). |
+| headerRight | ReactNode | no | — | Custom content for the right area. |
+| headerCenter | ReactNode | no | — | Custom content for the center area (replaces MenuList when provided). |
+| menuItems | MenuListItem[] | yes | — | Menu items for center nav and mobile menu; each has label, value, optional icon. |
+| size | "small" \| "medium" \| "large" | no | — | Size of the header. |
+| variant | "light" \| "dark" | no | — | Visual variant. |
+| margin | string \| SpacingOption[] | no | — | Spacing suffix(s) for outer margin; component adds m- prefix. |
+
+## Types
+
+### HeaderSize
+```typescript
+type HeaderSize = "small" | "medium" | "large";
+```
+
+### HeaderVariant
+```typescript
+type HeaderVariant = "light" | "dark";
+```
+
+### HeaderMargin
+```typescript
+type HeaderMargin = string | SpacingOption[];
+```
+
+### HeaderProps
+```typescript
+interface HeaderProps {
+  logoUrl?: string;
+  activeMenuItem?: string;
+  onMenuItemClick?: (item: MenuListItem) => void;
+  className?: string;
+  headerLeft?: React.ReactNode;
+  headerRight?: React.ReactNode;
+  headerCenter?: React.ReactNode;
+  menuItems: MenuListItem[];
+  size?: HeaderSize;
+  variant?: HeaderVariant;
+  margin?: HeaderMargin;
+}
+```
+
+## Usage Examples
+
+### Basic
+
+```jsx
+import { useState } from "react";
+import { Header, Avatar } from "cleanplate";
+
+const MENU_ITEMS = [
+  { label: "Dashboard", value: "/", icon: "speed" },
+  { label: "Projects", value: "/projects", icon: "receipt_long" },
+];
+
+const AppHeader = () => {
+  const [activeMenuItem, setActiveMenuItem] = useState("/");
+  return (
+    <Header
+      logoUrl="/logo.svg"
+      menuItems={MENU_ITEMS}
+      activeMenuItem={activeMenuItem}
+      onMenuItemClick={(item) => setActiveMenuItem(item.value)}
+      headerRight={<Avatar name="John" />}
+    />
+  );
+};
+```
+
+### With custom slots
+
+```jsx
+<Header
+  menuItems={menuItems}
+  activeMenuItem={activeItem}
+  onMenuItemClick={handleClick}
+  headerLeft={<img src="/logo.svg" alt="Logo" />}
+  headerRight={<Avatar name="User" />}
+/>
+```
+
+### Variants and sizes
+
+```jsx
+<Header menuItems={items} variant="light" activeMenuItem={active} onMenuItemClick={handle} />
+<Header menuItems={items} variant="dark" activeMenuItem={active} onMenuItemClick={handle} />
+<Header menuItems={items} size="small" activeMenuItem={active} onMenuItemClick={handle} />
+```
+
+## Behavior Notes
+
+- **menuItems:** Required; each item has label, value, optional icon (Material icon name).
+- **headerLeft / headerCenter / headerRight:** When provided, replace the default logo, MenuList, or right slot.
+- **Mobile:** Below 1024px, center nav hides; hamburger shows. Click opens slide-in menu (Animated fade-in-left).
+- **onMenuItemClick:** Called with the clicked item; mobile menu closes on click.
+- **Margin:** Uses the suffix API (e.g. `"0"` → m-0).
+
+## Related Components / Links
+
+- MenuList (used in center and mobile menu)
+- Avatar (commonly in headerRight)
+- Button, Icon (mobile menu trigger and close)
+- Animated (mobile menu slide-in)