cleanplate 0.1.11 → 0.2.1

package/llms.txt

@@ -0,0 +1,293 @@
+# CleanPlate Component Documentation Index
+
+This file is published in the **`cleanplate` npm package** (next to `package.json`). Consumers and coding agents should use `node_modules/cleanplate/llms.txt` or a CDN URL pinned to their installed semver (see the README “LLM / AI-friendly docs & agents” section).
+
+This file contains an index of all available component documentation for the CleanPlate UI framework.
+
+## Project Overview
+
+CleanPlate is a Headless React UI Framework providing reusable, accessible, and customizable components for building modern web applications.
+
+## Guidelines for AI / LLM code generation
+
+When generating code that uses CleanPlate components, **use component props instead of inline `style`** for layout, spacing, and alignment. The framework exposes these via props; inline styles bypass design tokens and consistency.
+
+### Spacing (margin, padding, gap) — common rule for all components
+
+**This rule applies to every CleanPlate component** that accepts `margin`, `padding`, or `gap` (Typography, Button, Container, Alert, Avatar, Accordion, Header, Footer, and others). All of them use the same **suffix-only** API; the component adds the prefix internally.
+
+- **Correct:** `margin="0"`, `margin="b-2"`, `margin={["b-2", "t-1"]}`, `padding="4"`, `gap="2"`. The component turns these into m-0, m-b-2, p-4, g-2, etc.
+- **Wrong:** `margin="m-0"`, `padding="p-4"`, `gap="g-2"` — do not include the m-, p-, or g- prefix.
+- Common suffixes: "0", "1", "2", "3", "4", "b-1", "b-2", "t-2", "y-2", "x-2".
+- Use the `margin` / `padding` / `gap` prop instead of `style={{ marginBottom, paddingTop, gap }}` for spacing.
+
+### Typography
+- **Text alignment:** Use the `align` prop. Example: `<Typography align="center">` not `style={{ textAlign: "center" }}`. Values: `"left"`, `"center"`, `"right"`.
+- **Spacing:** Use `margin` with the spacing suffix (see above; same rule as all components).
+- **Bold:** Use `isBold` prop, not `style={{ fontWeight: "bold" }}`.
+
+### Other components
+- **Container:** Use `padding`, `margin`, `gap`, `align`, `justify`, `display`, `width` props (spacing uses suffix rule above).
+- **Button, Alert, Badge, etc.:** Each has documented props (e.g. variant, size, margin). Prefer these over inline style. Any `margin` or `padding` prop follows the suffix rule. See `docs/<ComponentName>.md` for the full prop list.
+
+### Example (correct)
+```jsx
+<Typography variant="h4" align="center" margin="b-2">Login</Typography>
+```
+
+### Example (avoid)
+```jsx
+<Typography variant="h4" style={{ textAlign: "center", marginBottom: "1rem" }}>Login</Typography>
+```
+
+## Component Documentation
+
+All component documentation is located in the `docs/` folder. The following documentation files are available:
+
+### Button Component
+- File: `docs/Button.md`
+- 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.
+- Key Features: Variants (solid, outline, ghost, icon), sizes (small, medium), loading states, disabled states, fluid layout, margin spacing
+- Types: ButtonProps, ButtonSize, ButtonVariant, ButtonMargin, SpacingOption
+
+### Typography Component
+- File: `docs/Typography.md`
+- Purpose: Provides a consistent set of text styles for headings, paragraphs, and inline elements, ensuring clear hierarchy, readability, and brand-aligned communication across the interface.
+- Key Features: Variants (h1-h6, p, span, small), text alignment, word breaking, bold text, margin spacing
+- Types: TypographyProps, TypographyVariant, TypographyAlign, TypographyWordBreak, TypographyMargin, SpacingOption
+
+### Icon Component
+- File: `docs/Icon.md`
+- Purpose: A versatile and reusable element for displaying scalable vector icons, supporting various sizes, colors, and custom classes. Uses Google Material Symbols.
+- Key Features: Material Symbols integration, sizes (small, medium, large), colors (black, white, gray, blue, green, red, yellow, orange)
+- Types: IconProps, IconSize, IconColor
+- Note: Requires Material Symbols font to be included in the project
+
+### MediaObject Component
+- File: `docs/MediaObject.md`
+- 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.
+- Key Features: Media types (icon, image, avatar), title and description, margin and padding spacing, clickable support
+- Types: MediaObjectProps, MediaObjectMargin, MediaObjectPadding, SpacingOption
+- Related Components: Uses Avatar and Typography internally
+
+### Avatar Component
+- File: `docs/Avatar.md`
+- Purpose: Displays user initials, an image, or a Material icon in a consistent circle. Use for user identity in headers, lists, MediaObject, or anywhere you need a compact avatar.
+- Key Features: Display modes (initials, image, icon), sizes (small, medium), margin spacing (suffix API: e.g. "0" → m-0), optional onClick
+- Types: AvatarProps, AvatarSize, AvatarMargin, SpacingOption; icon prop uses MaterialIconName from Icon
+- Related Components: Used by MediaObject; often used with Container, Icon
+
+### Container Component
+- File: `docs/Container.md`
+- 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.
+- Key Features: Display (block, flex, inline-block), width variants, margin/padding/gap spacing (suffix API: e.g. "4" → p-4, "0" → m-0), flex align/justify, responsive width at 600px
+- Types: ContainerProps, ContainerDisplay, ContainerWidth, ContainerJustify, ContainerAlign, ContainerSpacing, SpacingOption
+
+### Dropdown Component
+- File: `docs/Dropdown.md`
+- Purpose: Floating panel that shows content relative to a trigger. Use for menus, option lists, or any content that opens on click.
+- Key Features: 12 placements, flip/shift to stay in viewport, three trigger modes (trigger element, renderTrigger, triggerLabel), close on outside click or Escape
+- Types: DropdownProps, DropdownPlacement, DropdownTriggerProps, DropdownRenderTriggerParams
+- Related Components: Button (trigger), MenuList (content)
+
+### Alert Component
+- File: `docs/Alert.md`
+- Purpose: Displays a short message with optional variant icon and dismiss button. Use for inline feedback (success, error, warning, info) or neutral notices.
+- Key Features: Variants (default, info, warning, error, success), sizes (small, medium, large), dismissible with onDismiss, margin spacing (suffix API), unmounts on dismiss
+- Types: AlertProps, AlertSize, AlertVariant, AlertMargin, SpacingOption
+- Related Components: Typography, Container, Button, Icon (used internally)
+
+### Spinner Component
+- File: `docs/Spinner.md`
+- Purpose: Loading indicator that shows a rotating Material icon. Use for progress or activity states.
+- Key Features: Six icon options (progress_activity, autorenew, sync, refresh, cached, loop), sizes (small, medium, large), variants (light, dark), margin spacing (suffix API)
+- Types: SpinnerProps, SpinnerSize, SpinnerVariant, SpinnerIcon, SpinnerMargin, SpacingOption
+- Related Components: Container, Icon (used internally)
+
+### Stepper Component
+- File: `docs/Stepper.md`
+- Purpose: Displays a sequence of steps for wizards or multi-step flows. Each step has label, key, and optional active/completed state; steps can be clickable.
+- Key Features: Variants (horizontal, vertical), config-driven steps (StepperStepConfig), optional onClick(step), margin spacing (suffix API), completed state shows done icon
+- Types: StepperProps, StepperStepConfig, StepperVariant, StepperMargin, SpacingOption
+- Related Components: Container, Typography, Icon (used internally)
+
+### BreadCrumb Component
+- File: `docs/BreadCrumb.md`
+- Purpose: Renders a semantic navigation trail (e.g. Home → Products → Current page). Use at the top of a page to show hierarchy and let users navigate back. Last item without href is the current page.
+- Key Features: Semantic nav/ol/li, aria-current="page", Schema.org BreadcrumbList, separators (chevron, slash), items (label, optional href), margin spacing (suffix API)
+- Types: BreadCrumbProps, BreadCrumbItem, BreadCrumbSeparator, BreadCrumbMargin, SpacingOption
+- Related Components: Container, Typography, Icon (used internally), Header
+
+### Accordion Component
+- File: `docs/Accordion.md`
+- Purpose: Collapsible panels from array of title and content items. For FAQ sections, feature lists, or expandable content.
+- Key Features: items (title, content), allowMultiple, defaultExpandedIndex, iconVariant (expand, plus), variant (grouped, spaced), titleTag (span, h2–h6 for SEO), margin, padding (suffix API), className
+- Types: AccordionProps, AccordionItem, AccordionIconVariant, AccordionVariant, AccordionTitleTag, AccordionMargin, AccordionPadding
+- Related Components: Container, Typography, Icon (used internally)
+
+### ConfirmDialog Component
+- File: `docs/ConfirmDialog.md`
+- Purpose: Modal dialog for confirmation actions (delete, discard, proceed). Title, description, primary/secondary buttons, optional close button; overlay and Escape to close.
+- Key Features: Variants (default, destructive, warning), sizes (small, medium, large), showCloseButton, closeOnOverlayClick, closeOnEscape, focus and body scroll management
+- Types: ConfirmDialogProps, ConfirmDialogSize, ConfirmDialogVariant
+- Related Components: Button, Typography, Icon (used internally)
+
+### Modal Component
+- File: `docs/Modal.md`
+- Purpose: Full-featured modal overlay for forms, long content, or custom dialogs. Optional title, close button, footer primary/secondary buttons; overlay and Escape to close.
+- Key Features: Sizes (small, medium, large, fullscreen), showCloseButton, closeOnOverlayClick, closeOnEscape, margin spacing, contentClassName/overlayClassName, focus and body scroll management
+- Types: ModalProps, ModalSize, ModalMargin, SpacingOption
+- Related Components: ConfirmDialog (simpler confirm-only), Button, Typography, Icon (used internally)
+
+### Pagination Component
+- File: `docs/Pagination.md`
+- Purpose: Navigate large content sets by pages. Shows total count, prev/next and page-number buttons with ellipsis, and optional rows-per-page select. Controlled via currentPage and rowsPerPage.
+- Key Features: Variants (default, minimal), rowsPerPageOptions, onPageChange(page, rowsPerPage), onRowsPerPageChange(rowsPerPage), margin spacing (suffix API)
+- Types: PaginationProps, PaginationVariant, PaginationMargin, PaginationRowsPerPageOption, SpacingOption
+- Related Components: Table (often used with Pagination), Container, Button, FormControls.Select, Typography, Icon (used internally)
+
+### Table Component
+- File: `docs/Table.md`
+- Purpose: Displays structured data in a table with configurable columns, optional built-in pagination, and responsive mobile view (MediaObject cards when viewport < 768px and mobileColumns set).
+- Key Features: columns (id, title, textAlign, widthPercentage, customRender), data (TableRow[]), variants (default, compact), mobileColumns, onRowClick, pagination props (totalItems, currentPage, onPageChange, etc.), hidePagination, margin (suffix API)
+- Types: TableProps, TableColumn, TableRow, TableVariant, TableMargin, TableColumnTextAlign, TableMobileColumns, SpacingOption
+- Related Components: Pagination (built-in), MediaObject (mobile view), Typography, Container, Badge (often in customRender)
+
+### Badge Component
+- File: `docs/Badge.md`
+- Purpose: Short label with colored background for status, tags, or counts. Inline-block, five variants.
+- Key Features: label, variant (default, info, success, warning, error), className
+- Types: BadgeProps, BadgeVariant
+- Related Components: Table (often in customRender for status columns), Container (layout for multiple badges)
+
+### Pills Component
+- File: `docs/Pills.md`
+- Purpose: Single tag/chip with modes: read-only (label only), edit (input + submit), remove (label + close). For tags, filters, editable chips.
+- Key Features: mode (read-only, edit, remove), label, placeholder, onSubmit(value), onRemove(), isLoading, isDisabled, margin (suffix API)
+- Types: PillsProps, PillsMode, PillsMargin, SpacingOption
+- Related Components: Container (layout), FormControls.Input, Button, Icon, Spinner, Typography (used internally)
+
+### Animated Component
+- File: `docs/Animated.md`
+- Purpose: Atom that adds scroll-triggered entrance/exit animations. Uses IntersectionObserver; applies animation class when element enters viewport.
+- Key Features: animationType (fade-in/out top, right, bottom, left), as (polymorphic root), delay (ms for stagger), margin (suffix API), isBlock
+- Types: AnimatedProps, AnimatedMargin, AnimationType, AnimationDelay, SpacingOption
+- Related Components: Container, Typography, Avatar (content); Header, BottomSheet, MenuList (use Animated internally)
+
+### FormControls
+- File: `docs/FormControls.md`
+- Purpose: Set of form primitives: Input, TextArea, Select, Date, Checkbox, Radio, File, Toggle, Stepper. Access via FormControls.Input, FormControls.Select, etc.
+- Key Features: Input (text), TextArea, Select (single/multi, options { label, value }), Date (dd-mm-yyyy), Checkbox (onChange(boolean)), Radio, File, Toggle, Stepper; common props label, isRequired, isFluid, error
+- Types: InputProps, SelectProps, SelectOption, TextAreaProps, CheckboxProps, FileProps, RadioProps, ToggleProps, DateProps, FormControlsStepperProps
+- Related Components: Pills (Input), Pagination (Select), Container, Button
+
+### Toast Component
+- File: `docs/Toast.md`
+- Purpose: Displays transient messages in a portal (fixed top-right). Use ref.addMessage({ mode, message }) imperatively.
+- Key Features: Imperative API (addMessage), variants (info, error, warning, success), autoClose, autoCloseTime, portal rendering, click to dismiss
+- Types: ToastProps, ToastRefHandle, ToastMessage, ToastVariant
+- Related Components: Alert (inline feedback), Button (trigger), Container (layout)
+
+### MenuList Component
+- File: `docs/MenuList.md`
+- Purpose: Renders a list of navigational items with optional icons, active state highlighting, and customizable layout.
+- Key Features: items (label, value, icon), activeItem, direction (horizontal, vertical), sizes (small, medium, large), variants (light, dark), margin (suffix API), onMenuClick(item), Animated entrance
+- Types: MenuListProps, MenuListItem, MenuListSize, MenuListVariant, MenuListDirection, MenuListMargin
+- Related Components: Dropdown (content), Header (navigation), Container, Typography, Icon, Animated (used internally)
+
+### Header Component
+- File: `docs/Header.md`
+- Purpose: Responsive navigation header with logo, menu items, and customizable left/center/right slots.
+- Key Features: logoUrl, menuItems, activeMenuItem, onMenuItemClick, headerLeft, headerCenter, headerRight, sizes (small, medium, large), variants (light, dark), margin (suffix API), responsive mobile menu
+- Types: HeaderProps, HeaderSize, HeaderVariant, HeaderMargin
+- Related Components: MenuList (center and mobile menu), Avatar (headerRight), Button, Icon, Animated (used internally)
+
+### PageHeader Component
+- File: `docs/PageHeader.md`
+- Purpose: Two-column page header: left (title, subtitle), right (primary CTA, more menu with three-dots icon). For page/section headings and actions.
+- Key Features: title, subtitle (string or ReactNode), primaryCta (ReactNode), moreMenuItems (label, onClick) or moreMenuContent, right column aligned right, className
+- Types: PageHeaderProps, PageHeaderMoreMenuItem
+- Related Components: Button, Typography, Dropdown, Icon (used internally), Container
+
+### BottomSheet Component
+- File: `docs/BottomSheet.md`
+- Purpose: Slides up from the bottom of the screen for additional content, forms, or actions.
+- Key Features: isOpen, onClose, snap points (30%, 60%, 90%), drag-to-close, touch and mouse support, body scroll lock, margin (suffix API)
+- Types: BottomSheetProps, BottomSheetMargin
+- Related Components: Modal, ConfirmDialog, Button, Container, Typography
+
+### Footer Component
+- File: `docs/Footer.md`
+- Purpose: Customizable footer with copyright, optional powered-by link, and custom content via children.
+- Key Features: brandName, poweredByLabel, poweredByLink, children, sizes (small, medium, large), variants (light, dark), margin (suffix API)
+- Types: FooterProps, FooterSize, FooterVariant, FooterMargin
+- Related Components: Container (footer columns), Typography (used internally), Header (app layout)
+
+### AppShell Component
+- File: `docs/AppShell.md`
+- Purpose: Full-page layout combining optional Header (top), Footer (bottom), and MenuList as left sidebar with main content. For dashboard-style apps.
+- Key Features: header (Header props or ReactNode), footer (Footer props or ReactNode), sidebar (AppShellSidebarConfig: items, activeItem, onMenuClick, size, variant), sidebarWidth, responsive (sidebar hidden ≤1024px; use header mobile menu)
+- Types: AppShellProps, AppShellSidebarConfig
+- Related Components: Header, Footer, MenuList (sidebar), Container, Typography, Avatar
+
+## Documentation Format
+
+All documentation files follow a consistent format:
+1. Component name and purpose
+2. Props/Inputs table with types, defaults, and descriptions
+3. TypeScript type definitions
+4. Usage examples covering common use cases
+5. Behavior notes explaining important details
+6. Related components and links
+
+## Quick Reference
+
+| Component | File | Primary Use Case |
+|-----------|------|------------------|
+| Button | `docs/Button.md` | User actions and interactions |
+| Typography | `docs/Typography.md` | Text content and headings |
+| Icon | `docs/Icon.md` | Visual icons and symbols |
+| MediaObject | `docs/MediaObject.md` | Media + content layouts |
+| Avatar | `docs/Avatar.md` | User identity (initials, image, or icon) |
+| Container | `docs/Container.md` | Layout, spacing, and flex structure |
+| Dropdown | `docs/Dropdown.md` | Menus and floating panels |
+| Alert | `docs/Alert.md` | Inline feedback and notices |
+| Spinner | `docs/Spinner.md` | Loading and activity indicator |
+| Stepper | `docs/Stepper.md` | Multi-step flows and wizards |
+| BreadCrumb | `docs/BreadCrumb.md` | Navigation trail and page hierarchy |
+| Accordion | `docs/Accordion.md` | Collapsible panels and FAQ sections |
+| ConfirmDialog | `docs/ConfirmDialog.md` | Confirmation modals and destructive actions |
+| Modal | `docs/Modal.md` | Forms, long content, and custom dialogs |
+| Pagination | `docs/Pagination.md` | Page navigation for tables and lists |
+| Table | `docs/Table.md` | Structured tabular data with optional pagination and mobile view |
+| Badge | `docs/Badge.md` | Status labels, tags, and counts with colored variants |
+| Pills | `docs/Pills.md` | Tags/chips with read-only, edit, and remove modes |
+| Animated | `docs/Animated.md` | Scroll-triggered entrance/exit animations |
+| FormControls | `docs/FormControls.md` | Form primitives (Input, Select, TextArea, Date, Checkbox, etc.) |
+| Toast | `docs/Toast.md` | Transient messages via ref.addMessage |
+| MenuList | `docs/MenuList.md` | Nav menus and link lists with icons |
+| Header | `docs/Header.md` | Responsive navigation header with logo and menu |
+| PageHeader | `docs/PageHeader.md` | Page title, subtitle, primary CTA, and more menu |
+| BottomSheet | `docs/BottomSheet.md` | Slide-up panel for forms and actions |
+| Footer | `docs/Footer.md` | App footer with copyright and optional links |
+| AppShell | `docs/AppShell.md` | Dashboard layout with header, sidebar, footer, and main content |
+
+## Additional Resources
+
+- Component source code: `src/components/`
+- Storybook documentation: Available at the project's Storybook instance
+- Type definitions: `src/types/` and component-specific type exports
+- Storybook static build: `storybook-static/`
+- Component stories: `src/stories/`
+
+## Installation
+
+```bash
+npm install cleanplate
+```
+
+## Usage
+
+```jsx
+import { Button, Typography, Icon, MediaObject, Avatar, Container, Dropdown, Alert, Spinner, Stepper, BreadCrumb, Accordion, ConfirmDialog, Modal, Pagination, Table, Badge, Pills, Animated, FormControls, Toast, MenuList, Header, PageHeader, BottomSheet, Footer, AppShell } from "cleanplate";
+```

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "cleanplate",
-  "version": "0.1.11",
+  "version": "0.2.1",
   "description": "CleanPlate - A Headless React UI Framework",
+  "files": [
+    "dist",
+    "docs",
+    "llms.txt"
+  ],
   "main": "dist/index.js",
   "module": "dist/index.es.js",
   "types": "dist/index.d.ts",