cleanplate 0.2.0 → 0.2.2

package/docs/Container.md

@@ -0,0 +1,230 @@
+# 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. **Spacing (margin, padding, gap)** uses the **framework-wide suffix rule** (same for all CleanPlate components); see `llms.txt`.
+
+## 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

@@ -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)