cleanplate 0.2.0 → 0.2.2

package/AGENTS.md

@@ -0,0 +1,45 @@
+# Agent instructions — CleanPlate (React)
+
+Use this file when generating or refactoring UI in **this frontend project**. This app uses **[CleanPlate](https://www.npmjs.com/package/cleanplate)** (`cleanplate` on npm): a headless React component library.
+
+## Where to load full documentation
+
+1. **Index (start here):** `node_modules/cleanplate/llms.txt`  
+   Overview, AI-oriented guidelines, and pointers to each component doc.
+
+2. **Component reference:** `node_modules/cleanplate/docs/<ComponentName>.md`  
+   Example: `docs/Button.md`, `docs/PageHeader.md` — props, types, examples, behavior.
+
+If `node_modules` is missing, run install first. Optionally use a **semver-pinned CDN** mirror of the same files (substitute your installed version):  
+`https://unpkg.com/cleanplate@<version>/llms.txt` · `https://unpkg.com/cleanplate@<version>/docs/Button.md`
+
+Human-facing demos: [Storybook — cleanplate.sivadass.in](https://cleanplate.sivadass.in)
+
+## Imports and styling
+
+- Import components as **named exports** from `'cleanplate'`.
+- Include framework styles **once** at the app root:  
+  `import "cleanplate/dist/index.css";`
+- **`Icon`** uses [Google Material Symbols](https://fonts.google.com/icons); ensure the Material Symbols font is loaded in the app (see `docs/Icon.md`).
+
+## Rules for generated code
+
+- Prefer **component props** for layout, spacing, and alignment — **avoid inline `style`** when CleanPlate exposes a prop for it.
+- **Spacing (`margin`, `padding`, `gap`):** use the **suffix-only** API everywhere it applies — e.g. `margin="b-2"`, `padding="4"`, `gap="2"`. Do **not** pass CSS-class-style prefixes (`m-`, `p-`, `g-`) in prop values.
+- **`Typography`:** use `align` for text alignment, `isBold` for bold, `margin` for spacing — not equivalent inline styles unless there is no prop.
+
+Correct vs avoid:
+
+```jsx
+<Typography variant="h4" align="center" margin="b-2">Login</Typography>
+```
+
+```jsx
+<Typography variant="h4" style={{ textAlign: "center", marginBottom: "1rem" }}>Login</Typography>
+```
+
+## Workflow
+
+1. Read `node_modules/cleanplate/llms.txt` for global rules and the right `docs/*.md` path.  
+2. Open the matching `docs/<Component>.md` before inventing props or patterns.  
+3. Match **TypeScript types** exported from `'cleanplate'` when the project uses TypeScript.

package/README.md

@@ -1,104 +1,249 @@
-# cleanplate
+# CleanPlate
 
-CleanPlate - Headless React UI Framework
+**A headless React UI framework** — reusable, accessible components you can style to match your brand. No opinionated theme; you bring the look and feel.
 
-### Installation
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Available components](#available-components)
+- [Documentation](#documentation)
+- [TypeScript](#typescript)
+- [LLM / AI-friendly docs & agents](#llm--ai-friendly-docs--agents)
+- [`AGENTS.md` in your app repo](#agentsmd-in-your-app-repo)
+- [GitHub MCP server](#github-mcp-server)
 
-```
-npm install cleanplate
-```
+---
 
-Check all versions at [NPM](https://www.npmjs.com/package/cleanplate).
+## Requirements
 
-### Usage
+- **React** 18 or higher
+- **React DOM** 18 or higher
 
-All components can be consumed by `import` using their respective names from `cleanplate` package.
+---
 
-#### Initial Setup
+## Installation
 
-Import the CSS Reset and minimal cleanplate styles at top most level or root level.
-
-```
-import "cleanplate/dist/index.css";
+```bash
+npm install cleanplate
 ```
 
-#### Button
+Or with Yarn:
 
+```bash
+yarn add cleanplate
 ```
-import { Button } from "cleanplate";
 
-<Button variant="primary" onClick={() => {}}>Save</Button>
-<Button variant="secondary" onClick={() => {}}>Save</Button>
-<Button variant="nude" onClick={() => {}}>Save</Button>
-<Button variant="special" onClick={() => {}}>Save</Button>
-```
+Published packages: [npm — cleanplate](https://www.npmjs.com/package/cleanplate)
 
-#### Typography
+---
 
-```
-import { Typography } from "cleanplate";
+## Quick start
+
+### 1. Add styles
 
-<Typography variant="h1">Hello World!</Typography>
-<Typography variant="h2">Hello World!</Typography>
-<Typography variant="h3">Hello World!</Typography>
-<Typography variant="h4">Hello World!</Typography>
-<Typography variant="h5">Hello World!</Typography>
-<Typography variant="h6">Hello World!</Typography>
-<Typography variant="p">Hello World!</Typography>
-<Typography variant="small">Hello World!</Typography>
+Import the reset and base styles **once** at your app root (e.g. `main.jsx`, `App.jsx`, or `index.js`):
 
+```jsx
+import "cleanplate/dist/index.css";
 ```
 
-#### Badge
+### 2. Import and use components
 
-```
-import { Badge } from "cleanplate";
+All components are **named exports** from `cleanplate`:
+
+```jsx
+import { Button, Typography, Container } from "cleanplate";
 
-<Badge label="New" />
+function App() {
+  return (
+    <Container padding="4">
+      <Typography variant="h1">Hello</Typography>
+      <Button variant="solid" onClick={() => alert("Saved!")}>
+        Save
+      </Button>
+    </Container>
+  );
+}
 ```
 
-#### AppShell
+### Example: Button
 
-```
-import { AppShell } from "cleanplate";
+```jsx
+import { Button } from "cleanplate";
 
-<AppShell />
+<Button variant="solid">Primary action</Button>
+<Button variant="outline">Secondary</Button>
+<Button variant="ghost">Tertiary</Button>
 ```
 
-#### Form Controls
+Variants: `solid`, `outline`, `ghost`, `icon`. Sizes: `small`, `medium`.
+
+### Example: Typography
 
+```jsx
+import { Typography } from "cleanplate";
+
+<Typography variant="h1">Heading 1</Typography>
+<Typography variant="h4">Heading 4</Typography>
+<Typography variant="p">Body paragraph.</Typography>
 ```
-import { FormControl } from "cleanplate";
 
-<FormControl.Input
-    name="email"
-    onChange={(e) => handleChange(e)}
-    value={values.email}
+Variants: `h1`–`h6`, `p`, `span`, `small`.
+
+### Example: Form controls
+
+```jsx
+import { FormControls } from "cleanplate";
+
+<FormControls.Input
+  label="Email"
+  value={email}
+  onChange={(e) => setEmail(e.target.value)}
 />
 
-<FormControl.TextArea
-    name="bio"
-    onChange={(e) => handleChange(e)}
-    value={values.bio}
+<FormControls.Select
+  label="Country"
+  options={[
+    { label: "United States", value: "us" },
+    { label: "Canada", value: "ca" },
+  ]}
+  value={country}
+  onChange={(e) => setCountry(e.target.value)}
 />
 ```
 
-#### Icon
+Other form primitives: `TextArea`, `Checkbox`, `Radio`, `Date`, `File`, `Toggle`, etc.
 
-```
+### Example: Icon
+
+Uses [Google Material Symbols](https://fonts.google.com/icons). Include the font in your app; then:
+
+```jsx
 import { Icon } from "cleanplate";
 
-<Icon name="settings" size="small" color="balck">
+<Icon name="settings" size="small" color="black" />
+<Icon name="check_circle" size="medium" />
+```
+
+---
+
+## Available components
+
+| Component      | Use case |
+|----------------|----------|
+| Accordion      | Collapsible panels, FAQ sections |
+| Alert          | Inline feedback (success, error, warning, info) |
+| Animated       | Scroll-triggered animations |
+| AppShell       | Full-page layout with Header, Footer, sidebar |
+| Avatar         | User initials, image, or icon |
+| Badge          | Status labels, tags |
+| BottomSheet    | Slide-up panel |
+| BreadCrumb     | Navigation trail |
+| Button         | Actions and buttons |
+| ConfirmDialog  | Confirmation modals |
+| Container      | Layout, spacing, flex |
+| Dropdown       | Menus, floating panels |
+| Footer         | App footer |
+| FormControls   | Input, Select, TextArea, Checkbox, etc. |
+| Header         | App header with nav |
+| Icon           | Material Symbols icons |
+| MediaObject    | Media + title + description |
+| MenuList       | Navigation lists |
+| Modal          | Dialogs, overlays |
+| PageHeader     | Page title + CTA + more menu |
+| Pagination     | Page navigation |
+| Pills          | Tags/chips |
+| ProgressBar    | Progress indicator |
+| Spinner        | Loading indicator |
+| Stepper        | Multi-step flows |
+| Table          | Tabular data |
+| Toast          | Transient messages |
+| Typography     | Headings and text |
+
+Import any of them from `cleanplate`:
+
+```jsx
+import {
+  Button,
+  Typography,
+  Container,
+  Header,
+  PageHeader,
+  BreadCrumb,
+  Table,
+  FormControls,
+  // ... etc.
+} from "cleanplate";
+```
+
+---
+
+## Documentation
+
+- **Storybook** — Interactive playground and docs for every component:  
+  [https://cleanplate.sivadass.in](https://cleanplate.sivadass.in)
+- **GitHub** — Source and issue tracker:  
+  [github.com/sivadass/cleanplate](https://github.com/sivadass/cleanplate)
+
+---
+
+## TypeScript
+
+CleanPlate is written in TypeScript and ships type definitions. Types are included in the package (`dist/index.d.ts`). No extra `@types` package needed.
+
+```tsx
+import { Button } from "cleanplate";
+import type { ButtonProps } from "cleanplate";
 ```
 
-View all the available icon names from [Google Material Icons](https://fonts.google.com/icons).
+---
 
-#### Modal
+## LLM / AI-friendly docs & agents
 
-```
-import { Modal } from "cleanplate";
-```
+Documentation for **coding agents** and LLMs ships with the npm package alongside the compiled library.
+
+### After `npm install cleanplate`
+
+- **Index:** `node_modules/cleanplate/llms.txt` — component list, conventions, and links to each doc file.
+- **Per-component docs:** `node_modules/cleanplate/docs/<ComponentName>.md` — props, types, examples, behavior.
+
+**Agent workflow:** read `node_modules/cleanplate/llms.txt` first, then open the specific files under `node_modules/cleanplate/docs/` (not imports alone).
+
+### Version-pinned URLs (no download step)
+
+CDN mirrors of the published tarball work well for prompts and CI; pin the semver you depend on:
+
+- **Latest:** [unpkg — `llms.txt`](https://unpkg.com/cleanplate@latest/llms.txt) · [jsDelivr — `llms.txt`](https://cdn.jsdelivr.net/npm/cleanplate@latest/llms.txt)
+- **Pinned example:** `https://unpkg.com/cleanplate@0.2.0/llms.txt` and `https://unpkg.com/cleanplate@0.2.0/docs/Button.md` (substitute your installed version)
+
+Human-facing Storybook: [cleanplate.sivadass.in](https://cleanplate.sivadass.in).
+
+### `AGENTS.md` in your app repo
+
+Many coding agents automatically read **`AGENTS.md`** at the **root of the repository** they are working in. To give agents CleanPlate-specific context in **your** frontend project:
+
+1. Copy the template into your app root:
+   - From this repo: [`AGENTS.md`](https://github.com/sivadass/cleanplate/blob/main/AGENTS.md) (raw: [`AGENTS.md` raw](https://raw.githubusercontent.com/sivadass/cleanplate/main/AGENTS.md))
+   - Or from an install: `node_modules/cleanplate/AGENTS.md` → paste/rename as `AGENTS.md` at your project root  
+2. Commit `AGENTS.md` so teammates and agents see the same rules.
+
+The published tarball also includes **`AGENTS.md`** next to `llms.txt` for easy copying after `npm install`.
+
+---
+
+## GitHub MCP server
+
+This repository is **compatible with the [GitHub MCP server](https://github.com/github/github-mcp-server)** (Model Context Protocol). The GitHub MCP server lets AI assistants (e.g. in Cursor or VS Code) access GitHub—repos, issues, pull requests, and workflows—so you can work with this codebase using natural language.
+
+- **Compatibility:** CleanPlate is a standard GitHub repo with no special constraints. The GitHub MCP server can read and interact with it once connected.
+- **Setup:** Add the GitHub MCP server in your editor:
+  - **Cursor:** Settings → Tools & MCP → add the GitHub MCP server (or add it to `~/.cursor/mcp.json`). Use [Cursor’s MCP docs](https://cursor.com/docs/context/mcp) for the exact config.
+  - **VS Code (1.101+):** Use the MCP servers UI or add the server to `.vscode/mcp.json`. See [GitHub: Using the GitHub MCP Server](https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp/use-the-github-mcp-server).
+- **Auth:** You’ll need to authenticate with GitHub (OAuth or a Personal Access Token with the scopes the MCP server needs).
+
+No project-level MCP config is required; configure the GitHub MCP server in your editor or global config and point it at this repo.
+
+---
 
-### Documentation & Demo
+## License
 
-Storybook playground is available for all components at [https://cleanplate.sivadass.in](https://cleanplate.sivadass.in).
+MIT © Sivadass N