# رفع افتادن مودال‌ها به پایین صفحه (portal برای همه مودال‌ها)

## پروژه

`clinicpro` (پنل ادمین React — `assets/admin/`)

## زمینه

بعضی مودال‌ها هنگام باز شدن وسط صفحه نمی‌افتند و «خیلی پایین» یا آفست ظاهر می‌شوند. نمونه‌اش مودال کراپ عکس در صفحه‌ی دکتر بود که با انتقال به `createPortal(document.body)` حل شد.

## مشکل / هدف

کلاس مشترک `.overlay` از `position: fixed; inset: 0` استفاده می‌کند (تعریف در `assets/admin/styles.css:613`). طبق مشخصات CSS، وقتی یک عنصر `position: fixed` داخل ancestorـی رندر شود که یکی از این خواص را دارد، دیگر نسبت به viewport نیست بلکه نسبت به همان ancestor محاسبه می‌شود:

- `transform` (حتی `transform: translateZ(0)` یا انیمیشن‌های `pop`/`slidein` که transform دارند)
- `filter` / `backdrop-filter`
- `perspective`, `will-change: transform`, `contain: paint/layout`

در نتیجه هر مودالی که `.overlay` را **inline در عمق درخت کامپوننت** (داخل کارت‌ها/کانتینرهای transform‌دار) رندر کند، پایین/آفست می‌افتد.

**راه‌حل استاندارد پروژه:** رندر مودال از طریق `createPortal(..., document.body)` تا از زنجیره‌ی ancestorها خارج شود. کامپوننت‌های `components/ui/Modal.tsx` و `components/ImageCropModal.tsx` همین کار را می‌کنند و درست‌اند — الگوی مرجع همین‌هاست.

هدف: **همه‌ی مودال‌های `.overlay` که هنوز portal ندارند** به portal منتقل شوند تا این مشکل در «هر جایی که مودال باز می‌شود» حل شود.

## فایل‌های مرتبط

| فایل | وضعیت | نقش |
|------|------|-----|
| `assets/admin/components/ui/Modal.tsx` | ✅ portal دارد | الگوی مرجع — تغییر نده |
| `assets/admin/components/ImageCropModal.tsx` | ✅ portal دارد | الگوی مرجع — تغییر نده |
| `assets/admin/components/ui/ConfirmDialog.tsx` | ❌ بدون portal | پرکاربردترین؛ اولویت اول |
| `assets/admin/components/ui/InviteDoctorModal.tsx` | ❌ بدون portal | مودال دعوت دکتر |
| `assets/admin/components/layout/Topbar.tsx` | ❌ بدون portal | overlay (خط ~75) |
| `assets/admin/pages/UsersPage.tsx` | ❌ بدون portal | مودال inline (خط ~104) |
| `assets/admin/pages/ClinicsPage.tsx` | ❌ بدون portal | مودال افزودن (خط ~247) |
| `assets/admin/pages/PreRegistrationsPage.tsx` | ❌ بدون portal | مودال رد کردن (خط ~207) |
| `assets/admin/pages/ClinicDetailPage.tsx` | ❌ یک مورد بدون portal (خط ~354) | بقیه‌ی overlayهایش portal دارند |
| `assets/admin/styles.css` | مرجع | تعریف `.overlay` (خط 613) — تغییر نده |

## وضعیت فعلی

نمونه‌ی `ConfirmDialog.tsx` (بدون portal — همین الگو در بقیه هم هست):

```tsx
import React from 'react';
import { XMarkIcon, ExclamationTriangleIcon } from '@heroicons/react/24/outline';

export default function ConfirmDialog({ open, /* ... */ onConfirm, onCancel }: Props) {
  if (!open) return null;

  return (
    <div className="overlay" onClick={onCancel}>
      <div className="modal" style={{ maxWidth: 420 }} onClick={(e) => e.stopPropagation()}>
        {/* ... */}
      </div>
    </div>
  );
}
```

`.overlay` (styles.css:613) — درست است، دست نزن:

```css
.overlay {
  position: fixed; inset: 0; z-index: 1000; display: grid; place-items: center; padding: 20px;
  background: rgba(8,13,22,.5); backdrop-filter: blur(4px); ...
}
```

## وظایف

### ۱. ساخت یک کامپوننت کمکی `Portal` (یک‌بار، برای جلوگیری از تکرار)

فایل جدید: `assets/admin/components/ui/Portal.tsx`

```tsx
import { useEffect, useState } from 'react';
import { createPortal } from 'react-dom';

export default function Portal({ children }: { children: React.ReactNode }) {
  const [mounted, setMounted] = useState(false);
  useEffect(() => setMounted(true), []);
  if (!mounted) return null;
  return createPortal(children, document.body);
}
```

> نکته: چون این SPA فقط client-side رندر می‌شود، `createPortal` مستقیم هم کار می‌کند؛ ولی داشتن wrapper واحد الگو را در همه‌جا یکدست و آینده‌محور می‌کند. اگر ترجیح می‌دهی بدون کامپوننت جدید پیش بروی، می‌توانی در هر فایل مستقیم `createPortal(..., document.body)` بزنی (مثل `ImageCropModal.tsx`). یکی از این دو روش را انتخاب و در همه‌ی موارد یکسان اعمال کن.

### ۲. انتقال `ConfirmDialog.tsx` به portal

```tsx
import Portal from './Portal';
// ...
  if (!open) return null;
  return (
    <Portal>
      <div className="overlay" onClick={onCancel}>
        {/* بدون تغییر */}
      </div>
    </Portal>
  );
```

### ۳. همین کار برای بقیه‌ی مودال‌های `.overlay` بدون portal

هر جای زیر که `.overlay` مستقیم رندر می‌شود را داخل `<Portal>...</Portal>` بپیچ (مسیر import را نسبت به محل فایل تنظیم کن: از `pages/` → `../components/ui/Portal`؛ از `components/layout/` → `../ui/Portal`؛ از `components/ui/` → `./Portal`):

- `components/ui/InviteDoctorModal.tsx` (خط ~42)
- `components/layout/Topbar.tsx` (خط ~75) — اگر این overlay فقط بک‌دراپ سایدبار موبایل است و مشکل جانمایی ندارد، فقط در صورت نیاز؛ ولی برای یکدستی بهتر است portal شود.
- `pages/UsersPage.tsx` (خط ~104)
- `pages/ClinicsPage.tsx` (خط ~247)
- `pages/PreRegistrationsPage.tsx` (خط ~207)
- `pages/ClinicDetailPage.tsx` (خط ~354) — این تنها overlay بدون portal این فایل است؛ بقیه (خطوط ~150، ~1177، ~1305، ~1315) از قبل `createPortal` دارند، آن‌ها را دست نزن.

### ۴. بررسی نبود مورد جاافتاده

بعد از اعمال، این جستجو را بزن و مطمئن شو هر `className="overlay"` یا `className='overlay'` یا داخل `createPortal` است یا داخل `<Portal>`:

```bash
grep -rn "className=[\"']overlay" assets/admin --include="*.tsx"
```

هر موردی که هیچ‌کدام نبود را هم portal کن.

## نکات مهم

- کلاس `.overlay` و `.modal` در `styles.css` درست‌اند (`place-items: center`)؛ **CSS را تغییر نده** — مشکل صرفاً از context جانمایی `fixed` به‌خاطر ancestor transform‌دار است، نه از خود overlay.
- محتوای داخل `.overlay` (شامل `onClick={onCancel}` بک‌دراپ و `stopPropagation` روی `.modal`) نباید تغییر کند؛ فقط دور کل بلوک `.overlay` یک `<Portal>` اضافه می‌شود.
- `ui/Modal.tsx` و `ImageCropModal.tsx` را تغییر نده (از قبل درست‌اند).
- تغییر فقط frontend است؛ هیچ endpoint/API عوض نمی‌شود → نیازی به به‌روزرسانی `docs/api/*` یا تست backend نیست.
- بعد از تغییر: `ddev exec npx tsc --noEmit --project tsconfig.json` (صفر خطا) و `ddev exec yarn dev` (باید `webpack compiled successfully` بدهد؛ خطای `lightningcss.linux-arm64-gnu` پیش‌زمینه‌ای و بی‌ربط است).
- تست دستی: در چند صفحه (کاربران، کلینیک‌ها، پیش‌ثبت‌نام، جزئیات دکتر/کلینیک) مودال/ConfirmDialog را باز کن و مطمئن شو وسط صفحه می‌افتد نه پایین.
