# معاينة المستند

> يعرض كشوف الحساب والفواتير والعقود داخل المنتج، مع شريط علوي للصفحات والتكبير والتنزيل والطباعة، وشريط جانبي للصفحات المصغّرة.

الصفحة: https://ritla.app/ar/ui/document-preview

## التثبيت

يُفتح التثبيت من السجل قريبًا، وهذه هي الأوامر التي ستشغّلها حينها.

```bash
npx ritla add document-preview
```

أو بأداة shadcn:

```bash
npx shadcn@latest add @ritla/document-preview
```

الاعتماديات: `@phosphor-icons/react`

## الاستخدام

```tsx
import { DocumentPreview } from "@/components/ui/document-preview";

// Pages come from the app's own renderer: images made on the server, or a library such as
// pdf.js drawing each page to a canvas. The viewer only shows them.
<DocumentPreview
  fileName="Statement_Sep_2026.pdf"
  pages={pageImages.map((src, i) => ({ content: <img src={src} alt={`Page ${i + 1}`} /> }))}
  downloadHref="/statements/2026-09.pdf"
  downloadLabel="Download PDF, 240 KB"
/>
```

## أمثلة

### المستند يحتفظ باتجاهه

كشف إنجليزي في العارض بلا شريط جانبي. في المعاينة العربية ينعكس الشريط العلوي، وتبقى الصفحات بالإنجليزية من اليسار إلى اليمين لأن لكل صفحة `dir` و`lang`.

معاينة حيّة: https://ritla.app/_kanz/preview/arabic/document-preview-own-direction

## مرجع الخصائص

### `DocumentPreview`

| الخاصية | النوع | الافتراضي | الوصف |
| --- | --- | --- | --- |
| `fileName` | `string` | لا يوجد | اسم الملف، يُقرأ من اليسار إلى اليمين. لا تضع فيه بيانات شخصية. |
| `pages` | `{ content, dir?, lang?, thumbnail? }[]` | لا يوجد | الصفحات كما يعرضها التطبيق، بلغتها واتجاهها. المكوّن لا يقرأ ملفات PDF: يرسم التطبيق كل صفحة بأداته، كصور يولّدها الخادم أو بمكتبة مثل pdf.js، ويمرّرها هنا (`<img>` أو `<canvas>` أو محتوى). |
| `pageWidth / pageHeight` | `number` | `560 / 792` | مقاس الصفحة بالبكسل عند 100%. |
| `sidebar` | `boolean` | لا يوجد | خاصية Sidebar: شريط الصفحات المصغّرة، مفتوح افتراضيًا لثلاث صفحات فأكثر، ومخفي على الهاتف. |
| `downloadHref / downloadLabel` | `string` | لا يوجد | رابط التنزيل، واسمه بنوع الملف وحجمه («تنزيل PDF، 240 كيلوبايت»). |
| `onPrint` | `() => void` | لا يوجد | زر الطباعة؛ لا يظهر دونه. |
| `menu` | `ReactNode` | لا يوجد | زر «المزيد» يفتح قائمة ببقية الإجراءات. |

## إمكانية الوصول

لوحة المفاتيح (المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين، ويتبادل السهمان في الاتجاه من اليمين إلى اليسار):

- `Tab`: إلى أزرار الشريط العلوي، ثم الصفحات المصغّرة، ثم مساحة الصفحات.
- `Enter`: على صفحة مصغّرة: ينتقل إلى تلك الصفحة.
- `ArrowDown` + `ArrowUp`: في مساحة الصفحات: تمرير عمودي.

ARIA:

- كل زر في الشريط له اسم: تنزيل، طباعة، تكبير، تصغير، ملاءمة العرض، تدوير.
- رقم الصفحة يتبع التمرير ويُعلن «الصفحة 1 من 3».
- الصفحات المصغّرة أزرار في `nav` باسم «الصفحات»، والحالية `aria-current`.
- نص المستند يبقى قابلًا للتحديد عندما تعرضه محتوًى لا صورة.

## ملاحظات العربية والاتجاه

ينعكس:

- القائمة واسم الملف على اليمين، والتنزيل والطباعة على اليسار.
- شريط الصفحات المصغّرة ينتقل إلى اليمين.
- عدد الصفحات يُكتب «1 من 2».

لا ينعكس:

- الصفحات نفسها: تحتفظ بلغتها واتجاهها.
- اسم الملف يبقى من اليسار إلى اليمين.
- التدوير باتجاه عقارب الساعة، وأيقونته لا تنعكس.

الأرقام: رقم الصفحة ونسبة التكبير يتبعان أرقام المنتج؛ أرقام المستند كما في صفحاته.

الخط العربي: اسم الملف `label-16` بوزن Semibold، والعدّاد `label-14` و`label-12` بوزن Medium، بالأبيض على الشريط الداكن.

النص ثنائي الاتجاه: اسم الملف ونسبة التكبير معزولان باتجاه LTR.