@matteoaliano/forest-ui 0.3.3 → 0.3.5

package/skills/forest-internal/references/patterns.md

@@ -0,0 +1,256 @@
+# Forest UI — Code Patterns & Anti-Patterns
+
+## 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>
+  );
+}
+```
+
+### MultiSelect with Select All
+
+```tsx
+import { useState } from "react";
+import { MultiSelect } from "@matteoaliano/forest-ui";
+
+const options = [
+  { label: "Bug", value: "bug" },
+  { label: "Enhancement", value: "enhancement" },
+  { label: "New Feature", value: "feature" },
+];
+
+function CategoryFilter() {
+  const [selected, setSelected] = useState<string[]>([]);
+  return (
+    <MultiSelect
+      label="Category"
+      options={options}
+      value={selected}
+      onChange={setSelected}
+    />
+  );
+}
+```
+
+### 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>
+  );
+}
+```
+
+### DataGrid
+
+```tsx
+import { DataGrid, type GridColDef } from "@matteoaliano/forest-ui";
+
+const columns: GridColDef[] = [
+  { field: "id", headerName: "ID", width: 70 },
+  { field: "name", headerName: "Name", flex: 1 },
+  { field: "email", headerName: "Email", flex: 1 },
+];
+
+function UsersGrid({ rows }) {
+  return <DataGrid rows={rows} columns={columns} />;
+}
+```
+
+### 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>
+  );
+}
+```
+
+### Sidebar Navigation
+
+```tsx
+import { SidebarNav, SidebarItem } from "@matteoaliano/forest-ui";
+import DashboardOutlined from "@mui/icons-material/DashboardOutlined";
+import SettingsOutlined from "@mui/icons-material/SettingsOutlined";
+
+function AppShell() {
+  const [open, setOpen] = useState(true);
+  return (
+    <SidebarNav open={open} onOpenChange={setOpen}>
+      <SidebarItem icon={<DashboardOutlined />} label="Dashboard" selected />
+      <SidebarItem icon={<SettingsOutlined />} label="Settings" />
+    </SidebarNav>
+  );
+}
+```
+
+### Charts
+
+Colors are automatically assigned from the theme's 12-series palette. Override with the `colors` prop if needed.
+
+```tsx
+import { BarChart, LineChart, PieChart, useChartColors } from "@matteoaliano/forest-ui";
+
+// Bar chart with striped variant
+<BarChart
+  series={[
+    { data: [10, 20, 30], label: "Current", variant: "solid" },
+    { data: [8, 15, 25], label: "Previous", variant: "striped" },
+  ]}
+  xAxis={[{ data: ["Jan", "Feb", "Mar"], scaleType: "band" }]}
+  height={300}
+/>
+
+// Line chart
+<LineChart
+  series={[{ data: [10, 20, 30], label: "Revenue" }]}
+  xAxis={[{ data: ["Jan", "Feb", "Mar"], scaleType: "band" }]}
+  height={300}
+/>
+
+// Pie chart
+<PieChart
+  series={[{ data: [
+    { id: 0, value: 40, label: "Desktop" },
+    { id: 1, value: 30, label: "Mobile" },
+    { id: 2, value: 30, label: "Tablet" },
+  ]}]}
+  height={300}
+/>
+
+// Access chart colors programmatically
+const colors = useChartColors(3);
+```
+
+## Storybook Controls
+
+When adding argTypes to stories:
+
+```tsx
+const meta: Meta<typeof Button> = {
+  component: Button,
+  argTypes: {
+    variant: {
+      control: "select",
+      options: ["contained", "outlined", "text"],
+    },
+    color: {
+      control: "select",
+      options: ["primary", "secondary", "error", "warning", "success", "info"],
+    },
+    disabled: { control: "boolean" },
+  },
+};
+```
+
+**Control types:** `"select"` with `options`, `"boolean"`, `"number"`, `"text"`.
+
+## 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
+
+// WRONG: using filled (default) icons
+import CloseIcon from "@mui/icons-material/Close";
+
+// CORRECT: always use Outlined variant
+import CloseIcon from "@mui/icons-material/CloseOutlined";
+
+// CORRECT: use theme tokens
+<Box sx={{ backgroundColor: "primary.main", p: 4 }} />
+
+// WRONG: manually building multi-select with Select + Checkbox
+// CORRECT: use the MultiSelect component
+<MultiSelect options={options} value={value} onChange={setValue} />
+```
+
+## TypeScript Props
+
+Every component exports its props type:
+
+```tsx
+import { Button, type ButtonProps } from "@matteoaliano/forest-ui";
+
+interface MyButtonProps extends ButtonProps {
+  analyticsId: string;
+}
+```