diff --git "a/text/0000-\331\202\330\264\330\261\330\251-\330\263\330\267\330\255-\330\247\331\204\331\205\331\203\330\252\330\250-\330\243\331\206\331\210\330\247\330\271-\330\247\331\204\331\206\331\210\330\247\331\201\330\260.md" "b/text/0000-\331\202\330\264\330\261\330\251-\330\263\330\267\330\255-\330\247\331\204\331\205\331\203\330\252\330\250-\330\243\331\206\331\210\330\247\330\271-\330\247\331\204\331\206\331\210\330\247\331\201\330\260.md" new file mode 100644 index 0000000..3074e90 --- /dev/null +++ "b/text/0000-\331\202\330\264\330\261\330\251-\330\263\330\267\330\255-\330\247\331\204\331\205\331\203\330\252\330\250-\330\243\331\206\331\210\330\247\330\271-\330\247\331\204\331\206\331\210\330\247\331\201\330\260.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) و**مساحات عمل** متعدّدة. +- **سمات سطح المكتب** (فاتح/داكن) عبر نظام السمات القائم. +- **توليد مُصيّرات الويب** لهذه الأنواع (نافذة ⇒ `