@turk.net/mui 3.0.7 → 3.0.8

package/COMPONENT_MAP.md

@@ -0,0 +1,567 @@
+# OneHub Component Map
+
+> **Purpose:** Definitive mapping of Figma design patterns to Material UI components with exact props (variant, size, color, severity).
+>
+> **Critical Rule:** AI agents MUST use ONLY the components and prop combinations listed below. Any deviation is a design violation.
+
+---
+
+## How to Use This Map
+
+1. Identify the UI element in Figma (e.g., a blue button with text)
+2. Find the matching pattern below
+3. Use the exact MUI component and props listed
+4. Do NOT invent new variant/size/color combinations
+
+---
+
+## Button
+
+**MUI Component:** `Button` from `@mui/material`
+
+| # | Figma Pattern | Variant | Size | Color | Key Visual Traits |
+|---|--------------|---------|------|-------|-------------------|
+| B1 | Primary / Filled Blue | `contained` | `medium` | `primary` | Blue bg (`--brand-background-1-rest`), white text, `borderRadius: 8px`, `height: 32px` |
+| B2 | Primary / Filled Large | `contained` | `large` | `primary` | Same as B1 but taller |
+| B3 | Primary / Filled Small | `contained` | `small` | `primary` | Same as B1 but smaller |
+| B4 | Secondary / Outlined | `outlined` | `medium` | `secondary` | Gray border (`--neutral-stroke-1-rest`), transparent bg, dark text |
+| B5 | Secondary / Outlined Large | `outlined` | `large` | `secondary` | Same as B4 but taller |
+| B6 | Secondary / Outlined Small | `outlined` | `small` | `secondary` | Same as B4 but smaller |
+| B7 | Text / Ghost | `text` | `medium` | `primary` | No bg, no border, blue text |
+| B8 | Text / Ghost Small | `text` | `small` | `primary` | Same as B7 but smaller |
+| B9 | Error / Danger | `contained` | `medium` | `error` | Red bg, white text |
+| B10 | Error / Outlined | `outlined` | `medium` | `error` | Red border, transparent bg, red text |
+| B11 | Icon Only (transparent) | `text` | `medium` | `primary` | No padding, transparent bg, `--neutral-background-subtle-rest` |
+| B12 | Icon Only (gray bg) | `text` | `medium` | `secondary` | Gray bg (`--neutral-background-2-rest`), border |
+| B13 | Filter Button (gray) | `text` | `medium` | `secondary` | Gray bg (`--neutral-background-2-rest`), `neutral-stroke-1` border, icon+text |
+| B14 | Filter Button (clear) | `text` | `medium` | `primary` | Transparent bg, delete icon, no text or "Temizle" |
+
+### Button State Tokens
+
+| State | Background | Foreground | Border |
+|-------|------------|------------|--------|
+| **rest** | `brand.background[1].rest` | `neutral.foreground.on.brand.rest` | none |
+| **hover** | `brand.background[1].hover` | `neutral.foreground.on.brand.hover` | none |
+| **pressed** | `brand.background[1].pressed` | `neutral.foreground.on.brand.pressed` | none |
+| **disabled** | `neutral.background.disabled.rest` | `neutral.foreground.disabled.rest` | none |
+| **focus** | `brand.background[1].rest` | `neutral.foreground.on.brand.rest` | `neutral.stroke.focus.rest` |
+
+> Button states are auto-handled by the theme overrides. Do NOT manually apply hover/pressed styles.
+
+### Invalid Button Combinations
+
+```typescript
+// ❌ WRONG — color="success" not defined in theme
+<Button color="success">Save</Button>
+
+// ❌ WRONG — variant="outlined" with color="primary" but without size
+<Button variant="outlined" color="primary">Delete</Button>
+
+// ✅ CORRECT
+<Button variant="outlined" size="medium" color="error">Delete</Button>
+```
+
+---
+
+## TextField / Input
+
+**MUI Component:** `TextField` from `@mui/material`
+
+| # | Figma Pattern | Color | Size | Key Visual Traits |
+|---|--------------|-------|------|-------------------|
+| T1 | Default Input | `neutral` | `medium` | Gray border, white bg |
+| T2 | Brand Input | `brand` | `medium` | Blue border/focus |
+| T3 | Error Input | `danger` | `medium` | Red border, error text |
+| T4 | Large Input | `neutral` | `large` | Taller input field |
+| T5 | Disabled Input | `neutral` | `medium` | Gray bg, disabled border |
+| T6 | Read-only Input | `neutral` | `medium` | No border, subtle bg |
+
+### TextField Label
+
+**MUI Component:** `InputLabel` (auto-wrapped by TextField)
+
+| Size | Typography |
+|------|-----------|
+| `small` | `text.xs.regular` (`12px`, `400`) |
+| `medium` | `text.sm.regular` (`14px`, `400`) |
+| `large` | `text.sm.regular` (`14px`, `400`) |
+
+### TextField Helper Text
+
+**MUI Component:** `FormHelperText`
+
+| Type | Typography | Color |
+|------|-----------|-------|
+| default | `text.xs.regular` | `neutral.foreground[3].rest` |
+| error | `text.xs.regular` | `danger.foreground[1].rest` |
+
+### Invalid TextField Combinations
+
+```typescript
+// ❌ WRONG — color="primary" not defined for TextField
+<TextField color="primary" />
+
+// ❌ WRONG — using MUI default sizes
+<TextField size="small" /> // Use "small" only if defined in theme
+
+// ✅ CORRECT
+<TextField color="neutral" size="medium" />
+```
+
+---
+
+## Select / Dropdown
+
+**MUI Component:** `Select` from `@mui/material`
+
+Uses same color/size system as TextField.
+
+| # | Figma Pattern | Color | Size |
+|---|--------------|-------|------|
+| S1 | Default Select | `neutral` | `medium` |
+| S2 | Brand Select | `brand` | `medium` |
+| S3 | Error Select | `danger` | `medium` |
+| S4 | Large Select | `neutral` | `large` |
+
+**MenuItem:** Standard `MenuItem` from `@mui/material`. Text uses `text.sm.regular`.
+
+---
+
+## Checkbox
+
+**MUI Component:** `Checkbox` from `@mui/material`
+
+| # | Figma Pattern | Color | Size |
+|---|--------------|-------|------|
+| C1 | Default Checkbox | `primary` | `small` (16px) |
+| C2 | Error Checkbox | `error` | `small` (16px) |
+
+### Checkbox Visual Specs
+
+| Property | Value |
+|----------|-------|
+| Size | `16px × 16px` |
+| Border Radius | `4px` |
+| Unchecked Border | `--neutral-stroke-accessible-rest` (`#616161`) |
+| Checked Background | `--brand-background-compound-rest` (`#2970ff`) |
+| Check Icon Color | White |
+
+### Figma Radio (Radio-style Checkbox)
+
+Figma's "Radio" uses the same `CheckboxBase` component with `rounded-[8px]` for radio-style selection (used in filter panels):
+
+| Figma Pattern | MUI Component | Props |
+|--------------|---------------|-------|
+| Radio (filter) | `Radio` or `Checkbox` | `color="primary"` — 16px, `borderRadius: 8px` |
+
+---
+
+## Radio
+
+**MUI Component:** `Radio` from `@mui/material`
+
+| # | Figma Pattern | Color | Size |
+|---|--------------|-------|------|
+| R1 | Default Radio | `primary` | `small` (16px) |
+| R2 | Error Radio | `error` | `small` (16px) |
+
+### Radio Visual Specs
+
+| Property | Value |
+|----------|-------|
+| Size | `16px × 16px` |
+| Border Radius | `8px` (fully rounded) |
+| Unchecked Border | `--neutral-stroke-accessible-rest` |
+| Checked Fill | `--brand-background-compound-rest` |
+
+---
+
+## Switch
+
+**MUI Component:** `Switch` from `@mui/material`
+
+| # | Figma Pattern | Color | Size |
+|---|--------------|-------|------|
+| SW1 | Default Switch | `primary` | `medium` |
+| SW2 | Small Switch | `primary` | `small` |
+
+---
+
+## Chip / Badge / Tag
+
+**MUI Component:** `Chip` from `@mui/material`
+
+### Chip Variants
+
+| # | Figma Pattern | Variant | Color | Size |
+|---|--------------|---------|-------|------|
+| CH1 | Filled (brand/blue) | `filled` | `primary` | `medium` |
+| CH2 | Tint (light blue bg) | `tint` | `primary` | `medium` |
+| CH3 | Outline (bordered) | `outline` | `primary` | `medium` |
+| CH4 | Ghost (text only) | `ghost` | `primary` | `medium` |
+| CH5 | Filled Error | `filled` | `error` | `medium` |
+| CH6 | Tint Error | `tint` | `error` | `medium` |
+
+### Filter Tags (from Figma)
+
+Figma shows "Badge" with `rounded-[16px]`, `brand-background-2-rest` bg, `brand-stroke-2-rest` border, `brand-foreground-2-rest` text, `text.xs.medium`:
+
+| Figma Name | MUI Component | Variant | Color | Size |
+|-----------|---------------|---------|-------|------|
+| Filter Tag (active) | `Chip` | `tint` | `primary` | `small` |
+| Filter Tag (with remove) | `Chip` | `tint` | `primary` | `small` + `onDelete` |
+
+### Chip Typography
+
+| Size | Typography |
+|------|-----------|
+| `small` | `text.xs.medium` (`12px`, `500`) |
+| `medium` | `text.sm.medium` (`14px`, `500`) |
+
+---
+
+## Badge (Notification Badge)
+
+**MUI Component:** `Badge` from `@mui/material`
+
+| # | Figma Pattern | Color | Size |
+|---|--------------|-------|------|
+| BD1 | Default Badge | `default` | `medium` |
+| BD2 | Brand Badge | `brand` | `medium` |
+| BD3 | Success Badge | `success` | `medium` |
+| BD4 | Danger Badge | `danger` | `medium` |
+| BD5 | Warning Badge | `warning` | `medium` |
+| BD6 | Important Badge | `important` | `medium` |
+| BD7 | Dot Badge (6px) | `default` | `dot` |
+| BD8 | Small Badge | `default` | `small` |
+
+### Dot Badge (from Figma)
+
+Figma shows a `size-[6px]` dot indicator next to task descriptions. This maps to:
+
+```typescript
+// Use Badge with dot size
+<Badge color="default" size="dot" variant="dot">
+  <Icon />
+</Badge>
+```
+
+---
+
+## Status Badges (Customer Status)
+
+Figma shows status labels: `Dondurulmus`, `Aktif`, `Hizmet disi`. These are not MUI Badge — they use `Chip`:
+
+| Figma Pattern | MUI Component | Variant | Color |
+|--------------|---------------|---------|-------|
+| Active status | `Chip` | `tint` | `success` |
+| Frozen status | `Chip` | `tint` | `warning` |
+| Out of service | `Chip` | `tint` | `error` |
+
+---
+
+## Alert
+
+**MUI Component:** `Alert` from `@mui/material`
+
+| # | Figma Pattern | Severity | Variant |
+|---|--------------|----------|---------|
+| A1 | Success Alert | `success` | `standard` |
+| A2 | Warning Alert | `warning` | `standard` |
+| A3 | Error Alert | `error` | `standard` |
+| A4 | Info Alert | `info` | `standard` |
+
+---
+
+## Snackbar / Toast
+
+**MUI Component:** `Snackbar` from `@mui/material` + `Alert` inside
+
+```typescript
+// Standard pattern for notifications
+<Snackbar open={open} autoHideDuration={6000} onClose={handleClose}>
+  <Alert severity="success" variant="standard" onClose={handleClose}>
+    Operation completed successfully
+  </Alert>
+</Snackbar>
+```
+
+---
+
+## Dialog / Modal
+
+**MUI Component:** `Dialog` from `@mui/material`
+
+| Property | Value |
+|----------|-------|
+| **Paper Elevation** | `theme.shadows[6]` (28px blur) |
+| **Paper Border Radius** | `theme.shape.borderRadius` (8px) |
+| **Backdrop** | `--neutral-background-overlay-rest` |
+
+```typescript
+// Standard pattern
+<Dialog open={open} onClose={handleClose}>
+  <DialogTitle>Title</DialogTitle>
+  <DialogContent>
+    <DialogContentText>Description</DialogContentText>
+  </DialogContent>
+  <DialogActions>
+    <Button variant="outlined" size="medium" color="secondary" onClick={handleClose}>
+      Cancel
+    </Button>
+    <Button variant="contained" size="medium" color="primary" onClick={handleConfirm}>
+      Confirm
+    </Button>
+  </DialogActions>
+</Dialog>
+```
+
+---
+
+## Menu (Dropdown Menu)
+
+**MUI Component:** `Menu` + `MenuItem` from `@mui/material`
+
+| Property | Value |
+|----------|-------|
+| **Paper Elevation** | `theme.shadows[4]` (8px blur) |
+| **Border Radius** | `theme.shape.borderRadius` (8px) |
+
+---
+
+## Tooltip
+
+**MUI Component:** `Tooltip` from `@mui/material`
+
+Tooltip styling is handled by theme overrides. Use standard MUI Tooltip API.
+
+---
+
+## Table / Data Grid
+
+OneHub tables are **not** MUI `Table` — they use custom styled `Box` rows with flex layout.
+
+### Table Structure (from Figma)
+
+| Element | Figma Height | Background | Border |
+|---------|-------------|------------|--------|
+| **Table Header** | `40px` | `--neutral-background-2-rest` (`#fafafa`) | Bottom: `--neutral-stroke-3-rest` |
+| **Table Row** | `56px` | `--neutral-background-1-rest` (white) | Bottom: `--neutral-stroke-3-rest` |
+| **Table Row Hover** | `56px` | — | Bottom: `--neutral-stroke-3-rest` |
+| **Table Cell Padding** | — | — | `paddingLeft: 32px, paddingRight: 32px` |
+| **Pagination Row** | `56px` | `--neutral-background-1-rest` | Top: `--neutral-stroke-3-rest` |
+
+### Table Typography
+
+| Element | Typography | Color |
+|---------|-----------|-------|
+| Header text | `text.xs.medium` (`12px`, `500`) | `neutral.foreground[1].rest` |
+| Row primary text | `text.sm.medium` (`14px`, `500`) | `neutral.foreground[1].rest` |
+| Row secondary text | `text.sm.regular` (`14px`, `400`) | `neutral.foreground[4].rest` |
+| Date number (large) | `text.lg.medium` (`18px`, `500`) | `neutral.foreground[2].rest` |
+| Date month (small) | `text.sm.regular` (`14px`, `400`) | `neutral.foreground[4].rest` |
+
+### Search & Filter Bar
+
+| Element | MUI Component(s) | Notes |
+|---------|-----------------|-------|
+| Search Input | `TextField` color="neutral" size="medium" + search icon | `placeholder="Ara"` |
+| Filter Button | `Button` variant="text" size="medium" color="secondary" | Gray bg, border, filter icon + "Filtreler" |
+| Active Filter Tags | `Chip` variant="tint" color="primary" size="small" | `onDelete` for remove |
+| Clear Button | `Button` variant="text" size="medium" color="primary" | Transparent bg, delete icon |
+
+### Pagination
+
+| Element | MUI Component |
+|---------|---------------|
+| Pagination controls | `Pagination` or `TablePagination` from `@mui/material` |
+
+---
+
+## Tabs
+
+**MUI Component:** `Tabs` + `Tab` from `@mui/material`
+
+Tab styling is handled by theme overrides. Use standard MUI Tabs API.
+
+| Property | Figma Spec |
+|----------|-----------|
+| Tab indicator | Blue, `2px` height |
+| Active tab text | `text.sm.semibold`, `brand.foreground[1].rest` |
+| Inactive tab text | `text.sm.regular`, `neutral.foreground[2].rest` |
+
+---
+
+## Cards
+
+**MUI Component:** `Card` / `Paper` from `@mui/material`
+
+| Property | Value |
+|----------|-------|
+| **Border Radius** | `theme.shape.borderRadius` (8px) |
+| **Background** | `--neutral-background-1-rest` |
+| **Default Elevation** | `theme.shadows[0]` (none) |
+| **Elevated** | `theme.shadows[3]` (4px blur) |
+
+---
+
+## Paper
+
+**MUI Component:** `Paper` from `@mui/material`
+
+| Property | Value |
+|----------|-------|
+| **Border Radius** | `theme.shape.borderRadius` (8px) |
+| **Border** | `--neutral-stroke-3-rest` (`1px solid #f0f0f0`) |
+| **Background** | `--neutral-background-1-rest` |
+
+---
+
+## Sidebar / Navigation
+
+**Layout Component:** `WithSidebarLayout` from `@turknet/onehub/layouts/page/WithSidebar`
+
+| Property | Figma Spec |
+|----------|-----------|
+| Width | `256px` (collapsed: `64px`) |
+| Background | Varies (light/dark) |
+| Nav items | `CollapsableListItem` |
+
+---
+
+## Date Picker
+
+**MUI Component:** `DatePicker` from `@mui/x-date-pickers`
+
+DatePicker styling is handled by theme overrides. Uses `dayjs` adapter.
+
+---
+
+## Autocomplete
+
+**MUI Component:** `Autocomplete` from `@mui/material`
+
+| # | Figma Pattern | Size |
+|---|--------------|------|
+| AC1 | Default Autocomplete | `medium` |
+| AC2 | Large Autocomplete | `large` |
+
+Uses same color system as TextField.
+
+---
+
+## Slider
+
+**MUI Component:** `Slider` from `@mui/material`
+
+Slider styling is handled by theme overrides.
+
+---
+
+## Link
+
+**MUI Component:** `Link` from `@mui/material`
+
+| Property | Value |
+|----------|-------|
+| Color | `brand.foreground.compound.rest` |
+| Typography | Inherits from parent |
+
+---
+
+## Icon
+
+**Icons:** Import from `@turknet/onehub/icons` (SVG React components) or the project's Tune icon font.
+
+```typescript
+// Preferred: SVG icon from theme package
+import { CheckIcon, ChevronDownIcon, SearchIcon } from '@turknet/onehub/icons'
+
+// Alternative: Tune icon font (if project uses it)
+import { TuneIcon } from '@/components/ui/icon'
+<TuneIcon name="check" />
+```
+
+---
+
+## Avatar
+
+**MUI Component:** `Avatar` from `@mui/material`
+
+| # | Size | Dimensions |
+|---|------|-----------|
+| AV1 | `dot` | `8px` |
+| AV2 | `extra-small` | `24px` |
+| AV3 | `small` | `32px` |
+| AV4 | `medium` | `40px` |
+| AV5 | `large` | `48px` |
+| AV6 | `extra-large` | `64px` |
+
+---
+
+## List
+
+**MUI Component:** `List` / `ListItem` / `ListItemButton` from `@mui/material`
+
+List styling is handled by theme overrides.
+
+---
+
+## Typography
+
+**MUI Component:** `Typography` from `@mui/material`
+
+See `DESIGN_TOKENS_MAP.md#typography-token-map` for the complete variant list.
+
+```typescript
+// ✅ CORRECT — Use defined variants
+<Typography variant="text.sm.medium">Label</Typography>
+<Typography variant="display.xs.bold">Page Title</Typography>
+
+// ❌ WRONG — MUI default variants are DISABLED
+<Typography variant="h1">Title</Typography>
+<Typography variant="body1">Text</Typography>
+```
+
+---
+
+## Components NOT Allowed (No Theme Override)
+
+The following MUI components do NOT have theme overrides and MUST NOT be used:
+
+| Component | Reason | Alternative |
+|-----------|--------|-------------|
+| `ToggleButton` | Not overridden | Use `Chip` or `Button` group |
+| `Rating` | Not overridden | Custom solution |
+| `SpeedDial` | Not overridden | Custom solution |
+| `BottomNavigation` | Not overridden | Custom solution |
+| `MobileStepper` | Not overridden | Custom solution |
+| `ImageList` | Not overridden | CSS Grid/Flex |
+
+---
+
+## Quick Reference: Figma → MUI
+
+| If you see in Figma... | Use this MUI component |
+|------------------------|----------------------|
+| A filled blue button | `Button variant="contained" color="primary"` |
+| An outlined gray button | `Button variant="outlined" color="secondary"` |
+| A text-only button | `Button variant="text" color="primary"` |
+| A text input field | `TextField color="neutral"` |
+| A dropdown selector | `Select color="neutral"` |
+| A checkbox | `Checkbox color="primary"` |
+| A radio button | `Radio color="primary"` |
+| A toggle switch | `Switch color="primary"` |
+| A blue tag/chip | `Chip variant="tint" color="primary"` |
+| A red error chip | `Chip variant="tint" color="error"` |
+| A filter pill with X | `Chip variant="tint" color="primary" onDelete={...}` |
+| A status dot (6px) | `Badge size="dot" color="..."` |
+| A table header | Custom Box with `text.xs.medium` |
+| A table data row | Custom Box with `text.sm.medium` / `text.sm.regular` |
+| A success message | `Alert severity="success"` |
+| A modal/dialog | `Dialog` |
+| A tooltip on hover | `Tooltip` |
+| A date picker | `DatePicker` (from `@mui/x-date-pickers`) |
+| A search with dropdown | `Autocomplete` |
+| Navigation tabs | `Tabs` + `Tab` |
+| A card container | `Card` / `Paper` |