@turk.net/mui 3.0.7 → 3.0.8

package/PAGE_PATTERNS.md

@@ -0,0 +1,509 @@
+# OneHub Page Patterns
+
+> **Purpose:** Standardized page patterns for OneHub modules. When creating a new page, match it to the closest pattern below and follow the exact structure, layout, component set, and spacing grid.
+>
+> **All patterns MUST use OneHub theme rules:** typography variants, spacing via `theme.spacing()`, colors via CSS custom properties.
+
+---
+
+## Pattern 1: List Page (Table + Filters)
+
+**Use case:** Task lists, customer lists, ticket lists, lead lists, any tabular data with search/filter.
+
+### Layout
+
+```
+TabBasedLayout (app level)
+  └── DashboardLayout / WithSidebarLayout (page level)
+        └── PageContentContainer
+              ├── PageContentHeader (title + actions)
+              └── Content Area
+                    ├── Search & Filter Bar
+                    ├── Active Filter Tags (Chips)
+                    ├── Table Header Row
+                    ├── Table Data Rows
+                    └── Pagination
+```
+
+### Component Breakdown
+
+| Element | Component | Props |
+|---------|-----------|-------|
+| Page title | `Typography` | `variant="display.xs.bold"` |
+| Search input | `TextField` | `color="neutral" size="medium" placeholder="Ara"` |
+| Search icon | `SearchIcon` from icons | `size: 20px` |
+| Filter button | `Button` | `variant="text" size="medium" color="secondary"` |
+| Active filter tags | `Chip` | `variant="tint" color="primary" size="small" onDelete={...}` |
+| Clear filters button | `Button` | `variant="text" size="medium" color="primary"` |
+| Table header | Custom `Box` | `bg: neutral.background[2].rest`, `height: 40px` |
+| Table header text | `Typography` | `variant="text.xs.medium"` |
+| Table row | Custom `Box` | `bg: neutral.background[1].rest`, `height: 56px` |
+| Table primary text | `Typography` | `variant="text.sm.medium" color="neutral.foreground[1].rest"` |
+| Table secondary text | `Typography` | `variant="text.sm.regular" color="neutral.foreground[4].rest"` |
+| Status indicator | `Badge` or `Chip` | Depends on status type |
+| Pagination | `Pagination` | `size="medium" color="primary"` |
+
+### Spacing Grid
+
+```
+Table cell:     paddingLeft/Right: theme.spacing(8)   (32px)
+Table header:   height: theme.spacing(10)              (40px)
+Table row:      height: theme.spacing(14)              (56px)
+Row gap:        gap: theme.spacing(2)                  (8px)
+Section gap:    marginBottom: theme.spacing(4)         (16px)
+```
+
+### Figma Reference
+
+- `My task table` (`364:28717`)
+- `Team task table` (`694:41994`)
+- `Customer table` (`2291:40548`)
+- `Ticket List table` (`9148:52401`)
+
+### Example Structure
+
+```tsx
+function TaskListPage() {
+  return (
+    <PageContentContainer>
+      <PageContentHeader>
+        <Typography variant="display.xs.bold">My Tasks</Typography>
+        <Button variant="contained" color="primary" size="medium">
+          New Task
+        </Button>
+      </PageContentHeader>
+
+      {/* Search & Filter Bar */}
+      <Box sx={{ display: 'flex', gap: 2, mb: 2 }}>
+        <TextField
+          color="neutral"
+          size="medium"
+          placeholder="Ara"
+          InputProps={{ startAdornment: <SearchIcon /> }}
+          sx={{ flex: 1 }}
+        />
+        <Button variant="text" size="medium" color="secondary" startIcon={<FilterIcon />}>
+          Filters
+        </Button>
+      </Box>
+
+      {/* Active Filter Tags */}
+      <Box sx={{ display: 'flex', gap: 1, mb: 2 }}>
+        <Chip variant="tint" color="primary" size="small" label="Today" onDelete={handleRemove} />
+      </Box>
+
+      {/* Table */}
+      <Box sx={{ border: 1, borderColor: 'var(--neutral-stroke-3-rest)', borderRadius: 1 }}>
+        {/* Header */}
+        <Box sx={{
+          display: 'flex',
+          px: 8,
+          height: 40,
+          alignItems: 'center',
+          bgcolor: 'var(--neutral-background-2-rest)',
+          borderBottom: 1,
+          borderColor: 'var(--neutral-stroke-3-rest)'
+        }}>
+          <Typography variant="text.xs.medium" sx={{ minWidth: 140 }}>Date</Typography>
+          <Typography variant="text.xs.medium" sx={{ minWidth: 90 }}>Customer</Typography>
+          <Typography variant="text.xs.medium" sx={{ flex: 1 }}>Description</Typography>
+          <Typography variant="text.xs.medium">Rating</Typography>
+        </Box>
+
+        {/* Rows */}
+        {tasks.map(task => (
+          <Box key={task.id} sx={{
+            display: 'flex',
+            px: 8,
+            height: 56,
+            alignItems: 'center',
+            borderBottom: 1,
+            borderColor: 'var(--neutral-stroke-3-rest)',
+            bgcolor: 'var(--neutral-background-1-rest)'
+          }}>
+            <Box sx={{ minWidth: 140 }}>
+              <Typography variant="text.lg.medium" color="var(--neutral-foreground-2-rest)">06</Typography>
+              <Typography variant="text.sm.regular" color="var(--neutral-foreground-4-rest)">WED, THU</Typography>
+            </Box>
+            <Typography variant="text.sm.regular" color="var(--neutral-foreground-4-rest)" sx={{ minWidth: 90 }}>
+              Gizem K.
+            </Typography>
+            <Typography variant="text.sm.medium" sx={{ flex: 1 }}>{task.description}</Typography>
+            <Box sx={{ display: 'flex', gap: 1 }}>
+              <FaceHappyIcon />
+              <MessageIcon />
+            </Box>
+          </Box>
+        ))}
+      </Box>
+
+      {/* Pagination */}
+      <Box sx={{ display: 'flex', justifyContent: 'center', mt: 4 }}>
+        <Pagination count={totalPages} size="medium" color="primary" />
+      </Box>
+    </PageContentContainer>
+  );
+}
+```
+
+---
+
+## Pattern 2: Detail Page
+
+**Use case:** Task detail, customer detail, ticket detail — viewing a single record with multiple sections.
+
+### Layout
+
+```
+TabBasedLayout
+  └── WithSidebarLayout
+        └── PageContentContainer
+              ├── PageContentHeader (back button + title)
+              ├── Tab Navigation (optional)
+              └── Content Sections
+                    ├── Section Card 1
+                    ├── Section Card 2
+                    └── ...
+```
+
+### Component Breakdown
+
+| Element | Component | Props |
+|---------|-----------|-------|
+| Back button | `Button` | `variant="text" size="medium" color="primary"` |
+| Page title | `Typography` | `variant="display.xs.bold"` |
+| Section tabs | `Tabs` + `Tab` | Active: `text.sm.semibold`, Inactive: `text.sm.regular` |
+| Section card | `Paper` | `elevation={0}` |
+| Section title | `Typography` | `variant="text.lg.medium"` |
+| Field label | `Typography` | `variant="text.xs.regular" color="neutral.foreground[2].rest"` |
+| Field value | `Typography` | `variant="text.sm.regular" color="neutral.foreground[1].rest"` |
+| Status badge | `Chip` | `variant="tint" size="small"` |
+| Action buttons | `Button` | `variant="contained" color="primary"` |
+
+### Spacing Grid
+
+```
+Section gap:       marginBottom: theme.spacing(4)      (16px)
+Card padding:      padding: theme.spacing(4)            (16px)
+Field row gap:     gap: theme.spacing(2)                (8px)
+Field label-value: marginBottom: theme.spacing(1)       (4px)
+```
+
+### Example Structure
+
+```tsx
+function DetailPage() {
+  return (
+    <PageContentContainer>
+      <PageContentHeader>
+        <Box sx={{ display: 'flex', alignItems: 'center', gap: 2 }}>
+          <Button variant="text" size="medium" color="primary" startIcon={<ArrowLeftIcon />}>
+            Back
+          </Button>
+          <Typography variant="display.xs.bold">Task Detail</Typography>
+        </Box>
+        <Box sx={{ display: 'flex', gap: 2 }}>
+          <Button variant="outlined" size="medium" color="secondary">Transfer</Button>
+          <Button variant="contained" size="medium" color="primary">Complete</Button>
+        </Box>
+      </PageContentHeader>
+
+      {/* Tabs */}
+      <Tabs value={tab} onChange={handleTabChange} sx={{ mb: 4 }}>
+        <Tab label="Overview" />
+        <Tab label="History" />
+      </Tabs>
+
+      {/* Content */}
+      <Paper elevation={0} sx={{ p: 4, mb: 4 }}>
+        <Typography variant="text.lg.medium" sx={{ mb: 4 }}>Customer Info</Typography>
+        <Box sx={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: 4 }}>
+          <Box>
+            <Typography variant="text.xs.regular" color="var(--neutral-foreground-2-rest)">Name</Typography>
+            <Typography variant="text.sm.regular">Gizem K.</Typography>
+          </Box>
+          <Box>
+            <Typography variant="text.xs.regular" color="var(--neutral-foreground-2-rest)">Status</Typography>
+            <Chip variant="tint" color="success" size="small" label="Active" />
+          </Box>
+        </Box>
+      </Paper>
+    </PageContentContainer>
+  );
+}
+```
+
+---
+
+## Pattern 3: Form Page
+
+**Use case:** New task, edit task, settings forms, any data entry page.
+
+### Layout
+
+```
+TabBasedLayout
+  └── WithSidebarLayout
+        └── PageContentContainer
+              ├── PageContentHeader (title)
+              ├── Form (Formik)
+              │     ├── Form Section 1
+              │     │     ├── Field Row
+              │     │     └── ...
+              │     └── Form Section 2
+              └── Form Actions (Submit + Cancel)
+```
+
+### Component Breakdown
+
+| Element | Component | Props |
+|---------|-----------|-------|
+| Page title | `Typography` | `variant="display.xs.bold"` |
+| Form wrapper | `form` + `Formik` | Formik `onSubmit` handler |
+| Section title | `Typography` | `variant="text.lg.medium"` |
+| Text input | `TextField` | `color="neutral" size="medium" fullWidth` |
+| Dropdown | `Select` | `color="neutral" size="medium"` |
+| Autocomplete | `Autocomplete` | `size="medium" color="neutral"` |
+| Radio group | `RadioGroup` + `Radio` | `color="primary"` |
+| Checkbox | `Checkbox` + `FormControlLabel` | `color="primary"` |
+| Switch toggle | `Switch` + `FormControlLabel` | `color="primary"` |
+| Date picker | `DatePicker` | `dayjs` adapter |
+| Error message | `FormHelperText` | `error` |
+| Submit button | `Button` | `variant="contained" color="primary" size="medium"` |
+| Cancel button | `Button` | `variant="outlined" color="secondary" size="medium"` |
+
+### Spacing Grid
+
+```
+Section gap:    marginBottom: theme.spacing(4)     (16px)
+Field row gap:  gap: theme.spacing(2)              (8px)
+Label margin:   marginBottom: theme.spacing(1)     (4px)
+Field fullWidth: fullWidth
+Form actions:   gap: theme.spacing(2), justifyContent: flex-end
+```
+
+### Example Structure
+
+```tsx
+function CreateTaskForm() {
+  const formik = useFormik({
+    initialValues: { title: '', customer: null, priority: 'medium', notify: false },
+    validationSchema: yup.object({
+      title: yup.string().required('Title is required'),
+      customer: yup.object().required('Customer is required'),
+    }),
+    onSubmit: (values) => createTask(values),
+  });
+
+  return (
+    <PageContentContainer>
+      <PageContentHeader>
+        <Typography variant="display.xs.bold">New Task</Typography>
+      </PageContentHeader>
+
+      <form onSubmit={formik.handleSubmit}>
+        <Paper elevation={0} sx={{ p: 4, mb: 4 }}>
+          <Typography variant="text.lg.medium" sx={{ mb: 4 }}>Task Details</Typography>
+
+          <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
+            <TextField
+              name="title"
+              label="Title"
+              color="neutral"
+              size="medium"
+              fullWidth
+              value={formik.values.title}
+              onChange={formik.handleChange}
+              error={formik.touched.title && Boolean(formik.errors.title)}
+              helperText={formik.touched.title && formik.errors.title}
+            />
+
+            <Autocomplete
+              options={customers}
+              size="medium"
+              renderInput={(params) => (
+                <TextField {...params} label="Customer" color="neutral" />
+              )}
+              value={formik.values.customer}
+              onChange={(_, value) => formik.setFieldValue('customer', value)}
+            />
+
+            <FormControlLabel
+              control={<Switch color="primary" checked={formik.values.notify} />}
+              label="Notify team"
+            />
+          </Box>
+        </Paper>
+
+        <Box sx={{ display: 'flex', justifyContent: 'flex-end', gap: 2 }}>
+          <Button variant="outlined" size="medium" color="secondary">Cancel</Button>
+          <Button variant="contained" size="medium" color="primary" type="submit">
+            Create
+          </Button>
+        </Box>
+      </form>
+    </PageContentContainer>
+  );
+}
+```
+
+---
+
+## Pattern 4: Dashboard
+
+**Use case:** Overview screens with metrics, charts, quick actions.
+
+### Layout
+
+```
+TabBasedLayout
+  └── WithSidebarLayout
+        └── PageContentContainer
+              ├── PageContentHeader (title + date filter)
+              ├── Metrics Row (Cards)
+              ├── Charts/Graphs Section
+              └── Quick Actions
+```
+
+### Component Breakdown
+
+| Element | Component | Props |
+|---------|-----------|-------|
+| Page title | `Typography` | `variant="display.xs.bold"` |
+| Date filter | `Chip` or `Select` | Filter chips shown in Figma |
+| Metric card | `Paper` | `elevation={0}` |
+| Metric value | `Typography` | `variant="display.md.semibold"` |
+| Metric label | `Typography` | `variant="text.xs.regular" color="neutral.foreground[2].rest"` |
+| Chart area | Custom component | Uses ApexCharts or similar |
+
+### Spacing Grid
+
+```
+Card gap:       gap: theme.spacing(2)             (8px)
+Card padding:   padding: theme.spacing(4)         (16px)
+Section gap:    marginBottom: theme.spacing(4)    (16px)
+```
+
+---
+
+## Pattern 5: Dialog/Modal
+
+**Use case:** Confirmation dialogs, quick edit forms, transfer/ticket close.
+
+### Component Breakdown
+
+| Element | Component | Props |
+|---------|-----------|-------|
+| Dialog | `Dialog` | `maxWidth`, `fullWidth` options |
+| Title | `DialogTitle` | Typography: `text.lg.medium` |
+| Content | `DialogContent` | Typography: `text.md.regular` |
+| Content text | `DialogContentText` | — |
+| Primary action | `Button` | `variant="contained" color="primary"` |
+| Secondary action | `Button` | `variant="outlined" color="secondary"` |
+| Destructive action | `Button` | `variant="contained" color="error"` |
+
+### Example Structure
+
+```tsx
+<Dialog open={open} onClose={handleClose} maxWidth="sm" fullWidth>
+  <DialogTitle>Confirm Action</DialogTitle>
+  <DialogContent>
+    <DialogContentText>
+      Are you sure you want to close this ticket?
+    </DialogContentText>
+  </DialogContent>
+  <DialogActions>
+    <Button variant="outlined" size="medium" color="secondary" onClick={handleClose}>
+      Cancel
+    </Button>
+    <Button variant="contained" size="medium" color="error" onClick={handleConfirm}>
+      Close Ticket
+    </Button>
+  </DialogActions>
+</Dialog>
+```
+
+---
+
+## Pattern 6: Notifications
+
+**Use case:** Success/error/warning feedback to users.
+
+### Component
+
+```typescript
+// Use notistack's useSnackbar hook (preferred)
+const { enqueueSnackbar } = useSnackbar();
+
+enqueueSnackbar('Operation successful', { variant: 'success' });
+enqueueSnackbar('Something went wrong', { variant: 'error' });
+
+// OR: MUI Snackbar + Alert
+<Snackbar open={open} autoHideDuration={6000} onClose={handleClose}>
+  <Alert severity="success" onClose={handleClose}>Message</Alert>
+</Snackbar>
+```
+
+---
+
+## Pattern 7: Empty State
+
+**Use case:** When a list or search returns no results.
+
+### Example
+
+```tsx
+<Box sx={{
+  display: 'flex',
+  flexDirection: 'column',
+  alignItems: 'center',
+  justifyContent: 'center',
+  py: 16
+}}>
+  <EmptyIcon style={{ width: 64, height: 64 }} />
+  <Typography variant="text.lg.medium" sx={{ mt: 4 }}>
+    No results found
+  </Typography>
+  <Typography variant="text.sm.regular" color="var(--neutral-foreground-4-rest)" sx={{ mt: 1 }}>
+    Try adjusting your search or filter criteria
+  </Typography>
+</Box>
+```
+
+---
+
+## Pattern 8: Loading State
+
+**Use case:** While data is being fetched.
+
+### Example
+
+```tsx
+// Skeleton loader (preferred)
+<Box sx={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
+  <Skeleton variant="rectangular" height={40} />
+  <Skeleton variant="rectangular" height={56} />
+  <Skeleton variant="rectangular" height={56} />
+  <Skeleton variant="rectangular" height={56} />
+</Box>
+
+// Or: CircularProgress
+<Box sx={{ display: 'flex', justifyContent: 'center', py: 16 }}>
+  <CircularProgress />
+</Box>
+```
+
+---
+
+## Quick Decision Guide
+
+| If you need to... | Use Pattern |
+|-------------------|-------------|
+| Show a list of records | Pattern 1: List Page |
+| View single record details | Pattern 2: Detail Page |
+| Collect user input | Pattern 3: Form Page |
+| Show metrics/overview | Pattern 4: Dashboard |
+| Confirm destructive action | Pattern 5: Dialog/Modal |
+| Show feedback message | Pattern 6: Notifications |
+| Handle no-data state | Pattern 7: Empty State |
+| Handle loading state | Pattern 8: Loading State |