nurosys-agents 2.0.0

package/.agent/monolith/skills/vuexy-component-guide/reference.md

@@ -0,0 +1,1036 @@
+# VueXY MUI Component Reference
+
+Complete configuration options for every component used in this project.
+
+---
+
+## Input Components
+
+### CustomTextField (`@core/components/mui/TextField`)
+
+Wraps MUI TextField with Vuexy styling. Use this instead of `@mui/material/TextField`.
+
+**Props**: All `TextFieldProps` from MUI, plus:
+- `size` — `'small'` (default) | `'medium'`
+- `label` — string — Label text above input
+- `placeholder` — string — Placeholder text
+- `fullWidth` — boolean — Expand to container width
+- `error` — boolean — Show error state (red border)
+- `helperText` — string | ReactNode — Text below input
+- `type` — `'text'` | `'email'` | `'password'` | `'number'` | `'tel'` | `'url'` | etc.
+- `disabled` — boolean — Disable input
+- `readOnly` — boolean — Read-only input
+- `multiline` — boolean — Multi-line textarea
+- `rows` — number — Number of visible lines (for multiline)
+- `select` — boolean — Render as select dropdown
+- `slotProps` — object — `{ input?: {}, inputLabel?: {}, select?: {} }`
+- `InputProps` — object — Passed to inner Input component
+- `inputProps` — object — Passed to native input element
+- `value` — string | number — Controlled value
+- `onChange` — function — Change handler
+- `onFocus` / `onBlur` — function — Focus handlers
+- `sx` — SxProps — Additional MUI sx styling
+
+**Styles applied**:
+- Label is always shrunk (not floating)
+- Default variant: `'filled'`
+- Border: 1px solid inputBorder, 2px on focus with shadow
+- Default size: `'small'` with compact padding
+- Focus: primary color border + `var(--mui-customShadows-primary-sm)`
+
+```tsx
+// Basic text
+<CustomTextField fullWidth label='Full Name' placeholder='John Doe' />
+
+// With error
+<CustomTextField fullWidth label='Email' error helperText='Invalid email' />
+
+// Select dropdown
+<CustomTextField select fullWidth label='Country' value='US' onChange={handleChange}>
+  <MenuItem value='US'>United States</MenuItem>
+  <MenuItem value='UK'>United Kingdom</MenuItem>
+</CustomTextField>
+
+// Multi-select
+<CustomTextField
+  select
+  fullWidth
+  slotProps={{ select: { multiple: true } }}
+  label='Languages'
+  value={['en', 'fr']}
+>
+  <MenuItem value='en'>English</MenuItem>
+  <MenuItem value='fr'>French</MenuItem>
+</CustomTextField>
+
+// Textarea
+<CustomTextField fullWidth label='Bio' multiline rows={4} />
+
+// Password with toggle
+<CustomTextField
+  fullWidth
+  label='Password'
+  type={isPasswordShown ? 'text' : 'password'}
+  slotProps={{
+    input: {
+      endAdornment: (
+        <InputAdornment position='end'>
+          <IconButton edge='end' onClick={handleTogglePassword}>
+            <i className='tabler-eye' />
+          </IconButton>
+        </InputAdornment>
+      )
+    }
+  }}
+/>
+```
+
+---
+
+### Autocomplete (`@mui/material/Autocomplete`)
+
+**Import**: `import Autocomplete from '@mui/material/Autocomplete'`
+
+**Key Props**:
+- `options` — Array<T> — List of options
+- `renderInput` — `(params) => ReactNode` — Render function for input. Use `CustomTextField` here.
+- `value` — T | null — Controlled value (single)
+- `multiple` — boolean — Allow multiple selection
+- `freeSolo` — boolean — Allow custom text not in options
+- `disabled` — boolean
+- `loading` — boolean
+- `onChange` — `(event, value) => void`
+- `getLabel` — `(option) => string` — Label for each option
+- `isOptionEqualToValue` — `(option, value) => boolean` — Comparison function
+- `filterOptions` — function — Custom filtering logic
+- `groupBy` — `(option) => string` — Group options by property
+- `disablePortal` — boolean — Don't render in portal
+- `renderOption` — `(props, option) => ReactNode` — Custom option rendering
+- `renderTags` — `(value, getTagProps) => ReactNode` — Custom tag rendering
+- `size` — `'small'` | `'medium'`
+
+```tsx
+<Autocomplete
+  options={countries}
+  value={selectedCountry}
+  onChange={(_, value) => setSelectedCountry(value)}
+  renderInput={params => <CustomTextField {...params} label='Country' />}
+/>
+
+// With avatars
+<Autocomplete
+  options={users}
+  getOptionLabel={option => option.name}
+  renderInput={params => <CustomTextField {...params} label='User' />}
+  renderOption={(props, option) => (
+    <li {...props}>
+      <Avatar src={option.avatar} size={32} />
+      <span style={{ marginLeft: 10 }}>{option.name}</span>
+    </li>
+  )}
+/>
+```
+
+---
+
+### Select (`@mui/material/Select`)
+
+Used when `CustomTextField` has `select` prop. Rarely used standalone.
+
+**Key Props**: `value`, `onChange`, `multiple`, `displayEmpty`, `IconComponent`, `renderValue`
+
+---
+
+### InputAdornment (`@mui/material/InputAdornment`)
+
+**Import**: `import InputAdornment from '@mui/material/InputAdornment'`
+
+**Key Props**:
+- `position` — `'start'` | `'end'` — Adornment position
+- `disablePointerEvents` — boolean
+- `children` — ReactNode — Usually `IconButton`
+
+```tsx
+<CustomTextField
+  fullWidth
+  label='Price'
+  slotProps={{
+    input: {
+      startAdornment: <InputAdornment position='start'>$</InputAdornment>
+    }
+  }}
+/>
+```
+
+---
+
+### InputBase (`@mui/material/InputBase`)
+
+Raw input without label/border styling. Use `CustomTextField` instead unless building custom input wrappers.
+
+---
+
+### InputLabel (`@mui/material/InputLabel`)
+
+Used with native `Select` or custom inputs. Use `CustomTextField` for most cases.
+
+**Key Props**: `shrink` (boolean), `required`, `error`, `focused`, `color`
+
+---
+
+### FormControl (`@mui/material/FormControl`)
+
+Wraps form elements to provide context for `FormHelperText`, `InputLabel`, and error state.
+
+**Key Props**: `fullWidth`, `error`, `disabled`, `required`, `size`, `variant`, `sx`
+
+```tsx
+<FormControl fullWidth error={Boolean(errors.gender)}>
+  <FormLabel>Gender</FormLabel>
+  <RadioGroup row value={gender} onChange={handleChange}>
+    <FormControlLabel value='male' control={<Radio />} label='Male' />
+    <FormControlLabel value='female' control={<Radio />} label='Female' />
+  </RadioGroup>
+  <FormHelperText>{errors.gender?.message}</FormHelperText>
+</FormControl>
+```
+
+---
+
+### FormHelperText (`@mui/material/FormHelperText`)
+
+**Key Props**: `error` (boolean), `disabled`, `sx`, `children`
+
+---
+
+### FormLabel (`@mui/material/FormLabel`)
+
+**Key Props**: `error`, `focused`, `disabled`, `required`, `sx`, `children`
+
+---
+
+### FormGroup (`@mui/material/FormGroup`)
+
+Container for checkboxes. Use with `FormControlLabel`.
+
+**Key Props**: `row` (boolean), `sx`
+
+---
+
+### FormControlLabel (`@mui/material/FormControlLabel`)
+
+**Key Props**: `control` (Checkbox/Radio/Switch element), `label` (string|ReactNode), `disabled`, `labelPlacement` (`'top'` | `'bottom'` | `'start'` | `'end'`), `checked`
+
+---
+
+### Checkbox (`@mui/material/Checkbox`)
+
+**Key Props**: `checked`, `defaultChecked`, `disabled`, `onChange`, `color`, `size`, `icon`, `checkedIcon`, `indeterminate`, `inputProps`
+
+```tsx
+<Checkbox checked={checked} onChange={e => setChecked(e.target.checked)} />
+<Checkbox color='secondary' checked />
+<Checkbox defaultChecked disabled />
+```
+
+---
+
+### Radio (`@mui/material/Radio`) + RadioGroup (`@mui/material/RadioGroup`)
+
+**Radio Props**: `checked`, `disabled`, `onChange`, `color`, `size`, `value`, `name`, `icon`, `checkedIcon`
+
+**RadioGroup Props**: `row` (boolean), `value`, `onChange`, `name`, `defaultValue`
+
+```tsx
+<FormControl>
+  <FormLabel>Plan</FormLabel>
+  <RadioGroup value={plan} onChange={handleChange} name='plan'>
+    <FormControlLabel value='free' control={<Radio />} label='Free' />
+    <FormControlLabel value='pro' control={<Radio />} label='Pro' />
+    <FormControlLabel value='enterprise' control={<Radio />} label='Enterprise' />
+  </RadioGroup>
+</FormControl>
+```
+
+---
+
+### Switch (`@mui/material/Switch`)
+
+**Key Props**: `checked`, `onChange`, `disabled`, `color`, `size` (`'small'` | `'medium'`), `defaultChecked`, `inputProps`
+
+```tsx
+<Switch checked={enabled} onChange={handleChange} />
+<Switch color='secondary' />
+<Switch size='small' />
+
+// With label
+<FormControlLabel control={<Switch checked={dark} onChange={handleChange} />} label='Dark Mode' />
+```
+
+---
+
+### Rating (`@mui/material/Rating`)
+
+**Key Props**: `value`, `onChange`, `max` (default 5), `icon`, `emptyIcon`, `precision` (0.5, 1), `size` (`'small'` | `'medium'` | `'large'`), `readOnly`, `disabled`, `highlightSelectedOnly`
+
+```tsx
+<Rating value={4} onChange={(_, newValue) => setValue(newValue)} />
+<Rating value={3.5} precision={0.5} readOnly />
+<Rating value={4} size='large' max={10} />
+```
+
+---
+
+## Data Display Components
+
+### Typography (`@mui/material/Typography`)
+
+**Key Props**:
+- `variant` — `'h1'` | `'h2'` | `'h3'` | `'h4'` | `'h5'` | `'h6'` | `'subtitle1'` | `'subtitle2'` | `'body1'` | `'body2'` | `'button'` | `'caption'` | `'overline'` | `'inherit'`
+- `color` — `'textPrimary'` | `'textSecondary'` | `'primary'` | `'secondary'` | `'error'` | etc.
+- `align` — `'left'` | `'center'` | `'right'` | `'justify'`
+- `noWrap` — boolean — Truncate with ellipsis
+- `gutterBottom` — boolean — Add bottom margin
+- `component` — string | ComponentType — Override HTML element (e.g., `'p'`, `'h3'`, `Link`)
+- `children` — ReactNode
+- `className` / `sx` — Styling
+
+```tsx
+<Typography variant='h4'>Page Title</Typography>
+<Typography variant='body2' color='text.secondary'>Description</Typography>
+<Typography color='text.primary' className='font-medium'>Bold text</Typography>
+<Typography variant='body2' noWrap>Long text that truncates...</Typography>
+```
+
+---
+
+### Card (`@mui/material/Card`)
+
+**Key Props**: `variant` (`'elevation'` | `'outlined'`), `raised`, `children`, `sx`
+
+```tsx
+<Card>
+  <CardHeader title='Card Title' subheader='Card Subtitle' />
+  <CardContent>
+    {/* Card content */}
+  </CardContent>
+  <CardActions>
+    <Button variant='contained'>Action</Button>
+  </CardActions>
+</Card>
+
+// With image
+<Card>
+  <CardMedia component='img' height='200' image='/images/card.png' />
+  <CardContent>...</CardContent>
+</Card>
+```
+
+---
+
+### CardHeader (`@mui/material/CardHeader`)
+
+**Key Props**: `title`, `subheader`, `avatar`, `action`
+
+```tsx
+<CardHeader title='Orders' subheader='Total 150 orders' action={
+  <IconButton><i className='tabler-dots-vertical' /></IconButton>
+} />
+```
+
+---
+
+### CardContent (`@mui/material/CardContent`)
+
+**Key Props**: `children`, `sx`
+
+---
+
+### CardActions (`@mui/material/CardActions`)
+
+**Key Props**: `children`, `disableSpacing`, `sx`
+
+---
+
+### CardMedia (`@mui/material/CardMedia`)
+
+**Key Props**: `component` (`'img'` | `'div'` | etc.), `image` (URL), `height`, `title`, `sx`
+
+```tsx
+<CardMedia component='img' height='140' image='https://example.com/image.jpg' />
+```
+
+---
+
+### CustomAvatar (`@core/components/mui/Avatar`)
+
+**Key Props** (all Avatar props plus):
+- `color` — `'primary'` | `'secondary'` | `'success'` | `'warning'` | `'error'` | `'info'`
+- `skin` — `'filled'` (default, solid bg) | `'light'` (light bg, respects theme) | `'light-static'`
+- `size` — number — Pixel dimensions (e.g., `32`, `40`, `119`)
+- `src` — string — Image URL
+- `children` — letter(s) for avatar
+- `variant` — `'circular'` (default) | `'rounded'` | `'square'`
+- `sx` — additional styles
+
+```tsx
+<CustomAvatar color='primary'>A</CustomAvatar>
+<CustomAvatar color='success' skin='light' size={32}><i className='tabler-check' /></CustomAvatar>
+<CustomAvatar src='/images/avatar.png' size={40} />
+```
+
+---
+
+### CustomBadge (`@core/components/mui/Badge`)
+
+**Key Props** (all Badge props plus):
+- `tonal` — `'true'` | `'false'` — Light background instead of solid
+
+```tsx
+<CustomBadge tonal='true' color='error' badgeContent={4}>
+  <CustomAvatar src='/images/avatar.png' />
+</CustomBadge>
+```
+
+---
+
+### CustomChip (`@core/components/mui/Chip`)
+
+**Key Props** (all Chip props plus):
+- `round` — `'true'` | `'false'` — Pill shape (500px border radius)
+
+**Chip Props**:
+- `label` — string | ReactNode
+- `color` — `'default'` | `'primary'` | `'secondary'` | `'error'` | `'info'` | `'success'` | `'warning'`
+- `size` — `'small'` | `'medium'`
+- `variant` — `'filled'` | `'outlined'`
+- `onDelete` — function — Shows delete icon (calls handler)
+- `onClick` — function
+- `icon` — ReactNode
+- `avatar` — Avatar element
+- `clickable` — boolean
+- `disabled` — boolean
+
+```tsx
+<CustomChip label='Active' color='success' round='true' />
+<CustomChip label='Pending' color='warning' />
+<CustomChip label='Error' color='error' variant='outlined' />
+<CustomChip avatar={<Avatar>A</Avatar>} label='Author' />
+<CustomChip label='Deletable' onDelete={() => {}} color='info' />
+```
+
+---
+
+### List, ListItem, ListItemButton, ListItemText, ListItemIcon, ListItemAvatar
+
+```tsx
+<List>
+  <ListItem disablePadding>
+    <ListItemButton>
+      <ListItemIcon><i className='tabler-mail' /></ListItemIcon>
+      <ListItemText primary='Inbox' secondary='12 unread' />
+    </ListItemButton>
+  </ListItem>
+</List>
+```
+
+**List Props**: `disablePadding`, `dense`, `subheader`, `component`
+**ListItem Props**: `disablePadding`, `dense`, `divider`, `secondaryAction`
+**ListItemButton Props**: `selected`, `disabled`, `dense`, `component`, `onMouseEnter/Leave`
+**ListItemText Props**: `primary`, `secondary`, `primaryTypographyProps`, `secondaryTypographyProps`
+**ListItemIcon Props**: `className` (for sizing)
+
+---
+
+### Divider (`@mui/material/Divider`)
+
+**Key Props**: `flexItem`, `light`, `orientation` (`'horizontal'` | `'vertical'`), `children`, `sx`
+
+```tsx
+<Divider />
+<Divider flexItem /> {/* In flex container */}
+<Divider className='mbe-4' />
+<Divider textAlign='left'>OR</Divider>
+```
+
+---
+
+### Table Components
+
+**Import each from `@mui/material/`**: `Table`, `TableHead`, `TableBody`, `TableRow`, `TableCell`, `TableContainer`, `TablePagination`
+
+```tsx
+import Table from '@mui/material/Table'
+import TableBody from '@mui/material/TableBody'
+import TableCell from '@mui/material/TableCell'
+import TableHead from '@mui/material/TableHead'
+import TableRow from '@mui/material/TableRow'
+import TablePagination from '@mui/material/TablePagination'
+import Checkbox from '@mui/material/Checkbox'
+
+<Table>
+  <TableHead>
+    <TableRow>
+      <TableCell padding='checkbox'>
+        <Checkbox
+          checked={selectAll}
+          onChange={e => setSelectAll(e.target.checked)}
+        />
+      </TableCell>
+      <TableCell>Name</TableCell>
+      <TableCell>Email</TableCell>
+      <TableCell>Actions</TableCell>
+    </TableRow>
+  </TableHead>
+  <TableBody>
+    {rows.map(row => (
+      <TableRow key={row.id}>
+        <TableCell padding='checkbox'>
+          <Checkbox checked={selected.has(row.id)} />
+        </TableCell>
+        <TableCell>{row.name}</TableCell>
+        <TableCell>{row.email}</TableCell>
+        <TableCell>
+          <IconButton onClick={() => handleEdit(row.id)}><i className='tabler-pencil' /></IconButton>
+          <IconButton onClick={() => handleDelete(row.id)}><i className='tabler-trash' /></IconButton>
+        </TableCell>
+      </TableRow>
+    ))}
+  </TableBody>
+</Table>
+
+{/* Pagination */}
+<TablePagination
+  component='div'
+  count={totalRows}
+  page={page}
+  onPageChange={(_, newPage) => setPage(newPage)}
+  rowsPerPage={rowsPerPage}
+  onRowsPerPageChange={e => { setRowsPerPage(+e.target.value); setPage(0); }}
+/>
+```
+
+**TableCell Props**: `align` (`'left'` | `'center'` | `'right'` | `'justify'`), `padding` (`'normal'` | `'checkbox'` | `'none'`), `size` (`'small'` | `'medium'`), `sortDirection`, `component`, `colSpan`, `rowSpan`, `variant` (`'head'` | `'body'` | `'footer'`)
+**TablePagination Props**: `count`, `page`, `rowsPerPage`, `onPageChange`, `onRowsPerPageChange`, `rowsPerPageOptions`, `component`, `labelRowsPerPage`, `labelDisplayedRows`
+
+---
+
+## Feedback Components
+
+### Alert (`@mui/material/Alert`)
+
+**Key Props**:
+- `severity` — `'error'` | `'warning'` | `'info'` | `'success'`
+- `variant` — `'standard'` | `'outlined'` | `'filled'`
+- `icon` — ReactNode — Custom icon
+- `action` — ReactNode — Action element (button, close icon)
+- `onClose` — function
+- `title` — string (for AlertTitle sibling)
+
+```tsx
+<Alert severity='error'>
+  <AlertTitle>Error</AlertTitle>
+  <div>Something went wrong.</div>
+</Alert>
+
+<Alert severity='success' variant='outlined'>
+  Changes saved successfully!
+</Alert>
+```
+
+---
+
+### AlertTitle (`@mui/material/AlertTitle`)
+
+**Key Props**: `children`, `className`, `sx`
+**Usage**: Must be used inside an `<Alert>` component.
+
+---
+
+### CircularProgress (`@mui/material/CircularProgress`)
+
+**Key Props**: `size` (number | `'small'` | `'medium'`), `thickness` (number), `color`, `variant` (`'indeterminate'` | `'determinate'`), `value` (0-100 for determinate)
+
+```tsx
+<CircularProgress />
+<CircularProgress size={24} />
+<CircularProgress color='secondary' />
+<CircularProgress variant='determinate' value={75} />
+```
+
+---
+
+### LinearProgress (`@mui/material/LinearProgress`)
+
+**Key Props**: `variant` (`'indeterminate'` | `'determinate'` | `'buffer'` | `'query'`), `value` (0-100), `valueBuffer` (0-100), `color`, `sx`
+
+```tsx
+<LinearProgress variant='determinate' value={60} />
+<LinearProgress color='secondary' />
+```
+
+---
+
+### Backdrop (`@mui/material/Backdrop`)
+
+**Key Props**: `open`, `children`, `onClick`, `sx`, `transitionDuration`
+
+```tsx
+<Backdrop open={loading} onClick={() => setLoading(false)}>
+  <CircularProgress color='inherit' />
+</Backdrop>
+```
+
+---
+
+### Snackbar (`@mui/material/Snackbar`)
+
+**Key Props**: `open`, `message`, `autoHideDuration`, `onClose`, `anchorOrigin` (`{ vertical: 'top' | 'bottom', horizontal: 'left' | 'center' | 'right' }`), `action`, `TransitionComponent`
+
+**Note**: This project uses `react-toastify` for toast notifications instead of MUI Snackbar. Use `toast.success()`, `toast.error()`, `toast.warning()`, `toast.info()` from `'react-toastify'`.
+
+---
+
+## Navigation Components
+
+### Button (`@mui/material/Button`)
+
+**Key Props**:
+- `variant` — `'text'` | `'outlined'` | `'contained'` | `'tonal'` (Vuexy custom!)
+- `color` — `'primary'` | `'secondary'` | `'error'` | `'info'` | `'success'` | `'warning'` | `'inherit'`
+- `size` — `'small'` | `'medium'` | `'large'`
+- `disabled` — boolean
+- `fullWidth` — boolean
+- `startIcon` / `endIcon` — ReactNode
+- `type` — `'button'` | `'submit'` | `'reset'`
+- `onClick` — function
+- `href` — string — Makes it a link
+- `component` — Link (for Next.js Link integration)
+- `className` / `sx`
+
+```tsx
+<Button variant='contained' type='submit'>Submit</Button>
+<Button variant='tonal' color='secondary'>Cancel</Button>
+<Button variant='outlined' startIcon={<i className='tabler-plus' />}>Add New</Button>
+<Button variant='text' onClick={handleClick}>Learn More</Button>
+<Button variant='contained' color='error'>Delete</Button>
+<Button variant='tonal' size='small'>Small</Button>
+
+// As link
+<Button component={Link} href='/settings' variant='tonal' color='secondary'>
+  Go to Settings
+</Button>
+```
+
+---
+
+### ButtonGroup (`@mui/material/ButtonGroup`)
+
+**Key Props**: `variant`, `color`, `size`, `orientation` (`'horizontal'` | `'vertical'`), `fullWidth`, `disabled`, `sx`
+
+```tsx
+<ButtonGroup>
+  <Button>One</Button>
+  <Button>Two</Button>
+  <Button>Three</Button>
+</ButtonGroup>
+```
+
+---
+
+### Breadcrumbs (`@mui/material/Breadcrumbs`)
+
+**Key Props**: `separator`, `maxItems`, `component`, `itemsAfterCollapse`, `itemsBeforeCollapse`, `sx`
+
+```tsx
+<Breadcrumbs>
+  <Link href='/'>Home</Link>
+  <Link href='/apps'>Apps</Link>
+  <Typography color='text.primary'>Ecommerce</Typography>
+</Breadcrumbs>
+```
+
+---
+
+### Tooltip (`@mui/material/Tooltip`)
+
+**Key Props**: `title`, `placement` (`'top'` | `'bottom'` | `'left'` | `'right'` + variants), `arrow`, `open`, `defaultOpen`, `enterDelay`, `leaveDelay`, `children`
+
+```tsx
+<Tooltip title='Delete' placement='top' arrow>
+  <IconButton><i className='tabler-trash' /></IconButton>
+</Tooltip>
+```
+
+---
+
+### Menu + MenuList + MenuItem
+
+```tsx
+import Menu from '@mui/material/Menu'
+import MenuItem from '@mui/material/MenuItem'
+
+const [anchorEl, setAnchorEl] = useState<null | HTMLElement>(null)
+const open = Boolean(anchorEl)
+
+<IconButton onClick={e => setAnchorEl(e.currentTarget)}>
+  <i className='tabler-dots-vertical' />
+</IconButton>
+
+<Menu anchorEl={anchorEl} open={open} onClose={() => setAnchorEl(null)}>
+  <MenuItem onClick={handleView}>
+    <i className='tabler-eye me-2' />
+    View
+  </MenuItem>
+  <MenuItem onClick={handleEdit}>
+    <i className='tabler-pencil me-2' />
+    Edit
+  </MenuItem>
+  <MenuItem onClick={handleDelete}>
+    <i className='tabler-trash me-2' />
+    Delete
+  </MenuItem>
+</Menu>
+```
+
+**Menu Props**: `anchorEl`, `open`, `onClose`, `anchorOrigin` (`{ vertical: 'bottom' | 'top', horizontal: 'left' | 'right' | 'center' }`), `transformOrigin`, `PaperProps`, `MenuListProps`, `slotProps`, `keepMounted`
+**MenuItem Props**: `dense`, `disabled`, `selected`, `component`, `onClick`, `children` (usually icon + text)
+
+---
+
+### Pagination (`@mui/material/Pagination`)
+
+**Key Props**: `count` (total pages), `page` (current), `onChange`, `variant` (`'text'` | `'outlined'`), `color`, `size` (`'small'` | `'medium'` | `'large'`), `shape` (`'round'` | `'rounded'`), `showFirstButton`, `showLastButton`, `siblingsRange`, `boundaryRange`
+
+```tsx
+<Pagination count={10} page={1} onChange={handlePageChange} color='primary' />
+<Pagination count={10} variant='outlined' shape='rounded' />
+```
+
+---
+
+### Stepper + Step + StepLabel + StepContent + StepIcon
+
+```tsx
+import Stepper from '@mui/material/Stepper'
+import Step from '@mui/material/Step'
+import StepLabel from '@mui/material/StepLabel'
+import StepContent from '@mui/material/StepContent'
+import Button from '@mui/material/Button'
+
+<Stepper activeStep={activeStep} orientation='vertical'>
+  {steps.map((step, index) => (
+    <Step key={index}>
+      <StepLabel>{step.label}</StepLabel>
+      <StepContent>
+        <p>{step.description}</p>
+        <Button variant='contained' onClick={() => setActiveStep(index + 1)}>
+          {index === steps.length - 1 ? 'Finish' : 'Next'}
+        </Button>
+      </StepContent>
+    </Step>
+  ))}
+</Stepper>
+```
+
+**Stepper Props**: `activeStep`, `orientation` (`'horizontal'` | `'vertical'`), `alternativeLabel`, `disabled`, `connector`, `nonLinear`, `children`
+**Step Props**: `completed`, `expanded`, `disabled`, `index`, `active`
+**StepLabel Props**: `error`, `children`, `StepIconComponent`, `optional`, `icon`
+**StepContent Props**: `children`, `TransitionProps`, `transitionDuration`
+
+---
+
+### Tabs, Tab, TabContext, TabPanel, CustomTabList
+
+```tsx
+import TabContext from '@mui/lab/TabContext'
+import TabPanel from '@mui/lab/TabPanel'
+import Tab from '@mui/material/Tab'
+import CustomTabList from '@core/components/mui/TabList'
+
+<TabContext value={tabValue}>
+  <CustomTabList onChange={handleTabChange} pill='true' color='primary'>
+    <Tab value='1' label='Tab One' />
+    <Tab value='2' label='Tab Two' />
+    <Tab value='3' label='Tab Three' />
+  </CustomTabList>
+  <TabPanel value='1'>Content One</TabPanel>
+  <TabPanel value='2'>Content Two</TabPanel>
+  <TabPanel value='3'>Content Three</TabPanel>
+</TabContext>
+```
+
+**CustomTabList Props**: `value`, `onChange`, `color`, `pill` (`'true'` | `'false'`), `orientation` (`'horizontal'` | `'vertical'`), `variant` (`'standard'` | `'scrollable'` | `'fullWidth'`), `scrollButtons`, `allowScrollButtonsMobile`
+**Tab Props**: `label`, `value`, `icon`, `iconPosition` (`'top'` | `'bottom'` | `'start'` | `'end'`), `disabled`, `wrapped` (for scrollable), `TabIndicatorProps`
+
+---
+
+## Overlays
+
+### Dialog + DialogTitle + DialogContent + DialogActions
+
+```tsx
+import Dialog from '@mui/material/Dialog'
+import DialogTitle from '@mui/material/DialogTitle'
+import DialogContent from '@mui/material/DialogContent'
+import DialogActions from '@mui/material/DialogActions'
+
+<Dialog open={open} onClose={handleClose} fullWidth maxWidth='sm'>
+  <DialogTitle>Dialog Title</DialogTitle>
+  <DialogCloseButton onClick={handleClose} />      {/* From @/components/dialogs/DialogCloseButton */}
+  <DialogContent>
+    <Grid container spacing={6}>
+      {/* Dialog content / form */}
+    </Grid>
+  </DialogContent>
+  <DialogActions className='dialog-actions-dense'>
+    <Button variant='tonal' color='secondary' onClick={handleClose}>Cancel</Button>
+    <Button variant='contained' onClick={handleSubmit}>Submit</Button>
+  </DialogActions>
+</Dialog>
+```
+
+**Dialog Props**: `open`, `onClose`, `fullWidth`, `maxWidth` (`'xs'` | `'sm'` | `'md'` | `'lg'` | `'xl'` | `false`), `fullScreen`, `children`, `sx`, `PaperProps`, `TransitionComponent`, `scroll` (`'paper'` | `'body'`)
+**DialogTitle Props**: `id`, `children`, `sx`
+**DialogContent Props**: `dividers`, `sx`
+**DialogActions Props**: `disableSpacing`, `sx`, `className='dialog-actions-dense'` (standard in this project)
+
+### DialogCloseButton (`@/components/dialogs/DialogCloseButton`)
+
+**Props**: `onClick`, `className`, `children` (default: `X` icon)
+
+```tsx
+import DialogCloseButton from '@/components/dialogs/DialogCloseButton'
+<DialogCloseButton onClick={handleClose} />
+```
+
+---
+
+### Drawer (`@mui/material/Drawer`)
+
+```tsx
+import Drawer from '@mui/material/Drawer'
+
+<Drawer
+  open={open}
+  anchor='right'
+  variant='temporary'
+  onClose={() => setOpen(false)}
+  ModalProps={{ keepMounted: true }}
+  sx={{ '& .MuiDrawer-paper': { width: { xs: 300, sm: 400 } } }}
+>
+  <div className='flex justify-between items-center pbs-5 mbe-4'>
+    <Typography variant='h5'>Drawer Title</Typography>
+    <IconButton onClick={() => setOpen(false)}>
+      <i className='tabler-x' />
+    </IconButton>
+  </div>
+  <Divider />
+  <div className='p-5'>
+    {/* Drawer content */}
+  </div>
+</Drawer>
+```
+
+**Drawer Props**: `open`, `onClose`, `anchor` (`'left'` | `'right'` | `'top'` | `'bottom'`), `variant` (`'temporary'` | `'permanent'` | `'persistent'`), `children`, `sx`, `ModalProps`, `SlideProps`, `transitionDuration`
+
+---
+
+### Popper (`@mui/material/Popper`)
+
+**Key Props**: `open`, `anchorEl`, `placement` (`'top'` | `'bottom'` | `'right'` | `'left'` + variants), `modifiers`, `transition`, `disablePortal`, `sx`
+
+---
+
+### ClickAwayListener (`@mui/material/ClickAwayListener`)
+
+```tsx
+import ClickAwayListener from '@mui/material/ClickAwayListener'
+
+<ClickAwayListener onClickAway={() => setOpen(false)}>
+  <div>
+    <button onClick={() => setOpen(true)}>Toggle</button>
+    {open && <div>Click outside to close</div>}
+  </div>
+</ClickAwayListener>
+```
+
+**Key Props**: `onClickAway`, `children`, `mouseEvent` (`'onClick'` | `'onMouseDown'` | `'none'`), `touchEvent` (`'onTouchEnd'` | `'none'`)
+
+---
+
+### Fade, Grow, Zoom, Collapse (Transitions)
+
+All used for animation: `<Fade in={open}>`, `<Grow in={open}>`, `<Zoom in={open}>`, `<Collapse in={open}>`
+
+**Common Props**: `in`, `children`, `timeout`, `onEnter`, `onEntering`, `onEntered`, `onExit`, `onExiting`, `onExited`
+
+**Collapse** also has: `orientation` (`'horizontal'` | `'vertical'`), `collapsedSize`
+
+---
+
+### Paper (`@mui/material/Paper`)
+
+**Key Props**: `variant` (`'elevation'` | `'outlined'`), `elevation` (0-24), `square`, `children`, `sx`
+
+```tsx
+<Paper elevation={2} sx={{ p: 3 }}>
+  Elevated content
+</Paper>
+```
+
+---
+
+## Lab Components (@mui/lab)
+
+### Timeline Components
+
+```tsx
+import Timeline from '@mui/lab/Timeline'
+import TimelineItem from '@mui/lab/TimelineItem'
+import TimelineSeparator from '@mui/lab/TimelineSeparator'
+import TimelineConnector from '@mui/lab/TimelineConnector'
+import TimelineContent from '@mui/lab/TimelineContent'
+import TimelineDot from '@mui/lab/TimelineDot'
+
+<Timeline>
+  <TimelineItem>
+    <TimelineSeparator>
+      <TimelineDot color='primary' />
+      <TimelineConnector />
+    </TimelineSeparator>
+    <TimelineContent>
+      <Typography variant='body2'>Event description</Typography>
+      <Typography variant='caption' color='text.secondary'>2 hours ago</Typography>
+    </TimelineContent>
+  </TimelineItem>
+</Timeline>
+```
+
+**Timeline Props**: `position` (`'alternate'` | `'right'` | `'left'`)
+**TimelineDot Props**: `color`, `variant` (`'filled'` | `'outlined'`)
+
+---
+
+## Card Statistics Components
+
+Pre-built statistic cards in `src/components/card-statistics/`:
+
+| Component | Props | Use Case |
+|-----------|-------|----------|
+| `CardStatsSquare` | `title`, `stats`, `avatarIcon`, `avatarColor`, `avatarSkin` | Square stat with icon avatar |
+| `Horizontal` | `title`, `stats`, `avatarIcon`, `avatarColor`, `subtitle` | Horizontal stat card |
+| `HorizontalWithAvatar` | `title`, `stats`, `avatarImg`, `avatarColor` | Horizontal with image avatar |
+| `HorizontalWithSubtitle` | `title`, `stats`, `subtitle`, `avatarIcon`, `avatarColor`, `trend` | With trend indicator |
+| `Vertical` | `title`, `stats`, `avatarIcon`, `avatarColor`, `chipText`, `chipType`, `trendNumber` | Vertical with trend chip |
+| `HorizontalWithBorder` | `title`, `stats`, `avatarIcon`, `avatarColor` | Horizontal with border accent |
+| `CardStatPie` | `title`, `stats`, `chartData`, `color` | With pie chart |
+| `CardStatsWithAreaChart` | `title`, `stats`, `chartData`, `color` | With area chart |
+| `CustomerStats` | `title`, `stats`, `chipText`, `chipType`, `trendDirection`, `avatarIcon`, `avatarColor` | Customer-focused stat |
+
+```tsx
+import CardStatsVertical from '@components/card-statistics/Vertical'
+
+<CardStatsVertical
+  title='Revenue'
+  stats='$42.5K'
+  chipText='+12.5%'
+  chipType='success'
+  avatarIcon='tabler-currency-dollar'
+  avatarColor='primary'
+/>
+```
+
+---
+
+## Option Menu Component (`@core/components/option-menu`)
+
+Dropdown menu for card headers/actions.
+
+```tsx
+import OptionMenu from '@core/components/option-menu'
+
+<OptionMenu
+  iconClassName='tabler-dots-vertical'
+  options={[
+    { text: 'Refresh', icon: 'tabler-refresh', onClick: handleRefresh },
+    { text: 'Edit', icon: 'tabler-pencil', href: '/edit' },
+    { divider: true },
+    { text: 'Delete', icon: 'tabler-trash', onClick: handleDelete }
+  ]}
+/>
+```
+
+**Options Array Item Format**:
+- `{ text: string, icon?: string, onClick?: fn, href?: string }` — menu item
+- `{ divider: true }` — divider separator
+
+---
+
+## Icon System
+
+This project uses **Tabler Icons** via Iconify. Icons are referenced by class name:
+
+```tsx
+<i className='tabler-icon-name' />
+```
+
+Common icons: `tabler-plus`, `tabler-pencil`, `tabler-trash`, `tabler-eye`, `tabler-eye-off`, `tabler-dots-vertical`, `tabler-check`, `tabler-x`, `tabler-arrow-left`, `tabler-arrow-right`, `tabler-arrow-up`, `tabler-user`, `tabler-mail`, `tabler-calendar`, `tabler-search`, `tabler-settings`, `tabler-bell`, `tabler-menu`, `tabler-layout-grid`, `tabler-layout-list`
+
+For MUI `IconButton` children or `startIcon`/`endIcon` on Buttons, use `<i className='...' />` or `<Icon />` from `@iconify/react`.
+
+---
+
+## Theme Utilities
+
+### styled() — For Custom Components
+
+```tsx
+'use client'
+import { styled } from '@mui/material/styles'
+import Card from '@mui/material/Card'
+
+const StyledCard = styled(Card)(({ theme }) => ({
+  border: `1px solid ${theme.palette.divider}`,
+  '&:hover': {
+    boxShadow: theme.shadows[6]
+  }
+}))
+```
+
+### useTheme Hook
+
+```tsx
+import { useTheme } from '@mui/material/styles'
+const theme = useTheme()
+// theme.palette.primary.main, theme.spacing(2), theme.typography.h4, theme.breakpoints.up('md')
+```
+
+### useMediaQuery Hook
+
+```tsx
+import useMediaQuery from '@mui/material/useMediaQuery'
+import { useTheme } from '@mui/material/styles'
+
+const theme = useTheme()
+const isMobile = useMediaQuery(theme.breakpoints.down('sm'))
+```
+
+### useColorScheme Hook
+
+```tsx
+import { useColorScheme } from '@mui/material'
+const { mode, setMode } = useColorScheme()
+```
+
+---
+
+## Common MUI Utility Values
+
+### Spacing
+`theme.spacing(1)` = `8px`, `theme.spacing(2)` = `16px`, `theme.spacing(3)` = `24px`, etc.
+
+### Breakpoints
+`xs: 0`, `sm: 600`, `md: 900`, `lg: 1200`, `xl: 1536`
+
+For Grid sizes use `Grid size={{ xs: 12, md: 6 }}`