@matteoaliano/forest-ui 0.1.0

package/FOREST_AI_GUIDELINES.md

@@ -0,0 +1,277 @@
+# Forest UI — AI Development Guidelines
+
+> **This file is auto-generated from the `forest-ui` package.**
+> Run `npx forest-ui sync` to update it.
+
+---
+
+## 1. Golden Rules
+
+1. **NEVER import from `@mui/material` directly.** Always import from `forest-ui`.
+2. **ALWAYS wrap your app root with `<ForestProvider>`** — it applies the theme and CSS baseline.
+3. **NEVER use inline colors or spacing values.** Use the exported design tokens or MUI's `sx` prop with theme values.
+4. **NEVER create custom component wrappers** for things Forest UI already provides.
+5. **TypeScript is required.** All components export their prop types.
+
+---
+
+## 2. Installation & Setup
+
+```bash
+npm install @matteoaliano/forest-ui @mui/material @emotion/react @emotion/styled
+```
+
+```tsx
+// App root — REQUIRED
+import { ForestProvider } from "@matteoaliano/forest-ui";
+
+function App() {
+  return (
+    <ForestProvider>
+      {/* All app content here */}
+    </ForestProvider>
+  );
+}
+```
+
+---
+
+## 3. Component Reference
+
+### Import Pattern
+
+```tsx
+// ✅ CORRECT — import from forest-ui
+import { Button, TextField, Alert } from "@matteoaliano/forest-ui";
+
+// ❌ WRONG — never import from @mui/material
+import Button from "@mui/material/Button";
+```
+
+### Available Components
+
+#### Inputs
+| Component | Import | Key Props |
+|-----------|--------|-----------|
+| `Button` | `import { Button } from "@matteoaliano/forest-ui"` | `variant: "contained" \| "outlined" \| "text"`, `size`, `color`, `disabled` |
+| `ButtonGroup` | `import { ButtonGroup } from "@matteoaliano/forest-ui"` | `variant`, `size`, `orientation` |
+| `TextField` | `import { TextField } from "@matteoaliano/forest-ui"` | `variant`, `size`, `label`, `error`, `helperText`, `fullWidth` |
+| `Select` | `import { Select, MenuItem } from "@matteoaliano/forest-ui"` | `label`, `value`, `onChange` |
+| `Checkbox` | `import { Checkbox } from "@matteoaliano/forest-ui"` | `checked`, `onChange`, `disabled` |
+| `RadioGroup` + `Radio` | `import { RadioGroup, Radio } from "@matteoaliano/forest-ui"` | `value`, `onChange`, `row` |
+| `Switch` | `import { Switch } from "@matteoaliano/forest-ui"` | `checked`, `onChange`, `disabled` |
+| `ToggleButton` + `ToggleButtonGroup` | `import { ToggleButton, ToggleButtonGroup } from "@matteoaliano/forest-ui"` | `value`, `exclusive`, `onChange` |
+| `Fab` | `import { Fab } from "@matteoaliano/forest-ui"` | `variant: "circular" \| "extended"`, `size`, `color` |
+| `Autocomplete` | `import { Autocomplete } from "@matteoaliano/forest-ui"` | `options`, `renderInput`, `freeSolo` |
+
+#### Data Display
+| Component | Import | Key Props |
+|-----------|--------|-----------|
+| `Badge` | `import { Badge } from "@matteoaliano/forest-ui"` | `badgeContent`, `color`, `variant: "standard" \| "dot"` |
+| `Chip` | `import { Chip } from "@matteoaliano/forest-ui"` | `label`, `variant: "filled" \| "outlined"`, `onDelete`, `size` |
+| `Divider` | `import { Divider } from "@matteoaliano/forest-ui"` | `orientation`, `variant`, `children` (for text dividers) |
+| `Typography` | `import { Typography } from "@matteoaliano/forest-ui"` | `variant: "h1"-"h6" \| "subtitle1" \| "body1" \| "caption" \| "overline"` |
+| `Tooltip` | `import { Tooltip } from "@matteoaliano/forest-ui"` | `title`, `placement`, `arrow` |
+| `Table` family | `import { Table, TableHead, TableBody, TableRow, TableCell, TableContainer } from "@matteoaliano/forest-ui"` | Standard table composition |
+| `List` family | `import { List, ListItem, ListItemButton, ListItemIcon, ListItemText, ListItemAvatar, ListSubheader } from "@matteoaliano/forest-ui"` | Standard list composition |
+
+#### Feedback
+| Component | Import | Key Props |
+|-----------|--------|-----------|
+| `Alert` + `AlertTitle` | `import { Alert, AlertTitle } from "@matteoaliano/forest-ui"` | `severity: "success" \| "info" \| "warning" \| "error"`, `variant` |
+| `Dialog` family | `import { Dialog, DialogTitle, DialogContent, DialogActions, DialogContentText } from "@matteoaliano/forest-ui"` | `open`, `onClose` |
+| `Backdrop` | `import { Backdrop } from "@matteoaliano/forest-ui"` | `open`, `onClick` |
+| `LinearProgress` | `import { LinearProgress } from "@matteoaliano/forest-ui"` | `variant: "indeterminate" \| "determinate"`, `value` |
+| `CircularProgress` | `import { CircularProgress } from "@matteoaliano/forest-ui"` | `variant: "indeterminate" \| "determinate"`, `value` |
+| `Skeleton` | `import { Skeleton } from "@matteoaliano/forest-ui"` | `variant: "text" \| "circular" \| "rectangular" \| "rounded"`, `width`, `height` |
+| `Snackbar` | `import { Snackbar } from "@matteoaliano/forest-ui"` | `open`, `autoHideDuration`, `onClose`, `message` |
+
+---
+
+## 4. Theme & Design Tokens
+
+### Accessing Tokens
+
+```tsx
+// Method 1: Via the sx prop (preferred)
+<Box sx={{ p: 2, borderRadius: 2, color: "text.primary" }} />
+
+// Method 2: Import raw token values (rare, for edge cases)
+import { colors, spacing, radius } from "@matteoaliano/forest-ui";
+```
+
+### Color Palette
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `primary.main` | `#7f56d9` (brand.600) | Primary actions, links, active states |
+| `primary.light` | `#9e77ed` (brand.500) | Hover states |
+| `primary.dark` | `#6941c6` (brand.700) | Pressed states |
+| `secondary.main` | `#475467` (gray.600) | Secondary actions |
+| `error.main` | `#d92d20` | Destructive actions, error states |
+| `warning.main` | `#dc6803` | Warnings |
+| `success.main` | `#079455` | Success states |
+| `info.main` | `#0ba5ec` | Informational |
+| `text.primary` | `#101828` (gray.900) | Main text |
+| `text.secondary` | `#475467` (gray.600) | Supporting text |
+| `background.default` | `#ffffff` | Page background |
+| `background.paper` | `#ffffff` | Card/surface background |
+| `divider` | `#eaecf0` (gray.200) | Borders and dividers |
+
+### Spacing Scale
+
+Use the MUI spacing multiplier: `theme.spacing(1) = 4px`
+
+| Token | px | Usage |
+|-------|-----|-------|
+| `spacing(1)` | 4px | Tight gaps |
+| `spacing(2)` | 8px | Component internal padding |
+| `spacing(3)` | 12px | Small gaps |
+| `spacing(4)` | 16px | Standard section spacing |
+| `spacing(6)` | 24px | Medium section spacing |
+| `spacing(8)` | 32px | Large section spacing |
+
+### Border Radius
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `borderRadius: 1` | 4px | Small elements (chips, badges) |
+| `borderRadius: 2` | 8px | Buttons, inputs |
+| `borderRadius: 3` | 12px | Cards, dialogs |
+
+---
+
+## 5. Code Patterns
+
+### Form Layout
+
+```tsx
+import { TextField, Button, Select, MenuItem, Checkbox } from "@matteoaliano/forest-ui";
+import Box from "@mui/material/Box"; // Box, Stack, Grid are OK from MUI
+
+function ContactForm() {
+  return (
+    <Box sx={{ display: "flex", flexDirection: "column", gap: 3 }}>
+      <TextField label="Name" fullWidth />
+      <TextField label="Email" type="email" fullWidth />
+      <Select label="Subject" fullWidth>
+        <MenuItem value="support">Support</MenuItem>
+        <MenuItem value="sales">Sales</MenuItem>
+      </Select>
+      <Button variant="contained" type="submit">
+        Send
+      </Button>
+    </Box>
+  );
+}
+```
+
+### Data Table
+
+```tsx
+import {
+  Table, TableContainer, TableHead, TableBody, TableRow, TableCell,
+} from "@matteoaliano/forest-ui";
+
+function UsersTable({ users }) {
+  return (
+    <TableContainer>
+      <Table>
+        <TableHead>
+          <TableRow>
+            <TableCell>Name</TableCell>
+            <TableCell>Email</TableCell>
+          </TableRow>
+        </TableHead>
+        <TableBody>
+          {users.map((u) => (
+            <TableRow key={u.id}>
+              <TableCell>{u.name}</TableCell>
+              <TableCell>{u.email}</TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </TableContainer>
+  );
+}
+```
+
+### Feedback Pattern
+
+```tsx
+import { Alert, AlertTitle, Snackbar } from "@matteoaliano/forest-ui";
+
+// Inline feedback
+<Alert severity="error">
+  <AlertTitle>Error</AlertTitle>
+  Something went wrong.
+</Alert>
+
+// Toast notification
+<Snackbar open={open} autoHideDuration={4000} onClose={handleClose}>
+  <Alert severity="success" variant="filled">Saved!</Alert>
+</Snackbar>
+```
+
+### Confirmation Dialog
+
+```tsx
+import { Dialog, DialogTitle, DialogContent, DialogActions, DialogContentText, Button } from "@matteoaliano/forest-ui";
+
+function ConfirmDialog({ open, onClose, onConfirm }) {
+  return (
+    <Dialog open={open} onClose={onClose}>
+      <DialogTitle>Confirm</DialogTitle>
+      <DialogContent>
+        <DialogContentText>Are you sure?</DialogContentText>
+      </DialogContent>
+      <DialogActions>
+        <Button variant="outlined" onClick={onClose}>Cancel</Button>
+        <Button onClick={onConfirm}>Confirm</Button>
+      </DialogActions>
+    </Dialog>
+  );
+}
+```
+
+---
+
+## 6. Anti-Patterns
+
+```tsx
+// ❌ WRONG: importing from @mui/material
+import Button from "@mui/material/Button";
+
+// ❌ WRONG: hardcoded colors
+<Box sx={{ backgroundColor: "#7f56d9" }} />
+
+// ❌ WRONG: hardcoded spacing
+<Box sx={{ padding: "16px" }} />
+
+// ❌ WRONG: forgetting ForestProvider
+ReactDOM.render(<App />, root); // theme won't apply
+
+// ✅ CORRECT: use theme tokens
+<Box sx={{ backgroundColor: "primary.main", p: 4 }} />
+```
+
+> **Note:** Layout primitives like `Box`, `Stack`, `Grid`, and `Container` should still be imported from `@mui/material` — Forest UI does not re-export these because they have no custom styling.
+
+---
+
+## 7. TypeScript Props
+
+Every component exports its props type:
+
+```tsx
+import { Button, type ButtonProps } from "@matteoaliano/forest-ui";
+
+interface MyButtonProps extends ButtonProps {
+  analyticsId: string;
+}
+```
+
+---
+
+*Generated from forest-ui v0.1.0*

package/bin/sync.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+/**
+ * forest-ui sync
+ *
+ * Copies FOREST_AI_GUIDELINES.md into the AI-tool config directories
+ * of the consuming project so coding assistants automatically follow
+ * Forest UI conventions.
+ *
+ * Supported targets:
+ *   .claude/forest-ui.md      — Claude Code
+ *   .cursor/rules/forest-ui.mdc — Cursor
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Locate the guidelines file shipped with the package
+const guidelinesPath = resolve(__dirname, "..", "FOREST_AI_GUIDELINES.md");
+
+if (!existsSync(guidelinesPath)) {
+    console.error("❌ Could not find FOREST_AI_GUIDELINES.md in the forest-ui package.");
+    process.exit(1);
+}
+
+const guidelines = readFileSync(guidelinesPath, "utf-8");
+
+// Find the consuming project root (walk up until we find package.json)
+function findProjectRoot(startDir) {
+    let dir = startDir;
+    while (dir !== dirname(dir)) {
+        if (existsSync(resolve(dir, "package.json"))) {
+            // Skip if this is the forest-ui package itself
+            try {
+                const pkg = JSON.parse(readFileSync(resolve(dir, "package.json"), "utf-8"));
+                if (pkg.name !== "@matteoaliano/forest-ui") return dir;
+            } catch {
+                return dir;
+            }
+        }
+        dir = dirname(dir);
+    }
+    return process.cwd();
+}
+
+const projectRoot = findProjectRoot(process.cwd());
+
+// Define sync targets
+const targets = [
+    {
+        name: "Claude Code",
+        dir: resolve(projectRoot, ".claude"),
+        file: "forest-ui.md",
+    },
+    {
+        name: "Cursor",
+        dir: resolve(projectRoot, ".cursor", "rules"),
+        file: "forest-ui.mdc",
+    },
+];
+
+console.log(`\n🌲 Forest UI — Syncing AI guidelines\n`);
+console.log(`   Project root: ${projectRoot}\n`);
+
+let synced = 0;
+
+for (const target of targets) {
+    try {
+        mkdirSync(target.dir, { recursive: true });
+
+        // For Cursor .mdc files, prepend frontmatter
+        let content = guidelines;
+        if (target.file.endsWith(".mdc")) {
+            content =
+                `---\ndescription: Forest UI Design System guidelines — components, tokens, and patterns\nglobs: **/*.{ts,tsx,js,jsx}\nalwaysApply: false\n---\n\n` +
+                guidelines;
+        }
+
+        writeFileSync(resolve(target.dir, target.file), content, "utf-8");
+        console.log(`   ✅ ${target.name} → ${target.dir}/${target.file}`);
+        synced++;
+    } catch (err) {
+        console.log(`   ⚠️  ${target.name} — skipped (${err.message})`);
+    }
+}
+
+console.log(`\n   Synced to ${synced}/${targets.length} targets.\n`);