# Use and adapt etjah-v2

Use the documented interfaces and source layout for **etjah-v2**. The sections below retain the README’s examples and configuration details.

## كيف يعمل تطبيق الويب التقدمي (PWA)

تطبيق الويب التقدمي (PWA) هو تطبيق ويب يستخدم تقنيات الويب الحديثة لتقديم تجربة تشبه التطبيقات الأصلية للمستخدمين. يتميز هذا التطبيق بما يلي:

1.  **قابلية التثبيت:** يمكن للمستخدمين تثبيت التطبيق مباشرة من المتصفح إلى الشاشة الرئيسية لأجهزتهم (Android و iOS) دون الحاجة إلى متاجر التطبيقات.
2.  **العمل دون اتصال بالإنترنت:** بفضل عامل الخدمة (Service Worker)، يمكن للتطبيق العمل حتى في حالة عدم وجود اتصال بالإنترنت، مما يوفر تجربة مستخدم مستمرة.
3.  **السرعة والأداء:** يتم تحميل المحتوى المخزن مؤقتًا بسرعة، مما يقلل من أوقات التحميل ويحسن الأداء العام.
4.  **تجربة المستخدم المحسّنة:** يفتح التطبيق في وضع ملء الشاشة بدون واجهة مستخدم المتصفح، مما يوفر تجربة غامرة.

### المكونات الرئيسية لـ PWA

*   **`public/manifest.json`**: ملف JSON يصف التطبيق للمتصفح، بما في ذلك اسمه، أيقوناته، لون السمة، وكيف يجب أن يظهر عند التثبيت.
*   **`public/sw.js` (Service Worker)**: نص برمجي يعمل في الخلفية، منفصل عن صفحة الويب. يقوم بمعالجة طلبات الشبكة، وتخزين الأصول مؤقتًا (caching)، وتوفير وظائف دون اتصال بالإنترنت، وإدارة التحديثات.
*   **علامات `<meta>` في `app/layout.tsx`**: علامات HTML إضافية في قسم `<head>` لدعم ميزات PWA الخاصة بـ iOS، مثل `apple-mobile-web-app-capable` و `apple-touch-icon`.
*   **`components/pwa-install-prompt.tsx`**: مكون React يعرض مطالبة للمستخدم لتثبيت التطبيق عندما يكون متاحًا.
*   **`components/service-worker-register.tsx`**: مكون React يقوم بتسجيل عامل الخدمة عند تحميل التطبيق.
*   **`app/loading.tsx`**: مكون تحميل يظهر أثناء جلب البيانات على الخادم، مما يحسن تجربة المستخدم من خلال توفير ملاحظات مرئية.

## كيفية تحديث عامل الخدمة (Service Worker)

عند إجراء تغييرات على ملف `public/sw.js` أو الأصول المخزنة مؤقتًا، يجب تحديث عامل الخدمة لضمان حصول المستخدمين على أحدث إصدار.

1.  **تغيير `CACHE_NAME`**: في `public/sw.js`، قم بتغيير قيمة المتغير `CACHE_NAME` (على سبيل المثال، من `etijah-real-estate-v1` إلى `etijah-real-estate-v2`). هذا سيجعل عامل الخدمة الجديد يرى أن هناك إصدارًا جديدًا من ذاكرة التخزين المؤقت.
2.  **تحديث `urlsToCache`**: إذا أضفت صفحات جديدة أو أصولًا ثابتة مهمة، تأكد من إضافتها إلى مصفوفة `urlsToCache` في `public/sw.js`.
3.  **إعادة النشر**: بعد إجراء التغييرات، قم بإعادة نشر تطبيقك. سيكتشف المتصفح عامل الخدمة الجديد، ويقوم بتثبيته في الخلفية، ثم ينشطه عند إغلاق المستخدم لجميع علامات تبويب التطبيق القديمة.

## كيفية تخصيص ملف `manifest.json`

يمكنك تخصيص سلوك ومظهر PWA الخاص بك عن طريق تعديل `public/manifest.json`:

*   **`name` و `short_name`**: اسم التطبيق الكامل والمختصر الذي يظهر للمستخدم.
*   **`lang` و `dir`**: لغة التطبيق واتجاه النص (مهم جدًا لـ RTL).
*   **`start_url`**: المسار الذي يجب أن يفتحه التطبيق عند التشغيل.
*   **`display`**: يحدد وضع عرض التطبيق (على سبيل المثال، `standalone` لفتح التطبيق في نافذة خاصة به).
*   **`theme_color` و `background_color`**: ألوان الواجهة التي يستخدمها المتصفح (مثل شريط الحالة).
*   **`description`**: وصف موجز للتطبيق.
*   **`icons`**: قائمة بأيقونات التطبيق بأحجام مختلفة. تأكد من وجود أيقونات 192x192 و 512x512 على الأقل.
*   **`screenshots`**: (اختياري) لقطات شاشة لتطبيقك تظهر في واجهة تثبيت المتصفح.

## Commands in the root manifest

The captured [package.json](https://github.com/Up-to-code/etjah-v2/blob/HEAD/package.json) declares the following scripts. Run them from the directory containing that manifest.

| Command | Script |
| --- | --- |
| `npm run build` | `next build` |
| `npm run dev` | `next dev` |
| `npm run lint` | `next lint` |
| `npm run start` | `next start` |

## Troubleshoot a local change

1. Reproduce the smallest example from the [quick-start guide](/docs/up-to-code-etjah-v2/quick-start-guide).
2. Compare required configuration and dependency versions with the README.
3. Check the linked issue tracker for the same error. Include the command, runtime version, and relevant error when reporting a problem; omit credentials.

## Source and help

- [GitHub repository](https://github.com/Up-to-code/etjah-v2)
- [Original README](https://github.com/Up-to-code/etjah-v2/blob/main/README.md)
- [Issues and existing reports](https://github.com/Up-to-code/etjah-v2/issues)
- [Open the project website](https://v0-arabic-luxury-website.vercel.app)