@matteoaliano/forest-ui 0.5.2 → 0.7.0

package/skills/forest-external/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;
-}
-```

package/skills/forest-internal/SKILL.md

@@ -1,94 +0,0 @@
----
-name: forest-internal
-description: Forest UI Design System rules for the Internal (magenta) preset. Enforces correct imports, component usage, and theming with @matteoaliano/forest-ui. Use when the project uses forest-ui, forest-internal preset, or when user builds UI components in a forest-ui project. Triggers on "forest", "forest-ui", "forest internal", "@matteoaliano/forest-ui".
-metadata:
-  author: Forest Design System
-  version: 0.5.2
----
-
-# Forest UI — Internal Preset
-
-## Golden Rules
-
-1. **NEVER import from `@mui/material` directly.** Always import from `@matteoaliano/forest-ui`. All MUI components, layout primitives, transitions, form helpers, and hooks are re-exported. The only exception is `@mui/icons-material` — import icons from there directly.
-2. **ALWAYS wrap your app root with `<ForestProvider>`** — it applies the theme and CSS baseline.
-3. **NEVER use inline colors or spacing values.** Use design tokens or MUI's `sx` prop with theme values (`p: 4`, `backgroundColor: "primary.main"`).
-4. **NEVER create custom component wrappers** for things Forest UI already provides.
-5. **TypeScript is required.** All components export their prop types (e.g. `type ButtonProps`).
-6. **ALWAYS use the Outlined variant of MUI icons.** Import from `@mui/icons-material/*Outlined` (e.g. `CloseOutlined`, `MailOutlined`). Never use filled, Rounded, Sharp, or TwoTone variants.
-
-## Setup
-
-```bash
-npm install @matteoaliano/forest-ui @mui/material @mui/x-data-grid @mui/x-date-pickers @mui/x-charts dayjs @emotion/react @emotion/styled
-```
-
-> **Note:** `@mui/material`, `@mui/x-data-grid`, `@mui/x-date-pickers`, and `@mui/x-charts` are **peer dependencies** — install them but **always import from `@matteoaliano/forest-ui`**, not from these packages directly. Forest UI re-exports everything.
-
-```tsx
-import { ForestProvider } from "@matteoaliano/forest-ui";
-
-function App() {
-  return (
-    <ForestProvider preset="forest-internal">
-      {/* All app content here */}
-    </ForestProvider>
-  );
-}
-```
-
-## Typography & Fonts
-
-- **Aeonik** — the default font for all UI text (headings, body, labels, buttons, etc.)
-- **Aeonik Mono** — use for numeric values: prices, stats, table figures, counters, dates, IDs, code snippets
-- **Alkemy Beta** — use for page titles (h1/hero headings). Not for general UI text
-
-Import the font CSS files you need in your app entry point:
-
-```tsx
-import "@matteoaliano/forest-ui/fonts/aeonik/aeonik.css";
-import "@matteoaliano/forest-ui/fonts/aeonik-mono/aeonik-mono.css";
-import "@matteoaliano/forest-ui/fonts/alkemy-beta/alkemy-beta.css";
-```
-
-## Available Components
-
-**Inputs:** Button, ButtonGroup, TextField, Select + MenuItem, MultiSelect, Checkbox, RadioGroup + Radio, Switch, ToggleButton + ToggleButtonGroup, Fab, IconButton, Autocomplete, Search, DatePicker, Input
-
-**Data Display:** Badge, Chip, Divider, Typography, Tooltip, Logo, Table family (Table, TableHead, TableBody, TableRow, TableCell, TableContainer, TableFooter, TablePagination, TableSortLabel), DataGrid + GridColDef, List family (List, ListItem, ListItemButton, ListItemIcon, ListItemText, ListItemAvatar, ListItemSecondaryAction, ListSubheader), Avatar + AvatarGroup, ImageList + ImageListItem + ImageListItemBar, Rating
-
-**Surfaces:** Accordion family, AppBar + Toolbar + AppBarNavItem, Card family + CardActionArea, Paper, Drawer + SwipeableDrawer
-
-**Feedback:** Alert + AlertTitle, Dialog family, Backdrop, LinearProgress, CircularProgress, Skeleton, Modal, Popover, Snackbar + SnackbarContent, Slider
-
-**Navigation:** Breadcrumbs, Link, Menu + MenuList, Pagination + PaginationItem, Stepper family (Stepper, Step, StepLabel, StepButton, StepConnector, StepContent, StepIcon), Tabs + Tab + TabScrollButton, SidebarNav + SidebarItem + useSidebar, BottomNavigation + BottomNavigationAction, SpeedDial + SpeedDialAction + SpeedDialIcon, MobileStepper
-
-**Layout:** Box, Stack, Grid, Container
-
-**Form Helpers:** FormControl, FormControlLabel, FormGroup, FormHelperText, FormLabel, InputAdornment, InputBase, InputLabel, OutlinedInput, FilledInput
-
-**Transitions:** Collapse, Fade, Grow, Slide, Zoom
-
-**Utilities:** ClickAwayListener, NoSsr, Portal, Popper, TextareaAutosize, SvgIcon, ButtonBase, GlobalStyles
-
-**Hooks:** useMediaQuery, useScrollTrigger, useFormControl, useTheme
-
-**Charts:** BarChart, LineChart, PieChart, ScatterChart, Gauge, SparkLineChart, useChartColors, plus composition primitives (see components.md)
-
-See `references/components.md` for full API details and `references/patterns.md` for code examples.
-
-## Tooltip vs Popover
-
-- **Tooltip** — Use for **text-only hints**. The Tooltip has a dark (black) background and is meant for short, plain-text labels or descriptions. Do not nest rich content inside a Tooltip.
-- **Popover** — Use when you need to display **rich or interactive content** such as Chips, lists, buttons, or any nested components. Popover renders in a neutral surface container that supports arbitrary children.
-
-**Rule of thumb:** If the overlay content is just a string, use `<Tooltip>`. If it contains components, use `<Popover>`.
-
-## Common Anti-Patterns
-
-1. **Importing from `@mui/material`** instead of `@matteoaliano/forest-ui` — all components, hooks, and layout primitives are available from forest-ui
-2. **Hardcoded color values** (`backgroundColor: "#7f56d9"`) instead of theme tokens (`backgroundColor: "primary.main"`)
-3. **Hardcoded spacing** (`padding: "16px"`) instead of theme spacing (`p: 4`)
-4. **Missing `<ForestProvider>`** at the app root — theme won't apply
-5. **Using filled MUI icons** (`Close`) instead of Outlined (`CloseOutlined`)
-6. **Building custom multi-select** instead of using the `<MultiSelect>` component