# 🦷 React Advanced Odontogram
[](https://github.com/ZoliQua/React-Odontogram-Modul/releases)
[](https://github.com/ZoliQua/React-Odontogram-Modul)
[](https://www.npmjs.com/package/react-advanced-odontogram)
[](https://github.com/ZoliQua/React-Odontogram-Modul/blob/main/LICENSE)
[](https://doi.org/10.5281/zenodo.21156787)
[](https://reactjs.org/)
[](https://www.typescriptlang.org/)
---
> 🌐 **Languages:** 🇬🇧 [English](README-en.md) | 🇪🇸 [Español](README-es.md) | 🇩🇪 [Deutsch](README-de.md) | 🇭🇺 [Magyar](README-hu.md) | 🇮🇹 [Italiano](README-it.md) | 🇸🇰 [Slovenčina](README-sk.md) | 🇵🇱 [Polski](README-pl.md) | 🇷🇺 [Русский](README-ru.md) | 🇧🇷 [Português (BR)](README-pt-br.md) | 🇸🇦 [العربية](README-ar.md) | 🇨🇳 [简体中文](README-zh.md) | 🇫🇷 [Français](README-fr.md)
---
## 🇸🇦 العربية
*(النسخة العربية من هذا الملف التعريفي (README) — مترجمة عن النسخة الإنجليزية الأصلية، بحسب الإصدار v1.49.0)*
### 📋 نظرة عامة
هذا المشروع محرر تخطيط أسنان (أودونتوغرام) تفاعلي يعمل داخل المتصفح، ويدعم تسجيل حالة الأسنان بسرعة من خلال واجهة مستخدم نظيفة وواضحة. يعرض المشروع قوالب أسنان بصيغة SVG متعددة الطبقات لتمثيل الترميمات، والنخر (التسوس)، وحالة العلاج اللبي (علاج قناة الجذر)، ودرجة حركة السن، وتفاصيل سريرية أخرى، مع توفير إمكانية التحديد المتعدد، ومرشحات التحديد، وأنماط حالة جاهزة مسبقًا.
---
🔗 **رابط الاختبار:** https://react-odontogram-modul.vercel.app/
---
### 📦 الاستخدام كحزمة npm
يُشحَن الأودونتوغرام كمكتبة مكوّنات React مستقلة بذاتها على npm:
[`react-advanced-odontogram`](https://www.npmjs.com/package/react-advanced-odontogram).
#### المتطلبات
- **React 18 أو 19** (مُعلَنة كاعتمادية نظير (peer dependency) — يوفّرها تطبيقك).
- **حزمة تجميع (bundler)** تفهم حقل `exports` وصيغة ESM: Vite، webpack 5، Next.js، Rollup، esbuild، Parcel. الحزمة **ESM فقط**.
- Node **الإصدار 18 فأعلى** للأدوات.
#### التثبيت
```bash
npm install react-advanced-odontogram react react-dom
```
#### الاستخدام الأساسي
اعرض `OdontogramShell` واستورد ملف التنسيق **مرة واحدة فقط** في أي مكان من تطبيقك:
```tsx
import { OdontogramShell } from "react-advanced-odontogram";
import "react-advanced-odontogram/style.css";
export function Chart() {
return (
);
}
```
#### خصائص المكوّن (props)
`OdontogramShell` مكوّن مُتحكَّم به (controlled component). أكثر الخصائص شيوعًا:
| الخاصية | النوع | الافتراضي | الوصف |
|------|------|---------|-------------|
| `language` | `Language` | `"hu"` | لغة الواجهة (`hu`/`en`/`de`/`es`/`it`/`sk`/`pl`/`ru`/`pt-br`/`ar`/`zh`). |
| `numberingSystem` | `"FDI" \| "Universal" \| "Palmer"` | `"FDI"` | نظام ترقيم الأسنان. |
| `darkMode` | `boolean` | `false` | مفتاح تبديل السمة الداكنة. |
| `readOnly` | `boolean` | `false` | تعطيل كل إمكانيات التحرير (عرض فقط). |
| `themeConfig` | `OdontogramThemeConfig` | — | تجاوز متغيرات CSS الخاصة بالسمة (`--odon-*`). |
| `plugins` | `OdontogramPlugin[]` | — | تسجيل إضافات حالة مخصّصة / طبقات إضافية. |
| `enableNotes` | `boolean` | `false` | تفعيل الملاحظات لكل سن. |
| `enableIcdas` | `boolean` | `false` | تفعيل تقييم النخر وفق ICDAS II. |
| `onLanguageChange` / `onNumberingChange` / `onDarkModeChange` | `(value) => void` | — | تُستدعى عندما يغيّر المستخدم الإعداد من الواجهة. |
تُقبَل أيضًا خصائص أدقّ لمستوى التفصيل (`pulpDetailLevel`، `secondaryCariesMode`، `rootCariesMode`، `radiographicDepthMode`، `wearDetailLevel`، `discolorationDetailLevel`، `surfaceNotation`، `showStatusCard`، `showOrthoCard`) — راجع أنواع `.d.ts` المرفقة للاطلاع على القائمة الكاملة المُنمَّطة.
#### واجهة برمجية عامة (تصديرات مسمّاة)
`OdontogramShell` هو التصدير الافتراضي وتصدير مسمّى في آن واحد. واجهة الحالة الآمرة (imperative)، ومكوّن `PerioChart` المستقل، والجولة التعريفية الموجَّهة، وجميع الأنواع العامة هي تصديرات مسمّاة من نقطة الدخول ذاتها:
```ts
import {
OdontogramShell, // also the default export
PerioChart, // standalone periodontal chart component
// read state
getOdontogramSummary,
getToothStateSummary,
onStateChange, // subscribe to state changes
// export / import
exportFhir, // HL7 FHIR R4 bundle
exportSvg, exportImage, // vector / raster chart export
setImportFormat,
// control
setReadOnly, getReadOnly,
clearSelection,
registerPlugins, setPluginState, getPluginState,
startIntroTour, // launch the onboarding tour
// …and many more setX/getX settings functions
} from "react-advanced-odontogram";
```
كامل الواجهة (نحو 44 دالة + أنواع مثل `OdontogramSummary`، `OdontogramThemeConfig`، `OdontogramPlugin`، `FhirExportOptions`، `PerioViewMode`، …) مُنمَّطة بالكامل ضمن التصريحات المرفقة.
#### الاستخدام مع Next.js (موجِّه التطبيق App Router)
المكوّن يعمل من جهة العميل فقط، لذا اعرضه من مكوّن عميل (Client Component):
```tsx
"use client";
import { OdontogramShell } from "react-advanced-odontogram";
import "react-advanced-odontogram/style.css";
export default function OdontogramClient() {
return ;
}
```
أو حمّله عبر استيراد ديناميكي مخصَّص لجهة العميل فقط: `dynamic(() => import("./OdontogramClient"), { ssr: false })`.
#### ملاحظات مهمة وقيود حالية
- **ESM فقط** — تنشر الحزمة وحدة ES واحدة (`dist/odontogram.js`) بالإضافة إلى مدخل تصريحات الأنواع (`dist/index.d.ts`). وهي موجَّهة لاستبانة وحدات حزم التجميع (bundler)؛ لا يوجد بناء CommonJS.
- **ملف التنسيق منفصل** — **يجب** عليك استيراد `react-advanced-odontogram/style.css` مرة واحدة؛ فهو لا يُحقَن تلقائيًا. التنسيق عبارة عن CSS عام محصور ضمن `.odontogram-root` ومُتحكَّم به عبر متغيرات CSS من نوع `--odon-*`.
- **العرض من جهة الخادم / جهة العميل فقط** — يقرأ المكوّن DOM عند التركيب (`document`)، لذا يجب أن يعمل داخل المتصفح. في أطر عمل SSR، اعرضه ضمن مكوّن عميل (`"use client"`) أو عبر استيراد ديناميكي مخصَّص لجهة العميل فقط.
- **الأصول مكتفية ذاتيًا** — تُدرَج رسومات الأسنان والأيقونات بصيغة SVG ضمن حزمة JavaScript وقت البناء؛ **لا يوجد** أي طلب أصول وقت التشغيل يلزم إعداده، ولا شيء إضافي يلزم نسخه إلى مجلدك العام.
- **نسخة واحدة لكل صفحة** — حالة المحرك حاليًا هي كائن وحيد (singleton) على مستوى الوحدة (module)، لذا فإن عرض نسختين من `` في الصفحة نفسها سيجعلهما تتشاركان حالة مخطط واحد. دعم النسخ المتعددة مخطَّط له في إصدار مستقبلي.
---
### ✨ الميزات الرئيسية
- 🖱️ تحديد سريع وتحديد متعدد (CMD/CTRL + نقر)
- 🦷 أنواع الأسنان: دائم، لبني (مؤقت)، زرعة، تحت اللثة، مفقود
- 🦷 نسيج السن الأساسي (مستقل عن أي ترميم): طبيعي، جذر متبقٍّ (radix)، مكسور، مُجهَّز لتركيب تاج
- 👑 الترميمات حسب النوع × المادة: تاج / حشوة داخلية (إنلاي) / حشوة فوقية (أونلاي) / قشرة (فينير) / جسر من الإيماكس، الذهب، الغراديا، الزركونيا، المعدن، المعدن الخزفي، التيليسكوب أو مؤقت (الأونلاي بمنظر إطباقي فقط) — تُختار من قائمة منسدلة مُجمَّعة واحدة "Fix: Crown – …" بأقل عدد من النقرات؛ تاجات `metal` القديمة تُرحَّل تلقائيًا إلى `metal-ceramic` (معدن خزفي)؛ الزرعات تستخدم نفس نموذج النوع × المادة، مع طبقة موصل زرعة إضافية. القائمة المنسدلة مقيّدة بحسب نوع السن: الزرعة تعرض فقط تاج/جسر (بالإضافة إلى خيارات التثبيت الخمسة أدناه)؛ السن المفقود/الفراغ يعرض فقط جسرًا وسيطًا (بالإضافة إلى طقم جزئي/كامل متحرك)؛ نسيج `radix` يخفي عنصر التحكم بالترميم تمامًا (لا يمكن تسجيل أي ترميم على جذر متبقٍّ)
- 🦿 تركيبات متحركة/بمرابط على محور `prosthesis` المخصص (مدخلات "Kivehető:" في القائمة المنسدلة المجمّعة): دعامة التئام الزرعة، لوكاتور، لوكاتور مع طقم علوي، بار، بار مع طقم علوي؛ طقم جزئي أو كامل متحرك مدعوم بالأسنان
- 🌉 أسنان الجسر تعرض غطاء التاج وموصل السرج معًا؛ تراكب امتداد جسر متعدد الأسنان يرسم موصلًا واحدًا متصلًا ومتوافقًا مع شكل القوس عبر أسنان الجسر المتتالية (الوسائط + الدعامات) والفراغات بينها (يستخدم القوسان العلوي والسفلي هندسة سرج متطابقة انعكاسيًا، بحيث يبقى الموصل متماشيًا في كلا القوسين)، وهو مُضمَّن في تصدير PNG/JPG/SVG؛ تطبيق جسر عبر نمط حالة جاهز يعيد حساب التراكب فورًا
- 🔍 تسجيل النخر على 6 أسطح: قريب من الوسط، بعيد عن الوسط، دهليزي، لساني، إطباقي، تحت التاج
- 🪥 مواد الحشو لكل سطح: أملغم، حشوة تجميلية (كومبوزيت)، أيونومر زجاجي، مؤقتة
- 🏥 مُحدِّد واحد مدمج لـ"حالة اللب/العلاج اللبي" (مُجمَّع: لب حيوي مقابل معالَج/لبّي): الحالات اللبّية (حشوة دوائية، حشوة قناة جذر، حشوة قناة جذر غير مكتملة، وتد ألياف زجاجية، وتد معدني) وتشخيص اللب وفق AAE (`pulpDx`: طبيعي / التهاب لب قابل للعكس / غير قابل للعكس / نخر اللب) متنافيان — فالسن المعالَج بقناة الجذر (`endo` مضبوط) لا يمكن أن يحمل في الوقت نفسه تشخيص لب حيوي؛ وعند المعالجة يُعاد ضبط `pulpDx` إلى `normal` ويُخفى رمز اللب المريض. التهاب اللب القابل للعكس يُعرض برمز لب مصغَّر. إعداد اختياري لثلاثة مستويات من تفاصيل اللب (`pulpDetailLevel`: بسيط / AAE / لاتيني عملي) يُظهر عبر `pulpLatin` تسعة أنماط لبّية فرعية باللاتينية العملية (pulpa sana … gangraena pulpae)؛ ويبقى الاستئصال والوتد المجاوز للُّب مؤشرين خاصين منفصلين
- 🦴 التشخيص القمي (`apicalDx`: التهاب دواعم السن القمي العرَضي/اللاعرَضي، خراج قمي حاد/مزمن، التهاب العظم المتكاثف) يتحكم مباشرة برمز الآفة حول الذروة؛ ويظهر محدِّد فرعي للنوع (ورم حبيبي/كيس) فقط تحت التهاب دواعم السن القمي العرَضي/اللاعرَضي (وقد أُلغي نوع "الخراج" الفرعي الزائد عن الحاجة — لأنه مشمول أصلًا ضمن التشخيص القمي)
- 🩹 بطاقة مدمجة لـ"الجذر ودواعم السن" (قسم قابل للطي واحد لنتائج الجذر/حول الذروة ونتائج دواعم السن)
- ⚕️ التعديلات: التهاب حول الذروة (يظهر فقط في الأسنان المفقودة/سنخ الخلع؛ ويُخفى في الأسنان الموجودة حيث يتحكم `apicalDx` وحده برمز الآفة، وفي الزرعات حيث يغطيها `periImplant`)، مرض دواعم السن، درجات حركة السن (M1/M2/M3، مخفية في الزرعات)
- 🦷🔩 حالة ما حول الزرعة (`periImplant`: none / mucositis / peri-implantitis-mild / -moderate / -severe) — وفق تصنيف الورشة العالمية 2018، تُعرض كمحدِّد مخصص في الزرعات؛ التهاب المخاطية حول الزرعة يعيد استخدام رمز اللثة الدواعمي، بينما التهاب ما حول الزرعة يضيف طبقة `peri-implant-bone-loss` متدرجة (عتامة 0.4/0.7/1.0). لم تعد الزرعات تعرض رمز آفة حول الذروة — إذ يُعبَّر عن التهابها عبر هذا المحور بدلًا من ذلك — وتُخفى خانات تعديل دواعم السن في الزرعات (وأُلغيت إعادة تسمية خانة "التهاب ما حول الزرعة" المؤقتة)
- 🏷️ مؤشرات خاصة: الحاجة إلى تاج، الحاجة إلى استبدال تاج، فراغ مغلق بعد الفقد، خطة خلع، إغلاق الشقوق، فقدان نقطة التماس
- 👁️ مفاتيح تبديل للمنظر الإطباقي، وأسنان العقل، وإظهار العظم واللب
- 🔢 12 مرشح تحديد (الكل، الموجود، الدائم، اللبني، الزرعات، المفقود، العلوي/السفلي، الأمامي/الأضراس)
- 📊 أنماط حالة جاهزة مسبقًا (إعادة الضبط، التسنين اللبني، التسنين المختلط، انعدام الأسنان)
- 📦 34 قالب ترميم جاهزًا مسبقًا (جسور، أطقم متحركة، أطقم بار مع زرعات)
- 💾 تصدير/استيراد الحالة بصيغة JSON (الإصدار 2.20؛ لا تزال الاستيرادات تقبل الإصدارات القديمة 1.4 ومن 2.0 حتى 2.19 وتُرحَّل تلقائيًا، مع حالات مخصصة للإضافات وملاحظات لكل سن)
- 🔗 تصدير HL7 FHIR R4 (حزمة تجميعية (Bundle) من ملاحظات (Observations) لكل سن، مع ترميز أسنان وفق ISO 3950 للتسنين الدائم، ونظام ترميز محلي — مع التخطيط لدعم ترميز SNOMED CT مستقبلًا)
- ✚ واجهة تحديد أسطح على شكل صليب/علامة زائد (B/M/O/D/L) للنخر والحشوات
- 🧱 مواد ترميم لكل سطح على حدة (حشوات مختلطة، مثل أملغم دهليزي + كومبوزيت بعيد عن الوسط)
- 🖼️ تصدير صورة PNG/JPG/SVG للمخطط (قابل للتنزيل؛ يُنشأ PNG/JPG بالتحويل النقطي من SVG متجهي)
- 🦷 النخر/النخر الثانوي آلة حالة لكل سطح: السطح المصاب بالنخر بلا حشوة يُعرض كنخر أولي (بعتامة متدرجة حسب مقياس ICDAS)؛ وبمجرد وجود حشوة على ذلك السطح يُعرض بدلًا من ذلك كنخر متكرر (طبقة `subcaries-{surface}`، بتقييم CARS) — ولا تكون الحالتان نشطتين معًا على السطح نفسه أبدًا
- 🎯 شدة موحّدة لكل سطح (`cariesSeverity`، من 0 إلى 6، تحل محل حقلي عمق ICDAS ودرجة CARS المنفصلين سابقًا): تُقرأ كعمق ICDAS على سطح أولي، وكدرجة CARS مُسمّاة (سليم … تجويف واسع) على سطح متكرر، عبر نافذة منبثقة سياقية تعرض فقط المقياس المناسب لحالة السطح الراهنة
- 🌱 نخر الجذر (`rootCaries`: none / active / arrested / active-cavitated)، يفعّل طبقة الرسم المخصصة لنخر الجذر بعتامة تعتمد على الشدة (نشِط 0.5 / متوقف 0.7 / نشِط وتجويفي بعتامة كاملة)
- 📡 عمق النخر الشعاعي (`radiographicDepth`: none / E1 / E2 / D1 / D2 / D3 لكل سطح)، مستقل عن مقياس الشدة البصري ICDAS/CARS، يظهر كشارة ويُصدَّر عبر ملاحظة FHIR خاصة به
- 🎚️ ثلاثة إعدادات لدرجة تفصيل النخر (`secondaryCariesMode`, `rootCariesMode`, `radiographicDepthMode`) بالإضافة إلى مفتاح `cariesDepthEnabled`، تختصر كل مقياس إلى واجهة اختيار أبسط دون فقدان القيمة المخزّنة
- 🩹 سطر ملخص للنخر الثانوي في لوحة الحشوات: يسرد أي سن محدد فيه نخر متكرر وأسطحه أسفل عناصر تحكم الحشو (مثل: "36 (O) has subcaries set on its filling.")
- 🪛 عيوب حشو لكل سطح (`fillingDefect`: none / marginal / fracture / wear) في الترميمات المباشرة، بمعزل عن النخر المتكرر — تُسجَّل عبر مؤشر لكل سطح في بطاقة الحشوات (يعكس مؤشر عمق النخر، مع قائمة خياراته مكدسة عموديًا)، وتُعرض على المخطط، وتظهر في التلميح وفي ملخص حشوات الفم الكامل بتسمية صريحة (مثل: "36 (O) – Filling defect: O: marginal")، بنفس الطريقة التي يُسمّى بها النخر المتكرر في سطر النخر؛ كما تعرض بطاقة الحشوات ملاحظة تنبيهية لأي سن محدد لديه عيب حشو مسجَّل (مثل: "36 has a filling defect recorded.")، بالتوازي مع ملاحظة النخر الثانوي القائمة
- 🦷💥 بري (تآكل) السن مصنّف حسب السبب السريري والموضع (`wearEdge`: none / attrition / erosion، قاطعي/إطباقي؛ `wearCervical`: none / abrasion / abfraction / erosion، عنقي) — يحل محل علمي التحكم السابقين (تشغيل/إيقاف) لبري الصرير؛ يُسجَّل عبر قائمتين منسدلتين في سطر البري، ويعيد استخدام رسوم البري الحالية، ويظهر في التلميح وفي قسم ملخص جديد للفم الكامل بعنوان "Wear"
- 🎨 تصبّغ السن حسب السبب (`discoloration`: none / tetracycline / fluorosis / nonvital / extrinsic / other) في الأسنان الدائمة واللبنية — يلوّن تاج السن الطبيعي المعروض بلون تمثيلي عندما لا يحمل السن ترميمًا وله نسيج طبيعي؛ يظهر في التلميح وفي قسم ملخص جديد للفم الكامل بعنوان "Discoloration"؛ ويكمل مجموعة الحالات السطحية والبنيوية إلى جانب عيوب الحشو والبري
- ✏️ الأسنان الأمامية (القواطع والأنياب) تُسمّي سطحها الإطباقي "قاطعي" (incisal) في كل أنحاء الواجهة (القائمة، النافذة المنبثقة، الملخصات)؛ ويبقى مفتاح السطح المخزَّن `occlusal`
- 🔤 ترميز أسطح مراعٍ للموضع (الإعدادات ← تفاصيل السن ← "ترميز السطح"، بسيط/كامل، الافتراضي كامل): في الوضع الكامل يتبع حرف/تسمية سطح النخر والحشو تشريح السن — الإطباقي ← I/قاطعي في الأسنان الأمامية، الدهليزي ← L/شفوي في الأسنان الأمامية، اللساني ← P/حنكي في الأسنان العلوية و L/لساني في الأسنان السفلية (لا يتأثر القريب من الوسط/البعيد عن الوسط/تحت التاج)؛ الوضع البسيط يستخدم دائمًا المجموعة العامة B/M/O/D/L/SC بصرف النظر عن موضع السن. ينطبق على ملخص الفم الكامل وعلى محددَي أسطح كل من النخر وعيب الحشو (الحرف + التسمية)؛ ولا يتأثر مفتاح السطح المخزَّن
- 🦷↕️ تسجيل تقويم الأسنان لكل سن (`orthoAppliance`: none / bracket / band؛ `orthoDrift`: none / mesial / distal؛ `orthoVertical`: none / extrusion / intrusion؛ `orthoRotation`: قيمة منطقية) على سن طبيعي موجود (دائم أو لبني) — يعيد استخدام رسوم التقويم الخاملة منذ الإصدار v2.5.0 (دون إضافة SVG جديد)؛ يظهر على المخطط، وفي التلميح، وفي قسم ملخص جديد للفم الكامل بعنوان "Orthodontics"
- 🪨 الجير، وامتصاص الجذر المصنَّف كداخلي أو عنقي خارجي (`resorptionType`)
- 📏 عمق النخر لكل سطح (سطحي / عاجي / عميق)، أو تقييم اختياري وفق ICDAS II (من 0 إلى 6) عبر `enableIcdas`
- 🩹 مفتاح تبديل لتسرب حافة التاج، يظهر فقط عند وجود ترميم تاج أو جسر
- 🧰 شريط أيقونات علوي موحَّد مع نافذة إعدادات بعلامات تبويب (عام / اللوحات / تفاصيل السن / النخر / اللب / الملاحظات / دواعم السن — الترقيم، الملاحظات، إظهار اللوحات، ICDAS، مفتاح عمق النخر، درجة تفصيل نخر الجذر/النخر الشعاعي، مستوى تفصيل اللب، مستوى تفصيل بري/تصبّغ السن، معلومات السن)
- 🗂️ الإعدادات ← علامة التبويب "اللوحات": إظهار/إخفاء مستقل للوحتَي ملخص الحالات وتقويم الأسنان لكامل الفم
- 🦷🩺 الإعدادات ← علامة التبويب "دواعم السن": 16 مفتاح إظهار/إخفاء لكل مؤشر من صفوف مخطط دواعم السن (مجمّعة: الجيب/النظافة/المخاطية اللثوية/الدعم/ما حول الزرعة — PD/GM/CAL/BOP، البلاك، PI، GI، إظهار CEJ، تقعر الجذر، KG، GT، تفرع الجذور، الحركة، تصنيف ميلر، mPI، mBI)، لكل منها وصف، بالإضافة إلى خيار عرض أسماء المؤشرات مترجمة مقابل قياسية (القياسي = اسم علمي إنجليزي/لاتيني ثابت في كل لغات الواجهة؛ وتبقى التلميحات مترجمة دائمًا بصرف النظر عن هذا الإعداد). كلاهما إعدادان على مستوى التطبيق (مثل `perioViewMode`) — وليسا أبدًا جزءًا من حمولة التصدير
- 🩹 دُمِجت إعدادات النخر الثانوي (CARS) في علامة تبويب إعدادات النخر، وتموضعت أعلى العمق الشعاعي (أُلغيت علامة التبويب المنفصلة "النخر الثانوي")
- 🎚️ مستوى تفصيل تفاصيل السن (الإعدادات ← تفاصيل السن): إعداد بسيط/معقّد لبري السن وللتصبغ. الوضع البسيط يعرض مفتاح نعم/لا لكل نتيجة (تفعيل البري ← attrition/abrasion، تفعيل التصبغ ← other)؛ الوضع المعقد (الافتراضي) يبقي القوائم المنسدلة للنوع/السبب، وتُحفظ القيمة المخزَّنة عند التبديل بين المستويين
- 📋 لوحة معلومات السن: ملخص نصي حي لكامل المخطط (عدد الأسنان، قوائم الموجود/المفقود، النخر بما فيه الثانوي، الحشوات، علاجات قناة الجذر، التركيبات، الزرعات، حالة دواعم السن) — تظهر افتراضيًا، وقابلة للتبديل من الإعدادات
- 🗂️ قائمة تصدير موحّدة منسدلة (JSON للحالة / FHIR / PNG / JPG)
- 📥 قائمة استيراد منسدلة مع استيراد FHIR (تُعيد قراءة الحزم المُصدَّرة سابقًا)
- ⏳ طبقة تغطية للتقدم أثناء تصدير الصورة
- 🎓 جولة تعريفية تفاعلية من 12 خطوة
- 🔢 ثلاثة أنظمة ترقيم (FDI، العالمي، بالمر)
- 🌐 دعم متعدد اللغات (HU/EN/DE/ES/IT/SK/PL/RU/PT-BR) مع مبدّل لغة (أكثر من 190 مفتاح ترجمة لكل لغة)
- 🌗 دعم الوضع الداكن بزر تبديل (مستقل أو متحكَّم به من التطبيق الأصل)
- 🎨 إعدادات سمة مخصصة (خاصية `themeConfig`) عبر خصائص CSS المخصصة (`--odon-*`)
- 📱 تجربة لمس محسّنة للجوال: نافذة تكبير عند اللمس، قائمة سياق بالضغط المطوّل، تكبير بالقرص (Pinch-to-zoom)، أهداف لمس بحجم WCAG 44px، تنقل بتبديل القوس
- 🔌 نظام إضافات SVG مخصص: حقن تراكبات بصرية، حالة مخصصة لكل سن، دعم تصدير/استيراد JSON
- ⚠️ تحذيرات تحقق من الحالة لتركيبات حالة الأسنان غير المتوافقة
- 🏷️ تلميح تلقائي لحالة السن على بلاطات الأسنان (يعرض كل الحالات النشطة)
- 🩺 تلميح حديث لكل سن ولوحة ملخص لكامل الفم: يعرض كلاهما المجموعة الكاملة من النتائج السريرية (تشخيص اللب/القمة + النوع الفرعي للآفة، امتصاص الجذر، حالة ما حول الزرعة، نخر الجذر المتدرج، الجير، تسرب حافة التاج، الكسر، فقدان التماس، البري المصنَّف حسب الحافة/العنق)، مع قسم مخصص بعنوان "Diagnoses" في اللوحة، وقسم مخصص بعنوان "Wear"، ومؤشر خشِن لشدة النخر (سطحي/متوسط/عميق)
- ♿ إمكانية الوصول عبر لوحة المفاتيح (WCAG): أدوار ARIA لصندوق القوائم/الخيارات، تحديد بـEnter/مسافة، تنقل بأسهم لوحة المفاتيح، إطارات تركيز مرئية (focus-visible)
- 🔒 وضع للقراءة فقط: تعطيل جميع التفاعلات لحالات الاستخدام مثل الطباعة/التقرير/العرض
- ✨ رسوم متحركة للتحديد: إطار متقطع نابض وظل توهج على الأسنان المحددة (مع دعم `prefers-reduced-motion`)
- 📝 ملاحظات لكل سن: نقر مزدوج لإضافة/تعديل الملاحظات، أيقونة ملاحظة بجانب رقم السن، تلميح عند المرور بالمؤشر يعرض نص الملاحظة، سطر "ملاحظات فردية" في لوحة ملخص كامل الفم، وتضمينها في تقرير PDF، تصدير/استيراد JSON
- 🔀 فصل مخطط الحالة ↔ الخطة: مفتاح تبديل `Status | Plan` في رأس المخطط يبدّل بين مخطط **الحالة** الراهنة ومخطط **الخطة** (المعالجة المقصودة بعد العلاج)، ولكل منهما حالات أسنانه الخاصة؛ يبدأ مخطط الخطة كنسخة من الحالة عند أول تبديل إليه، ولا تؤثر التعديلات في أحد المخططين على الآخر أبدًا. يستهدف التصدير/الاستيراد (`exportStatus`/`exportFhir`/استيراد الملف) دائمًا مخطط الحالة؛ ويُقرأ/يُكتب مخطط الخطة بشكل منفصل عبر واجهته البرمجية الخاصة (انظر واجهة برمجة التطبيقات العامة أدناه) — وعند اختلافه عن الحالة، يُدرج كقسم إضافي `plan` في تصدير JSON
- 📝 مربع "ما الذي تغيّر": كلما اختلفت الخطة عن الحالة الراهنة، يسرد مربع أسفل لوحة معلومات السن كل فرق لكل سن ولكل محور معالجة (الوجود، النسيج الأساسي، الترميم، التركيبة، التاج المخطط له، التقويم، اللب/العلاج اللبي، القمة) كسطر بصيغة `tooth: axis from → to`؛ ومتاح أيضًا برمجيًا عبر `getPlanChanges()`
- 🩺 تسجيل دواعم السن: **عمق الجيب**، و**الحافة اللثوية**، و**النزف عند السبر** (+ التقيّح) لكل موضع، في المواضع الستة القياسية لكل سن، مع **مستوى الالتصاق السريري المشتق (CAL = عمق الجيب + الحافة اللثوية)**، والانحسار، ونسبة **%BOP** لكامل الفم. **مخطط دواعم سن رسومي لكامل الفم** — يُرسم كل قوس كـ**رسمي SVG منفصلين، دهليزي وحنكي/لساني** (بإعادة استخدام رسوم الأسنان بتوجيه موحّد من التاج نحو الشريط في كلا الجانبين؛ مع **رسم زرعة** خاص لأسنان الزرعات) مع **خط CEJ** أحمر، و**شبكة توجيه مرقّمة بالمليمتر**، و**منحنى للحافة اللثوية/عمق الجيب** فوق الأسنان، مقسَّمة بواسطة **شريط مركزي لمؤشرات دواعم السن** (بعنوان `▲ Buccal … Lingual/Palatal ▼`) يحمل المؤشرات المشتركة لكل سن — **تصنيف ميلر** في الأعلى تمامًا، و**البلاك/PI/GI/mPI/mBI** تُعرض كـ**بلاطة معينية تشريحية** لكل سن (الرأس الدهليزي للأعلى، الرأس اللساني للأسفل، مع تبديل القريب من الوسط/البعيد عنه في الصف الأوسط حسب الجانب بحيث يشير القريب من الوسط دائمًا نحو منتصف القوس)؛ وصفوف الأرقام (بأسماء المؤشرات الكاملة — PD/GM/CAL/BOP + الحركة + تفرع الجذور — في خلايا أكبر وأكثر ملاءمة للمس) مصفوفة في أعمدة، مع ملخص (متوسط PD/CAL، %BOP، %PI)، وإدخال بـ**تقدم تلقائي عبر لوحة المفاتيح**؛ ويتمدد المخطط **ديناميكيًا ليملأ العرض المتاح**، ويستجيب لأي حجم نافذة. يُعرض كمفتاح تبديل عرض `Odontogram | Periodontal Status`، حيث تُعاد صياغة اللوحة اليمنى إلى **شريط جانبي سياقي لدواعم السن** (بيانات المريض، وتصنيف 2017، وملخص كامل الفم) طوال نشاط ذلك العرض (مع خيار في الإعدادات لإعادة كل العرض إلى **نافذة منبثقة**)، ويبقى أيضًا **مكونًا قابلًا للاستدعاء بشكل منفصل** (تصدير `PerioChart`) بحيث يمكن للتطبيق المضيف استدعاء مخطط دواعم السن بمعزل عن الأودونتوغرام الأساسي. تصدير **FHIR** لكل موضع عبر لوحة دواعم السن في LOINC (`74029-0`؛ PD `32910-2`، الانحسار `32911-0`، CAL `32912-8`)
- 🅿️ تنسيق مقترَح: في وضع الخطة، تُعرض النتائج التي **تضيفها** الخطة مقارنة بالحالة الراهنة (تاج مخطط له، خلع، حركة تقويمية، تركيبة، ...) بحدود خارجية متقطعة وملوَّنة مميزة تدل على أنها "مقترحة"، بحيث تُقرأ الخطة كنيّة لا كواقع — مع مفتاح توضيحي "متقطع = مقترَح" في بطاقة المخطط. يبقى العرض في وضع الحالة مطابقًا تمامًا بايتًا بايت؛ والمعالجة موجودة فقط في الخطة وتُعاد ضبطها بالكامل عند العودة إلى الحالة
- 🚦 تقييد وضع الخطة: يعرض مخطط الخطة فقط ما يمكن لطبيب الأسنان أن *يفعله* — يعرض المحدِّد الأساسي فقط مفقود / دائم / زرعة، وتُخفى النتائج الخاصة بالحالة فقط (النخر، بري السن، التصبّغ، وكامل قسم دواعم السن — الحركة، شبكة السبر بالمواضع الستة، تعديلات الالتهاب/دواعم السن، الجير، حالة ما حول الزرعة)؛ بينما يحتفظ عنصر التحكم باللب/العلاج اللبي بـ**معالجة** العلاج اللبي (قناة الجذر / الوتد / استئصال الذروة / الوتد المجاوز للُّب) مع إخفاء **تشخيص** اللب/القمة وامتصاص الجذر. يبقى كل من الترميم، والتركيبة، والتقويم، والحاجة إلى تاج/استبداله، وخطة الخلع قابلاً للتخطيط
- 🧪 نجاح 1746 اختبارًا آليًا (مع تخطي اختبار إضافي واحد) (Vitest) عبر 164 ملف اختبار (165 إجمالاً) تغطي الترقيم، والترجمات، والأنماط الجاهزة، والدعم متعدد اللغات، ومكوّن App، والسمة، واللمس، والإضافات، وإمكانية الوصول، وتكافؤ محاور التشخيص/المحاور السريرية
- 📖 توثيق واجهة برمجة تطبيقات بواسطة TypeDoc مع تعليقات JSDoc على جميع الصادرات العامة (`npm run docs`)
### 📦 الوحدات
- 🦷 شبكة الأودونتوغرام وواجهة بلاطات الأسنان
- 🎛️ عناصر التحكم ولوحة الحالة
- 🎨 محرك طبقات SVG والقوالب
- 🔢 ترقيم الأسنان وربط التسميات (FDI/العالمي/بالمر)
- 🌐 الترجمة والتوطين (HU/EN/DE/ES/IT/SK/PL/RU/PT-BR)
- 💾 تصدير/استيراد الحالة
- 📋 إضافات الحالة: قوالب ترميم جاهزة مسبقًا
- 🎨 إعدادات السمة: لوحة ألوان قابلة للتخصيص عبر خصائص CSS من نوع `--odon-*`
- 📱 تفاعلات لمس للجوال (تكبير باللمس، الضغط المطوّل، التكبير بالقرص، تبديل القوس)
- 🔌 نظام إضافات SVG مخصص
- ⚠️ نظام تحقق من الحالة والتلميحات
- ♿ إمكانية الوصول عبر لوحة المفاتيح ودعم ARIA
- 🔒 وضع القراءة فقط
- ✨ رسوم متحركة للتحديد
- 📝 نظام ملاحظات لكل سن
- 🧪 مجموعة اختبارات آلية (Vitest + Testing Library)
### 🛠️ عناصر التحكم في الواجهة
**🔝 الشريط العلوي:**
- مبدّل اللغة (قائمة منسدلة HU/EN/DE/ES/IT/SK/PL/RU/PT-BR)
- زر تبديل الوضع الداكن (أيقونة شمس/قمر، يبدّل بين السمة الفاتحة والداكنة)
- مبدّل نظام الترقيم (قائمة منسدلة FDI/العالمي/بالمر)
- زرا تصدير الحالة / استيراد الحالة
**📊 رأس المخطط:**
- مفتاح تبديل المنظر الإطباقي
- مفتاح تبديل إظهار أسنان العقل
- مفتاح تبديل إظهار العظم
- مفتاح تبديل إظهار اللب
- زر مسح التحديد
**🔍 مرشحات التحديد:**
- تحديد الكل / كل الموجود / الدائم / اللبني / الزرعات / كل المفقود
- تحديد العلوي / الأمامي العلوي 6 / أضراس علوية
- تحديد السفلي / الأمامي السفلي 6 / أضراس سفلية
**📋 أنماط الحالة الجاهزة:**
- إعادة ضبط الكل (إعادة ضبط الفم)
- تسنين لبني
- تسنين مختلط
- مفتاح تبديل انعدام الأسنان
**📦 قائمة إضافات الحالة المنسدلة:**
- جسور زركونيا علوية/سفلية (12-22، 13-23، 16-26، قوس كامل)
- جسور معدنية علوية/سفلية (12-22، 13-23، 16-26، قوس كامل)
- أطقم جزئية متحركة علوية/سفلية
- أطقم كاملة متحركة علوية/سفلية
- أطقم بار مع زرعات علوية/سفلية
**🦷 لوحة محرر السن** (للسن/الأسنان المحددة، مجمّعة في بطاقات قابلة للطي):
- **سطر أساسي:** تحديد السن (النوع الأساسي بما في ذلك أنماط التاج المكسور) ونسيج السن (طبيعي/جذر متبقٍّ/مكسور/مُجهَّز لتاج)
- **سطر الترميم:** القائمة المنسدلة المدمجة "Fix: …" / "Kivehető: …" للترميم (خيارات ثابتة لـ`restorationType`×`restorationMaterial` بالإضافة إلى خيارات تثبيت/تحريك `prosthesis`، مقيّدة حسب نوع السن)؛ خانة تسرب حافة التاج (تاج/جسر فقط)؛ خانات موقع التاج المكسور؛ مفاتيح الحاجة إلى تاج / الحاجة إلى استبدال تاج
- **سطر البري والتصبّغ:** قائمة منسدلة لنوع بري القاطع/الإطباقي، قائمة منسدلة لنوع البري العنقي، قائمة منسدلة لسبب التصبّغ (يتحول كل منها إلى مفتاح بسيط نعم/لا ضمن الإعدادات ← تفاصيل السن ← الوضع البسيط)
- **بطاقة التقويم:** الجهاز، الانزياح القريب من الوسط/البعيد عنه، الحركة العمودية (بروز/انغراس)، مفتاح الدوران — تظهر على سن طبيعي موجود
- **بطاقة النخر:** قائمة منسدلة لوضع عمق النخر، خانة نخر تحت التاج، قائمة منسدلة لشدة نخر الجذر، ومحدِّد أسطح النخر B/M/O/D/L مع نافذة منبثقة سياقية لعمق ICDAS/CARS وشارة للعمق الشعاعي
- **بطاقة الحشوات:** قائمة منسدلة لمادة الحشو، محدِّد حشو لكل سطح (مع مادة لكل سطح)، مؤشر عيب حشو لكل سطح (هامشي/كسر/بري)، ملاحظات تنبيهية للنخر الثانوي وعيب الحشو
- **بطاقة الجذر ودواعم السن:** المحدِّد المدمج لحالة اللب/العلاج اللبي، محدِّد التشخيص القمي، محدِّد النوع الفرعي للآفة حول الذروة (التهاب دواعم السن القمي العرَضي/اللاعرَضي فقط)، محدِّد نوع امتصاص الجذر، محدِّد درجة الحركة، محدِّد حالة ما حول الزرعة (للزرعات فقط)
- **مؤشرات خاصة:** خطة/جرح الخلع، فراغ مغلق بعد الفقد، إغلاق الشقوق، فقدان نقطة التماس، الجير، الوتد المجاوز للُّب، استئصال الذروة، دعامة الجسر
### 🦷 أنواع الأسنان والحالات
**تحديد السن (النوع الأساسي):**
| القيمة | الوصف |
|---|---|
| `none` | سن مفقود |
| `tooth-base` | سن دائم |
| `milktooth` | سن لبني (مؤقت) |
| `implant` | زرعة سنية |
| `tooth-under-gum` | سن تحت اللثة (لم يبزغ) |
**أنماط السن المكسور:**
`tooth-broken-inicisal`, `tooth-broken-distal-inicisal`, `tooth-broken-distal`, `tooth-broken-mesial-distal-inicisal`, `tooth-broken-mesial-distal`, `tooth-broken-mesial-inicisal`, `tooth-broken-mesial`, `no-tooth-after-extraction`
**نسيج السن الأساسي (الأسنان الدائمة):**
`natural` (الافتراضي)، `radix` (جذر متبقٍّ)، `broken` (مكسور)، `crownprep` (مُجهَّز لتاج)
**نوع الترميم (الأسنان الدائمة):**
`none`, `crown`, `inlay`, `onlay` (بمنظر إطباقي فقط), `veneer`, `bridge`
**مادة الترميم (الأسنان الدائمة):**
`none`, `emax`, `gold`, `gradia`, `zircon`, `metal`, `metal-ceramic` (تُرحَّل إليها تاجات `metal` القديمة), `telescope`, `temporary`
**خيارات الترميم مقيّدة حسب نوع السن** (الدالة `restorationOptions()` في `src/registry/restorations.ts`): تعرض الزرعة فقط أنواع ترميم `crown`/`bridge` (مركبة مع طبقة موصل زرعة) بالإضافة إلى مدخلات `prosthesis` الخمسة أدناه؛ ويعرض السن المفقود/الفراغ فقط وسيط جسر `bridge` بالإضافة إلى مدخلي `prosthesis` للأطقم المتحركة؛ ويُخفي نسيج `radix` عنصر التحكم بالترميم تمامًا. الحقلان المسطّحان القديمان `crownMaterial`/`bridgeUnit` (قيم تثبيت الزرعة/الجسر من قبل الإصدار v1.14) أُلغيا من النموذج الحيّ — ولا يُقبلان إلا كمسار ترحيل للقراءة فقط للحمولات القديمة.
**التركيبة** (`prosthesis`؛ محور تحريك/تثبيت متعامد، يظهر كمدخلات "Kivehető:" في القائمة المنسدلة المدمجة للترميم):
`none`, `healing-abutment`, `locator`, `locator-denture`, `bar`, `bar-denture` (تثبيتات على الزرعة، مع أو بدون طقم علوي)، `removable-partial`, `removable-full` (أطقم مدعومة بالأسنان على سن مفقود/فراغ). يحمل السن إما ترميمًا ثابتًا أو تركيبة، لا كليهما أبدًا — فضبط أحدهما يمسح الآخر.
**تسرب حافة التاج** (`crownLeakage`؛ منطقية): تظهر فقط عندما يكون `restorationType` مساويًا لـ`crown` أو `bridge`؛ وتُفعِّل طبقة الرسم `crown-leakage`.
**خيارات العلاج اللبي (الأسنان الدائمة):**
`none`, `endo-medical-filling`, `endo-filling`, `endo-filling-incomplete`, `endo-glass-pin`, `endo-metal-pin`
**خيارات العلاج اللبي (الأسنان اللبنية):**
`none`, `endo-medical-filling`
يظهر `endo` و`pulpDx` عبر عنصر `