@matteoaliano/forest-ui 0.6.0 → 0.7.0

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

@@ -1,405 +0,0 @@
-# Forest UI — Code Patterns & Anti-Patterns
-
-## Code Patterns
-
-### Form Layout
-
-```tsx
-import { TextField, Button, Select, MenuItem, Checkbox, Box } from "@matteoaliano/forest-ui";
-
-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>
-  );
-}
-```
-
-### App Shell (AppBar + Sidebar Navigation)
-
-The standard application layout: a full-width AppBar at the top with a SidebarNav below it. The Toolbar uses three equal `flex: 1` columns so the Search stays visually centered. The sidebar drawer uses `position: relative` to flow inside the layout instead of overlaying as a fixed panel.
-
-```tsx
-import { useState } from "react";
-import {
-  AppBar, Toolbar, Logo, Search, IconButton, Badge,
-  SidebarNav, SidebarItem, List, Typography, Box, Avatar,
-} from "@matteoaliano/forest-ui";
-import NotificationsOutlined from "@mui/icons-material/NotificationsOutlined";
-import SettingsOutlined from "@mui/icons-material/SettingsOutlined";
-import HomeOutlined from "@mui/icons-material/HomeOutlined";
-import BarChartOutlined from "@mui/icons-material/BarChartOutlined";
-import PeopleOutlined from "@mui/icons-material/PeopleOutlined";
-
-function AppShell({ children }) {
-  const [sidebarOpen, setSidebarOpen] = useState(true);
-
-  return (
-    <Box sx={{ display: "flex", flexDirection: "column", height: "100vh" }}>
-      {/* ── App Bar ── */}
-      <AppBar
-        position="sticky"
-        elevation={0}
-        sx={{ zIndex: (theme) => theme.zIndex.drawer + 1 }}
-      >
-        <Toolbar variant="dense" sx={{ px: { xs: "16px", sm: "16px" } }}>
-          {/* Left — Logo */}
-          <Box sx={{ flex: 1, display: "flex", alignItems: "center" }}>
-            <Logo product="wsuite" />
-          </Box>
-          {/* Center — Search (always visually centered) */}
-          <Box sx={{ flex: 1, display: "flex", justifyContent: "center" }}>
-            <Search size="small" sx={{ width: "100%", maxWidth: 480 }} />
-          </Box>
-          {/* Right — Actions */}
-          <Box sx={{ flex: 1, display: "flex", alignItems: "center", justifyContent: "flex-end", gap: 1 }}>
-            <IconButton size="small" color="inherit">
-              <Badge color="error" variant="dot">
-                <NotificationsOutlined fontSize="small" />
-              </Badge>
-            </IconButton>
-            <IconButton size="small" color="inherit">
-              <SettingsOutlined fontSize="small" />
-            </IconButton>
-            <Avatar sx={{ width: 28, height: 28, fontSize: 13 }}>MA</Avatar>
-          </Box>
-        </Toolbar>
-      </AppBar>
-
-      {/* ── Body: Sidebar + Content ── */}
-      <Box sx={{ display: "flex", flexGrow: 1, overflow: "hidden" }}>
-        <SidebarNav
-          open={sidebarOpen}
-          onOpenChange={setSidebarOpen}
-          sx={{
-            height: "100%",
-            "& .MuiDrawer-paper": { position: "relative", height: "100%" },
-          }}
-        >
-          <List>
-            <SidebarItem icon={<HomeOutlined />} label="Home" selected />
-            <SidebarItem icon={<BarChartOutlined />} label="Analytics" />
-            <SidebarItem icon={<PeopleOutlined />} label="Users" />
-            <SidebarItem icon={<SettingsOutlined />} label="Settings" />
-          </List>
-        </SidebarNav>
-
-        <Box
-          component="main"
-          sx={{ flexGrow: 1, p: 3, overflow: "auto", backgroundColor: "background.paper" }}
-        >
-          {children}
-        </Box>
-      </Box>
-    </Box>
-  );
-}
-```
-
-**Key patterns:**
-- `Toolbar variant="dense"` — 48px height instead of 64px
-- Three `flex: 1` columns in Toolbar — keeps Search centered regardless of left/right content width
-- `px: { xs: "16px", sm: "16px" }` on Toolbar — aligns logo with sidebar icons (overrides MUI's responsive 24px default)
-- `position: "relative"` on drawer paper — makes sidebar flow in layout, not overlay
-- `height: "100%"` on SidebarNav — sidebar border extends full height
-- `backgroundColor: "background.paper"` on content — contrasts with sidebar/AppBar background
-
-### Detail Drawer
-
-Use the `Drawer` component when a user clicks an item (table row, card, list entry) to view or edit its details in a side panel. The Drawer defaults to `anchor="right"` and `hideBackdrop={true}`, so it opens on the right without dimming the page — the user retains full visibility of the content behind it.
-
-```tsx
-import { useState } from "react";
-import {
-  Drawer, Box, Typography, IconButton, Divider, Chip, Stack,
-  DataGrid, type GridColDef,
-} from "@matteoaliano/forest-ui";
-import CloseOutlined from "@mui/icons-material/CloseOutlined";
-
-function KeywordTable({ rows, columns }: { rows: any[]; columns: GridColDef[] }) {
-  const [selected, setSelected] = useState<any | null>(null);
-
-  return (
-    <Box sx={{ display: "flex", height: "100%" }}>
-      <Box sx={{ flex: 1, minWidth: 0 }}>
-        <DataGrid
-          rows={rows}
-          columns={columns}
-          onRowClick={(params) => setSelected(params.row)}
-        />
-      </Box>
-
-      <Drawer open={!!selected} onClose={() => setSelected(null)}>
-        {selected && (
-          <Box sx={{ width: 400, p: 3 }}>
-            {/* Header */}
-            <Box sx={{ display: "flex", justifyContent: "space-between", alignItems: "center", mb: 2 }}>
-              <Typography variant="h6">{selected.name}</Typography>
-              <IconButton size="small" onClick={() => setSelected(null)}>
-                <CloseOutlined />
-              </IconButton>
-            </Box>
-            <Divider sx={{ mb: 2 }} />
-
-            {/* Detail content */}
-            <Stack direction="row" spacing={1} sx={{ mb: 3 }}>
-              <Chip label={`${selected.volume} vol`} size="small" />
-              <Chip label={selected.category} size="small" variant="outlined" />
-            </Stack>
-            <Typography variant="body2" color="text.secondary">
-              {selected.description}
-            </Typography>
-          </Box>
-        )}
-      </Drawer>
-    </Box>
-  );
-}
-```
-
-**Key points:**
-- `anchor="right"` and `hideBackdrop={true}` are the Forest defaults — no need to set them
-- The Drawer takes full viewport height and overlays the right side of the page
-- Always include a close button in the Drawer header
-- Set a fixed `width` on the Drawer content (e.g. 400px)
-- The content behind the Drawer remains fully visible and interactive
-
-### 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} />
-
-// WRONG: inline detail panel — a flex Box that sits inside the content area
-// This is not a design system pattern and creates inconsistent layouts
-<Box sx={{ display: "flex" }}>
-  <Box sx={{ flex: 1 }}><DataGrid ... /></Box>
-  {selected && (
-    <Box sx={{ width: 400, borderLeft: 1, borderColor: "divider", p: 2 }}>
-      {/* detail content sitting next to the table */}
-    </Box>
-  )}
-</Box>
-
-// CORRECT: use the Drawer component for detail panels
-// It opens full viewport height on the right, without a backdrop
-<Drawer open={!!selected} onClose={() => setSelected(null)}>
-  <Box sx={{ width: 400, p: 3 }}>
-    {/* detail content */}
-  </Box>
-</Drawer>
-```
-
-## TypeScript Props
-
-Every component exports its props type:
-
-```tsx
-import { Button, type ButtonProps } from "@matteoaliano/forest-ui";
-
-interface MyButtonProps extends ButtonProps {
-  analyticsId: string;
-}
-```