RFC: قشرة سطح المكتب — أنواع عناصر النوافذ المتراكبة لمكتبة رسومات ص

text/0000-قشرة-سطح-المكتب-أنواع-النوافذ.md

@@ -0,0 +1,170 @@
+- **عنوان المقترح:** قشرة سطح المكتب — أنواع عناصر النوافذ المتراكبة لمكتبة رسومات ص
+- **النطاق:** لغة `text/` (يمسّ `UINodeType` + `language-truth/builtins/ui_widgets.yaml` + مُصيّرات المنصّات)
+- **تاريخ البدء:** 2026-07-25
+- **رقم الـ RFC:** (يُترك فارغاً حتى الدمج)
+- **الحالة:** مقترَح (PR مفتوح)
+- **Issue التتبُّع:** (يُترك فارغاً حتى القبول)
+
+# ملخّص
+
+يضيف هذا المقترح فئةً جديدة من عناصر واجهة ص (`UINodeType`) مخصّصةً لبناء **بيئة سطح
+مكتب بطابع النوافذ المتراكبة** (شبيهة بويندوز): `نافذة`، `شريط_عنوان`، `شريط_تمرير`،
+`شريط_مهامّ`، `قائمة_ابدأ`، `لوحة_نظام`، `شريط_حالة`، `صندوق_تجميع`. تُرسَم كلّها على
+الباطن الحرّ (`/dev/fb0`) لنظام sad-os مباشرةً، وتُستدعى من كود ص بدوالّ بناء عربيّة
+(`نافذة(...)`، `شريط_عنوان(عنوان: "...")` …). النتيجة المرئيّة: يستطيع مبرمج ص كتابة
+سطح مكتب كامل — نوافذ قابلة للسحب بأزرار تصغير/تكبير/إغلاق، شريط مهامّ، قائمة ابدأ —
+بلغة ص خالصة، فوق مكتبة الرسومات القائمة، بلا X11/Wayland/SDL.
+
+هذا المقترح هو **الأساس اللغويّ (SoT)** للمرحلتين ١–٦ من
+`sad-os/متطلبات/خطة-مكتبة-ودجات-سطح-المكتب-شبيهة-بويندوز.md`.
+
+# الدافع (Motivation)
+
+مكتبة رسومات ص تملك اليوم ~٤٢ ودجتًا موصولًا (نصّ/زرّ/حقل/قوائم/حاويات) ومحرّك تخطيط
+وأحداث وحالة ناضجة، وتعمل على الباطن الحرّ. لكن **بناء سطح مكتب حقيقيّ** يتطلّب عناصر
+غائبة تمامًا: لا يوجد مفهوم «نافذة متراكبة بشريط عنوان وأزرار»، ولا «شريط مهامّ»، ولا
+«قائمة ابدأ». الخطّة الحاليّة لـ sad-os (سطح مكتب بلغة ص) تتعثّر عند هذه الفجوة.
+
+حالات استخدام واقعيّة لبرامج `.ص`:
+- **مدير ملفّات**: نافذة بشريط عنوان + شجرة مجلّدات + شريط تمرير + شريط حالة.
+- **مشغّل تطبيقات**: قائمة ابدأ تفتح نوافذ تطبيقات ص (لا `fork/exec`).
+- **صدفة سطح المكتب**: شريط مهامّ سفليّ بساعة حيّة (لوحة نظام) وأزرار النوافذ المفتوحة.
+
+بلا هذه الأنواع، يضطرّ كلّ مبرمج لإعادة تركيب «نافذة» يدويًّا من حاويات وأزرار في كلّ
+برنامج، بلا سلوك موحَّد (سحب/ترتيب z/تركيز) ولا مظهر متّسق.
+
+# الشرح التوجيهي (Guide-level explanation)
+
+يكتب مبرمج ص نافذةً هكذا — تمامًا كأيّ ودجت قائم، بدوالّ بناء ومعدّلات سلسلة:
+
+```sad
+استورد رسومات
+
+دالة ابنِ_مدير_الملفّات()
+    ارجع نافذة(
+        شريط_عنوان("مدير الملفّات — نظام ص")
+            .لون_خلفية("#0B264A"),
+
+        صف(
+            عرض_شجريّ()               # شجرة المجلّدات (RFC لاحق)
+                .عرض(200),
+            عمود(
+                نص_عنصر("مجلّد: المستندات"),
+                نص_عنصر("١٢ عنصرًا • ٣ مجلّدات")
+            )
+                .موسّع(),
+            شريط_تمرير()
+                .قيمة(40)
+        ),
+
+        شريط_حالة("جاهز • ١٢ عنصرًا")
+    )
+        .عرض(640)
+        .ارتفاع(400)
+نهاية
+
+تشغيل_تطبيق(ابنِ_مدير_الملفّات)
+```
+
+- **`نافذة(...)`**: لوح مرتفع بظلّ وحدود؛ حاوية عموديّة لأبنائها. تدعم `.عرض/.ارتفاع/.زوايا`.
+- **`شريط_عنوان(عنوان)`**: شريط ملوَّن بالعنوان (محاذاة RTL أصالةً) وثلاثة أزرار دائريّة
+  (إغلاق/تصغير/تكبير) على الحافّة اليسرى (اتّجاه RTL). ردود نداء الأزرار عبر معدّلات
+  الأحداث القائمة (`.عند_النقر`) في مرحلة لاحقة.
+- **`شريط_تمرير()`**: مسار رأسيّ بإبهام يعكس `.قيمة(٠..١٠٠)`.
+- **`شريط_مهامّ(...)`/`قائمة_ابدأ(...)`/`لوحة_نظام(...)`/`شريط_حالة(نصّ)`/`صندوق_تجميع(عنوان)`**:
+  عناصر القشرة المتبقّية (تُنفَّذ عبر مراحل الخطّة).
+
+المبرمج يفكّر فيها كـ«عناصر واجهة عاديّة» — لا صياغة جديدة في اللغة، فقط أنواع ودجت
+جديدة تتبع النمط ذاته (دالّة بناء + معدّلات سلسلة + إرسال أحداث موحَّد).
+
+# الشرح المرجعي (Reference-level explanation)
+
+الأثر على الأنظمة المتشابكة:
+
+- **مصدر الحقيقة (`language-truth/`):**
+  - `builtins/ui_widgets.yaml`: ٨ مُدخَلات ودجت جديدة (اسم عربيّ + وصف + توقيع) ⇒ يُعاد
+    توليد `shared/builtins/generated/builtin_registry_generated.h` (أسماء `Bw::WINDOW` …).
+  - لا كلمة مفتاحيّة ولا توجيه لغويّ جديد — العناصر دوالّ بناء لا صياغة.
+
+- **`UINodeType` (‏`features/graphics/core/include/sad_ui/types.h`):** ٨ قيم جديدة تُلحَق
+  **قبل `_Count`** كي لا تُزحزَح قيم الأنواع القائمة (التعداد `uint8_t`، والسعة كافية:
+  ~٩٥/٢٥٦ مستعملة). أسماؤها العربيّة في `core/src/types.cpp::getNodeTypeNames`.
+
+- **المحلل المعجمي/النحوي:** لا تغيير (تُحلَّل كاستدعاءات دوالّ بناء عاديّة).
+
+- **الشجرة المجردة (AST) / IR:** لا عقد جديدة — تُمثَّل بـ`IRNode` بنوعها الجديد وخصائصها.
+
+- **المفسّر:** دوالّ البناء تُسجَّل في `interpreter/src/ui/widget_builtins.cpp`
+  (نمط `MAKE_WIDGET_WITH_PROP_FN`/`MAKE_SIMPLE_WIDGET_FN` القائم).
+
+- **المترجم (sadc):** لا أثر على SIR/LLVM codegen — العناصر بيانات IR تُمرَّر لوقت تشغيل
+  الواجهة كبقيّة الودجات.
+
+- **المُصيّرات (المنصّات):** حالة رسم لكلّ نوع في `core/src/platform_renderer.cpp::renderNode`
+  (يشترك فيها الباطن الحرّ + سطح المكتب). **الباطن الحرّ أولويّة** (هدف sad-os). مُصيّرات
+  الويب/أندرويد/iOS/macOS تسقط `default` مبدئيًّا (تُصيَّر عنصرًا عامًّا) — **دَين توليد
+  متعدّد المنصّات متتبَّع**، لا يكسر البناء (كلّ `switch` على `UINodeType` فيه `default`).
+
+- **محرّك التخطيط:** أحجام `measureLeaf` افتراضيّة للعناصر الورقيّة الجديدة (شريط عنوان
+  يملأ العرض، شريط تمرير رأسيّ نحيل …). النافذة/صندوق التجميع حاويات (تتبع `measureColumn`).
+
+- **مدير النوافذ (`WindowManager`):** منطق سحب/ترتيب z/تركيز يُبنى فوق نظام الحالة
+  (`StateStore`) والأحداث (`event_dispatch`) القائمين — بلا حالة C++ خفيّة. يُفصَّل في مرحلة
+  م١ من الخطّة (خارج نطاق SoT هذا المقترح، لكنّه يعتمد على `نافذة`/`شريط_عنوان`).
+
+- **نظام الأخطاء:** لا رموز أخطاء جديدة.
+
+- **الأدوات (LSP/المنسّق/sadinfo):** الأسماء الجديدة تظهر تلقائيًّا عبر
+  `builtin_registry_generated.h` المولَّد (لا تدخّل يدويّ).
+
+- **التوافق الخلفي:** غير كاسر — إضافة أنواع/دوالّ جديدة فقط؛ لا تغيير سلوك قائم. الإلحاق
+  قبل `_Count` يحفظ التسلسل الثنائيّ للأنواع القائمة.
+
+**حالة التنفيذ عند فتح هذا المقترح:** طبقة الرسم الحرّة لثلاثة أنواع (`نافذة`/`شريط_عنوان`/
+`شريط_تمرير`) **منفَّذة ومُثبَتة بصريًّا** (لغة PR #282، مرحلة م١) — سبقت المقترح لإثبات
+الجدوى. هذا المقترح يُقنِّن الأنواع الثمانية ويرخّص **توصيل دوالّ البناء** (طبقة التوصيل)
+وبقيّة عناصر القشرة.
+
+# السلبيات (Drawbacks)
+
+- توسيع `UINodeType` بثمانية أنواع يزيد سطح الصيانة (٥ مُصيّرات × نوع). لكنّ `default`
+  يجعل التوسيع تدريجيًّا بلا كسر.
+- عناصر القشرة (شريط مهامّ/قائمة ابدأ) **خاصّة بسطح المكتب**؛ لا معنى لها على الجوّال/الويب،
+  فتبقى مُصيّرات تلك المنصّات فارغةً لها (فجوة مقصودة).
+- منطق مدير النوافذ (سحب/z) خارج SoT، فيبقى اتّساقه مسؤوليّة طبقة ص (مخاطرة تفتيت لو بُني
+  عدّة مرّات).
+
+# المبرّرات والبدائل (Rationale and alternatives)
+
+- **لماذا أنواع جديدة لا تركيب؟** يمكن نظريًّا تركيب «نافذة» من `حاوية+صفّ+زرّ`، لكنّ ذلك
+  يفقد: (أ) المظهر الموحَّد (أزرار النافذة المميّزة)، (ب) قياس التخطيط الخاصّ، (ج) نقطة
+  ارتكاز لمنطق مدير النوافذ. نوع مخصّص يطابق نمط `AppBar`/`Dialog`/`Card` القائم.
+- **بديل: إبقاؤها في sad-os لا في SoT اللغة.** مرفوض: العناصر بصريّة عامّة (نافذة/شريط
+  تمرير مفيدان لأيّ تطبيق ص سطح مكتب)، ومكانها الطبيعيّ مكتبة الرسومات لا نظام واحد.
+- **بديل: تركها ويب-أوّلًا.** مرفوض: الهدف الأوّل sad-os الحرّ (`/dev/fb0`)، لا الويب.
+- **أثر عدم الفعل:** تبقى خطّة سطح مكتب ص متعثّرةً، ويعيد كلّ برنامج اختراع النافذة.
+
+# أعمال سابقة (Prior art)
+
+- **أطقم أدوات سطح المكتب** (Win32، GTK، Qt): «نافذة» عنصر أوّليّ بشريط عنوان وأزرار
+  وحدود — نموذجنا يقتبس هذا مع محاذاة RTL أصالةً (أزرار على اليسار في RTL).
+- **Flutter/SwiftUI**: يبنيان النوافذ من عناصر أدنى، لكنّهما يستهدفان الجوّال أساسًا؛ سطح
+  المكتب الحقيقيّ (نوافذ متراكبة) يحتاج مفهوم نافذة صريحًا كما في أطقم سطح المكتب.
+- **الدرس لِـ ص (العربيّة أوّلًا):** أسماء عربيّة أولى (`نافذة`/`شريط_عنوان`)، ومحاذاة
+  RTL افتراضيّة في شريط العنوان (العنوان يمينًا، الأزرار يسارًا) — عكس المألوف الغربيّ.
+
+# أسئلة غير محسومة (Unresolved questions)
+
+- **قبل الدمج:** هل تُدرَج الأنواع الثمانية دفعةً في `ui_widgets.yaml`، أم تدريجيًّا مع كلّ
+  مرحلة؟ (الاقتراح: تعريفها كلّها في SoT الآن، وتوصيل دوالّ البناء تدريجيًّا مع الرسم.)
+- **أثناء التنفيذ:** توقيع `شريط_مهامّ`/`قائمة_ابدأ` (كيف تُمرَّر قائمة النوافذ/التطبيقات؟) —
+  يُحسَم مع مرحلتَي م٢/م٤.
+- **خارج النطاق:** منطق مدير النوافذ (سحب/z/تركيز)؛ عناصر عروض المستكشف (`عرض_شجريّ`/
+  `جدول_بيانات`) لها RFC/توصيل منفصل؛ توليد مُصيّرات الويب/الجوّال لهذه الأنواع.
+
+# إمكانات مستقبلية (Future possibilities)
+
+- **مدير نوافذ معياريّ** بلغة ص (سحب/تحجيم/z/لصق حوافّ) فوق هذه الأنواع.
+- **تبليط النوافذ** (tiling) و**مساحات عمل** متعدّدة.
+- **سمات سطح المكتب** (فاتح/داكن) عبر نظام السمات القائم.
+- **توليد مُصيّرات الويب** لهذه الأنواع (نافذة ⇒ `<div>` عائم) لمعاينة سطح المكتب في المتصفّح.