@turk.net/mui 3.0.7 → 3.0.8

package/DESIGN_RULES.md

@@ -0,0 +1,399 @@
+# OneHub Design Rules
+
+> **Purpose:** Mandatory design constraints that ALL AI agents and developers MUST follow when writing UI code for OneHub.
+>
+> **Language:** This document uses RFC 2119 keywords: MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, OPTIONAL.
+>
+> **Violation of any MUST/MUST NOT rule is a design defect.**
+
+---
+
+## Rule 1: Typography
+
+### 1.1 — Variant Selection
+
+**MUST ONLY use Untitled UI custom typography variants.**
+
+MUI default variants (`h1`-`h6`, `body1`, `body2`, `subtitle1`, `subtitle2`, `caption`, `button`) are **DISABLED** in the theme and MUST NOT be used.
+
+```typescript
+// ✅ CORRECT
+<Typography variant="display.lg.bold">Page Title</Typography>
+<Typography variant="text.md.regular">Body text</Typography>
+<Typography variant="text.xs.medium">Label</Typography>
+
+// ❌ WRONG — MUI default variants are disabled
+<Typography variant="h1">Title</Typography>
+<Typography variant="body1">Text</Typography>
+```
+
+### 1.2 — Font Family
+
+**MUST use Inter font exclusively.** The host project MUST define `--font-inter` CSS variable.
+
+Font weights: `400` (Regular), `500` (Medium), `600` (Semibold), `700` (Bold).
+
+### 1.3 — Typography Hierarchy
+
+| Context | Variant | Weight |
+|---------|---------|--------|
+| Page title | `display.lg.bold` or `display.md.semibold` | 600-700 |
+| Section header | `text.lg.medium` or `text.md.semibold` | 500-600 |
+| Body text | `text.md.regular` or `text.sm.regular` | 400 |
+| Table header | `text.xs.medium` | 500 |
+| Table cell | `text.sm.regular` | 400 |
+| Form label | `text.sm.regular` or `text.xs.regular` | 400 |
+| Helper/error text | `text.xs.regular` | 400 |
+| Button text | `text.sm.medium` | 500 |
+| Chip/Badge text | `text.xs.medium` | 500 |
+
+---
+
+## Rule 2: Colors
+
+### 2.1 — Access Method
+
+**MUST reference colors exclusively via CSS custom properties OR `theme.vars.palette.*` paths.** Raw hex values, RGB values, or `theme.palette` (non-vars) MUST NOT be used.
+
+> **IMPORTANT — MUI v5 `--palette-` prefix:** Projeler MUI v5 kullandığı için CSS custom property'lere `--palette-` prefix'i ile erişilmelidir. Prefix'siz yazım (`var(--neutral-foreground-1-rest)`) çalışmaz.
+
+```typescript
+// ✅ CORRECT — CSS custom property (MUI v5 — --palette- prefix ŞART)
+sx={{ color: 'var(--palette-neutral-foreground-1-rest)' }}
+sx={{ bgcolor: 'var(--palette-brand-background-1-rest)' }}
+
+// ✅ CORRECT — theme.vars
+sx={{ bgcolor: theme.vars.palette.brand.background[1].rest }}
+
+// ❌ WRONG — raw hex value
+sx={{ color: '#242424' }}
+
+// ❌ WRONG — non-vars palette
+sx={{ bgcolor: theme.palette.primary.main }}
+
+// ❌ WRONG — prefix eksik (MUI v5'te çalışmaz)
+sx={{ color: 'var(--neutral-foreground-1-rest)' }}
+```
+
+### 2.2 — Color by Component
+
+Component color props MUST use ONLY the values listed below:
+
+| Component | Valid `color` Values |
+|-----------|---------------------|
+| `Button` | `primary`, `secondary`, `error` |
+| `TextField` | `neutral`, `brand`, `danger` |
+| `Select` | `neutral`, `brand`, `danger` |
+| `Checkbox` | `primary`, `error` |
+| `Radio` | `primary`, `error` |
+| `Switch` | `primary`, `error` |
+| `Chip` | `primary`, `secondary`, `error` |
+| `Badge` | `default`, `brand`, `success`, `danger`, `severewarning`, `warning`, `important` |
+| `Alert` | `success`, `warning`, `error`, `info` |
+
+### 2.3 — Shared Colors
+
+`theme.vars.palette.shared.*` colors (red, green, orange, yellow, purple, pink, cyan, lime) MUST ONLY be used in custom components, NOT as `color` props on standard MUI components.
+
+---
+
+## Rule 3: Spacing
+
+### 3.1 — No Magic Numbers
+
+**MUST NOT use raw pixel values for spacing.** All spacing MUST pass through `theme.spacing(n)`.
+
+Base grid: **4px** (`theme.spacing(1)` = 4px).
+
+```typescript
+// ✅ CORRECT
+sx={{ padding: theme.spacing(2) }}       // 8px
+sx={{ gap: theme.spacing(1) }}           // 4px
+sx={{ marginLeft: theme.spacing(3) }}    // 12px
+
+// ❌ WRONG — magic numbers
+sx={{ padding: '8px' }}
+sx={{ padding: 8 }}
+sx={{ gap: '4px' }}
+```
+
+### 3.2 — Standard Spacing Values
+
+| Context | Value | `theme.spacing()` |
+|---------|-------|-------------------|
+| Tight icon gap | 4px | `theme.spacing(1)` |
+| Standard gap | 8px | `theme.spacing(2)` |
+| Button horizontal padding | 12px | `theme.spacing(3)` |
+| Card/section padding | 16px | `theme.spacing(4)` |
+| Large section gap | 24px | `theme.spacing(6)` |
+| Table cell horizontal padding | 32px | `theme.spacing(8)` |
+| Page padding | 64px | `theme.spacing(16)` |
+
+---
+
+## Rule 4: Components
+
+### 4.1 — No Custom Components
+
+**MUST NOT create custom components that duplicate Material UI functionality.** Use MUI components with theme overrides instead.
+
+```typescript
+// ❌ WRONG — custom component duplicating MUI
+function MyButton({ children }: { children: React.ReactNode }) {
+  return <div className="custom-button">{children}</div>;
+}
+
+// ✅ CORRECT — use MUI component
+<Button variant="contained" color="primary">{children}</Button>
+```
+
+### 4.2 — No Inline Styles
+
+**MUST NOT use inline styles (`style={{}}` prop).** Use `sx` prop with theme values or CSS custom properties.
+
+```typescript
+// ❌ WRONG
+<Button style={{ backgroundColor: 'red', padding: '20px' }}>Click</Button>
+
+// ✅ CORRECT
+<Button sx={{ color: theme.vars.palette.danger.foreground[1].rest }}>Click</Button>
+```
+
+### 4.3 — Valid Props Only
+
+**MUST NOT use variant/size/color combinations not defined in `COMPONENT_MAP.md`.** Any undefined combination will not have theme styles applied.
+
+```typescript
+// ❌ WRONG — color="success" not defined for Button
+<Button color="success">Save</Button>
+
+// ❌ WRONG — variant="gradient" not defined
+<Button variant="gradient">Gradient</Button>
+
+// ✅ CORRECT
+<Button variant="contained" color="primary" size="medium">Save</Button>
+```
+
+### 4.4 — Layout Components
+
+**MUST use OneHub layout components for page structure:**
+
+| Layout | Import | Use Case |
+|--------|--------|----------|
+| TabBased | `@turknet/onehub/layouts/app/TabBased` | Tab-based application layout |
+| WithSidebar | `@turknet/onehub/layouts/page/WithSidebar` | Sidebar + content layout |
+| Empty | Custom per module | No layout (passthrough) |
+| Login | Custom per module | Authentication pages |
+
+---
+
+## Rule 5: Icon Usage
+
+### 5.1 — Icon Source
+
+**MUST import icons from `@turknet/onehub/icons`** (SVG React components) or the project's Tune icon font.
+
+```typescript
+// ✅ CORRECT — SVG icons
+import { CheckIcon, ChevronDownIcon } from '@turknet/onehub/icons';
+
+// ✅ CORRECT — Tune icon font
+import { TuneIcon } from '@/components/ui/icon';
+<TuneIcon name="check" />
+```
+
+### 5.2 — Icon Sizing
+
+Standard icon sizes: `16px` (small/inline), `20px` (default), `24px` (large).
+
+---
+
+## Rule 6: Border Radius
+
+| Element | Value | `theme.shape.borderRadius` equivalent |
+|---------|-------|--------------------------------------|
+| Checkbox, small elements | `4px` | `theme.shape.borderRadius / 2` |
+| Buttons, inputs, cards, radio | `8px` | `theme.shape.borderRadius` |
+| Chips, badges, filter tags | `16px` | `theme.shape.borderRadius * 2` |
+
+---
+
+## Rule 7: Elevation / Shadows
+
+**MUST use `theme.shadows[n]` or the `elevation` prop (0-24) on Paper components.**
+
+| Level | Usage |
+|-------|-------|
+| `0` | Flat elements (no shadow) |
+| `2` | Very subtle elevation |
+| `4` | Dropdowns, tooltips |
+| `8` | Dialogs |
+| `16` | Modals |
+| `24` | Top-level overlays |
+
+```typescript
+// ✅ CORRECT
+<Paper elevation={4}>Content</Paper>
+<Card elevation={2}>Content</Card>
+
+// ✅ CORRECT — theme.shadows access
+sx={{ boxShadow: theme.shadows[6] }}
+```
+
+---
+
+## Rule 8: Responsive Design
+
+### 8.1 — Breakpoints
+
+**MUST use MUI breakpoints** via `theme.breakpoints` or `sx` prop.
+
+| Breakpoint | Width |
+|-----------|-------|
+| `xs` | 0px |
+| `sm` | 600px |
+| `md` | 900px |
+| `lg` | 1200px |
+| `xl` | 1536px |
+
+```typescript
+// ✅ CORRECT
+sx={{
+  padding: { xs: theme.spacing(2), md: theme.spacing(4) }
+}}
+```
+
+---
+
+## Rule 9: Forms
+
+### 9.1 — Form Library
+
+**MUST use Formik + Yup** for form handling.
+
+```typescript
+import { useFormik } from 'formik';
+import * as yup from 'yup';
+```
+
+### 9.2 — Form Components
+
+| Field Type | MUI Component |
+|-----------|---------------|
+| Text input | `TextField` |
+| Dropdown | `Select` + `MenuItem` |
+| Autocomplete | `Autocomplete` |
+| Checkbox | `Checkbox` + `FormControlLabel` |
+| Radio group | `RadioGroup` + `Radio` + `FormControlLabel` |
+| Switch | `Switch` + `FormControlLabel` |
+| Date picker | `DatePicker` (`@mui/x-date-pickers`) |
+| Submit | `Button variant="contained" color="primary"` |
+
+---
+
+## Rule 10: File Organization
+
+### 10.1 — Component Placement
+
+| Component Type | Directory |
+|---------------|-----------|
+| Reusable UI components | `src/components/ui/` |
+| Page-specific components | `src/components/pages/<pageName>/` |
+| Layout components | `src/components/layouts/` |
+| API types/models | `src/data/models/` |
+| API services | `src/data/services/` |
+| Custom hooks | `src/data/hooks/` or `src/hooks/` |
+| Redux slices | `src/redux/slices/` |
+| Utility functions | `src/utils/` |
+
+### 10.2 — Naming Conventions
+
+- **Component files:** PascalCase (e.g., `SigninForm.tsx`)
+- **Utility files:** camelCase (e.g., `cookieKeys.ts`)
+- **Type files:** camelCase (e.g., `user.ts`)
+- **Style overrides:** `*.styled.tsx` suffix
+- **Page directories:** camelCase (e.g., `myTasks/`)
+
+---
+
+## Rule 11: Data Fetching
+
+### 11.1 — API Calls
+
+**MUST use React Query (TanStack Query)** for all server data.
+
+```typescript
+import { useQuery, useMutation } from '@tanstack/react-query';
+```
+
+### 11.2 — API Client
+
+**MUST use the Hermes API client** (GraphQL endpoint) configured per module.
+
+---
+
+## Rule 12: Accessibility
+
+### 12.1 — Required Attributes
+
+- All form inputs MUST have associated labels
+- Icon buttons MUST have `aria-label`
+- Tables MUST have proper header rows
+- Color contrast MUST meet WCAG AA standards
+- Focus indicators MUST be visible
+
+### 12.2 — Keyboard Navigation
+
+- All interactive elements MUST be keyboard accessible
+- Dialogs MUST trap focus
+- Tab order MUST follow visual order
+
+---
+
+## Rule 13: Performance
+
+### 13.1 — Bundle Size
+
+- **MUST NOT** import entire MUI library (`import * as Mui from '@mui/material'`)
+- **MUST** use named imports
+- **SHOULD** use React.lazy for page-level code splitting
+
+### 13.2 — Image Optimization
+
+- **MUST** use `next/image` for images
+- **SHOULD** use SVG for icons (preferred over icon fonts)
+
+---
+
+## Rule 14: Module Federation
+
+### 14.1 — Shared Dependencies
+
+Modules MUST share these dependencies via Module Federation (do NOT bundle locally):
+
+- `@mui/material`
+- `@mui/icons-material`
+- `react` / `react-dom`
+- `dayjs`
+- `notistack`
+
+### 14.2 — Remote Components
+
+When consuming remote components from the host application, use `React.lazy`:
+
+```typescript
+const ChangeModuleModal = React.lazy(() => import('components/changeModuleModal'));
+```
+
+---
+
+## Enforcement
+
+These rules are enforced through:
+
+1. **`.opencode/rules/design-compliance.md`** — Always-apply rule for AI agents
+2. **`.opencode/skills/onehub-design-verification/SKILL.md`** — Step-by-step verification skill
+3. **`scripts/verify-design.js`** — Automated compliance scanner
+4. **`ESLINT_DESIGN_RULES.md`** — Lint rules specification (future custom ESLint plugin)
+
+Any violation of MUST/MUST NOT rules found during code review is a **blocking issue**.

package/DESIGN_SOURCES.md

@@ -0,0 +1,198 @@
+# OneHub Design Sources
+
+> **Purpose:** Maps every OneHub module to its Figma design source and provides quick navigation to key design pages.
+>
+> **Usage:** When implementing a new feature for a module, AI agents MUST reference the corresponding Figma source to verify component usage, spacing, typography, and color choices.
+
+---
+
+## Primary Design Files
+
+### 1. Tune UI — Component Library & Design Tokens
+
+| Attribute | Value |
+|-----------|-------|
+| **Figma URL** | https://www.figma.com/design/3HRzKtaYJ7OOHWlxTE0ihw/Tune-UI-%E2%80%93--Beta-v0.1 |
+| **Node ID** | `2371-1464` |
+| **Purpose** | Base component library: Button, TextField, Chip, Badge, Checkbox, Radio, Switch, Select, Autocomplete, etc. All component variants, sizes, and color states. |
+| **Contains** | Component specifications, design tokens, color palette, typography scale, shadow definitions, spacing system |
+| **Doc Pages** | `🔑 Tokens` (design tokens), `Component` (component library), `📕 read Me` (documentation) |
+
+### 2. OneHub Pages & Layouts — Module Screens
+
+| Attribute | Value |
+|-----------|-------|
+| **Figma URL** | https://www.figma.com/design/bbqqjZQvPaVwgk35rDdi6p/05---OneHub---Pages-and-Layouts |
+| **Node ID** | `363-22380` |
+| **Purpose** | Page-level designs for all OneHub modules. Screen layouts, page patterns, content structures. |
+| **Doc Pages** | See module sections below |
+
+### 3. OneHub Yönetim Modül — Administration Module
+
+| Attribute | Value |
+|-----------|-------|
+| **Figma URL** | https://www.figma.com/design/11BlopkoRzfdm6ZyvkasTL/05---OneHub---Yonetim-Mod%C3%BCl |
+| **Node ID** | `17014-14727` |
+| **Purpose** | Dedicated designs for the Support Quality & Communication module |
+
+---
+
+## Module → Design Mapping
+
+### Support Module (`tn.onehub.ui.task`)
+
+| Attribute | Value |
+|-----------|-------|
+| **App Path** | `/support` |
+| **Figma Doc** | OneHub Pages & Layouts |
+| **Page Node ID** | `363:22380` — Pages - Destek Ekibi |
+
+**Key Pages in Figma:**
+
+| Page Name | Figma Section | Key Components Used |
+|-----------|--------------|---------------------|
+| **Task Listing** | `Görev listeleme` (`453:23224`) | Table, SearchInput, Badge/Chip, Filter Button, Pagination, Checkbox |
+| **Task Detail** | `Görev Detay` (`2392:18837`) | Tabs, Form Fields, Buttons, Status Badges, Data Cards |
+| **Customers** | `Müşteriler` (`2392:21320`) | Search Table, Customer Status Badges, Pagination |
+| **Login** | `Oturum açma` (`363:27138`) | SignInForm, TextField, Button, Gradient Background |
+| **Ticket Close/Defer/Transfer** | `Ticket Kapatma, Erteleme, Aktarma` (`2844:24042`) | Dialog, Form, Radio, TextArea, Button |
+| **Call Answering** | `Görüşme Cevaplama` (`3459:30467`) | Form, Radio Buttons, TextField, Button |
+| **Customer Status** | `Kullanıcı Statu Değiştirme` (`4000:38012`) | Dropdown, Status Badge, Button |
+| **Subscriber Info** | `Abone Bilgileri` (`4472:41034`) | Data Cards, Tables, Badges |
+| **Performance** | `Perfomans` (`6320:27443`) | Data Tables, Metrics |
+| **Ticket Flow (Complaint)** | `Şikayet Görev Akışı` (`6567:27967`) | Flow Chart, Form Elements |
+| **AI Explanation** | `AI Açıklama` (`13968:222110`) | Card, Text Content |
+| **Labels** | `Etiketler` (`17708:168933`) | Tag/Chip List, Filter |
+| **Authentication** | `Kimlik Doğrulama` (`18568:124485`) | Form, TextField, Button |
+| **Notifications** | `Notification` (`19592:106701`) | Snackbar/Toast, Alert |
+| **Road Map** | `Ağ Yolu Haritası` (`20073:159756`) | Visual Diagram |
+| **Chat** | `Chat` (`21456:115282`) | Chat Interface, Message Bubbles |
+| **Field Priority** | `Saha Öncelliği` (`23995:123620`) | Data Grid, Badges |
+| **Live Chat** | `Net Uzman Canlı Sohbet` (`24165:177134`) | Chat Interface |
+| **Activity History** | `Aktivite Geçmişi` (`17204:211755`) | Timeline, Data Table |
+| **New Task** | `Yeni Görev oluştur` (`14414:232693`) | Form, Dropdown, Button |
+| **Task Edit** | `Görev Düzenle` (`14414:239260`) | Form, Dropdown, Button |
+| **Connection Check** | `Müşteri Detay - Bağlantı Kontrol` (`11350:147025`) | Status Card, Metrics |
+| **Speed Test History** | `Geçmiş Hız Testi Sonuçları` (`20675:136856`) | Data Table, Charts |
+| **Past Tasks** | `Geçmiş-Gorevler` (`22331:170137`) | Data Table |
+
+---
+
+### Team Lead / Nexus Module (`tn.onehub.ui.nexus`)
+
+| Attribute | Value |
+|-----------|-------|
+| **App Path** | `/support-team-lead` |
+| **Figma Doc** | OneHub Pages & Layouts |
+| **Page Node ID** | `5935:75901` — Pages - Destek Takım Lideri |
+
+---
+
+### Lead Module (`tn.onehub.ui.lead`)
+
+| Attribute | Value |
+|-----------|-------|
+| **App Path** | `/lead` |
+| **Figma Doc** | OneHub Pages & Layouts |
+| **Page Node ID** | `5148:85859` — Pages - Lead Alma |
+
+**Component Library Section:** `Lead table` (`9560:59968`) — Lead-specific table with search, filters, title, row, hover state, pagination.
+
+---
+
+### Order Tracking Module (`tn.onehub.ui.ordertracking`)
+
+| Attribute | Value |
+|-----------|-------|
+| **App Path** | `/order-tracking` |
+| **Figma Doc** | OneHub Pages & Layouts |
+| **Page Node ID** | `16599:257816` — Pages - Sipariş Ekibi |
+
+---
+
+### Activation Module (`tn.onehub.ui.activation`)
+
+| Attribute | Value |
+|-----------|-------|
+| **App Path** | `/activation` |
+| **Figma Doc** | OneHub Pages & Layouts |
+| **Page Node ID** | `15632:51384` — Pages - Aktivasyon |
+
+---
+
+### Funnel Module (`tn.onehub.ui.funnel`)
+
+| Attribute | Value |
+|-----------|-------|
+| **App Path** | `/funnel` |
+| **Figma Doc** | OneHub Pages & Layouts |
+| **Page Node ID** | `22173:310640` — Pages - Funnel |
+
+**Component Library Section:** `Dashboard` (`22810:311671`) — Funnel dashboard components.
+
+---
+
+### Support Quality & Communication Module (`tn.onehub.ui.supportqualcomm`)
+
+| Attribute | Value |
+|-----------|-------|
+| **App Path** | `/support-qual-comm` |
+| **Figma Doc** | OneHub Yönetim Modül |
+| **Page Node ID** | `17014:14727` |
+
+---
+
+### Entrypoint (`tn.onehub.ui.entrypoint`)
+
+| Attribute | Value |
+|-----------|-------|
+| **App Path** | `/login` |
+| **Figma Doc** | OneHub Pages & Layouts |
+| **Design Section** | Login page, Module selection screen |
+
+---
+
+## Design System Component Pages (Shared)
+
+These are located under `Component` (`51:16668`) in the Pages & Layouts document:
+
+| Component Library | Figma Node ID | Description |
+|------------------|---------------|-------------|
+| **Sidebar static** | `62:16343` | Static sidebar variants (Skeleton, User, Rol, Customer, Akkordion) |
+| **Sidebar dynamic** | `241:25857` | Dynamic sidebar (Skeleton, Help, AI) |
+| **My task table** | `364:28717` | Task table with Search/Filter, Title, Task row, Subtask, Pagination |
+| **Team task table** | `694:41994` | Team task table with Filter, Title, Task row, Pagination |
+| **Customer table** | `2291:40548` | Customer table with multiple filter types, Title, Task row, Hover, Pagination |
+| **Lead table** | `9560:59968` | Lead-specific table |
+| **Ticket List table** | `9148:52401` | Ticket list table with hover state |
+| **Netuzman Table** | `2852:33089` | Netuzman-specific table |
+| **IVR Table** | `5272:95132` | IVR settings table |
+| **Comparison Table** | `8366:85886` | Comparison table with icons |
+| **Customer Status** | `2291:41099` | Status badges (Dondurulmus, Aktif, Hizmet disi) |
+| **AI Checkbox Card** | `1195:32250` | Checkbox card component |
+| **Timer** | `1908:60012` | Timer indicator (Above 60, 15-60, Under 15) |
+| **Failure logging** | `3500:35889` | Failure logging form with rest state and empty state |
+| **Team Durum - Net Uzman** | `6280:55681` | Team status table for Net Uzman |
+| **Team Durum - Leader** | `6280:56097` | Team status table for Team Leaders |
+
+---
+
+## How to Use This Reference
+
+### When Creating a New Page
+1. Find your module in the **Module → Design Mapping** section above
+2. Locate the closest matching page design in Figma
+3. Read `COMPONENT_MAP.md` to find the correct MUI component + props for each UI element
+4. Read `DESIGN_TOKENS_MAP.md` for the correct CSS custom property paths
+5. Read `DESIGN_RULES.md` for mandatory constraints
+
+### When Adding a Feature to an Existing Page
+1. Check if the feature exists in Figma for your module
+2. If yes: follow the Figma design exactly
+3. If no: find the closest pattern from the Component library section and adapt
+4. Always run `scripts/verify-design.js` after implementation
+
+### Module Ownership
+- Each module has ONE Figma page section (e.g., `Pages - Destek Ekibi`)
+- Components are shared across modules via the `Component` library page
+- New components MUST be added to the `Component` page first, then used in module pages