RFC: تمرير بيانات الحدث (EventData) لردود نداء الواجهة في المترجم (②)

text/0000-تمرير-بيانات-الحدث-لردود-نداء-الواجهة.md

@@ -0,0 +1,76 @@
+- **عنوان المقترح:** تمرير بيانات الحدث (`EventData`: موضع/دلتا) لردود نداء الواجهة في المترجم (②)
+- **النطاق:** لغة `text/`
+- **تاريخ البدء:** 2026-07-22
+- **رقم الـ RFC:** 46
+- **الحالة:** مقبول (مُنفَّذ طرفًا لطرف في المحرّكين؛ PR التنفيذ رقم 251 نحو dev، جولتا مراجعة خصميّة، بناء ذرّيّ أخضر)
+- **Issue التتبُّع:** sadlang/s-programming-language#251
+
+# ملخّص
+
+ردود نداء أحداث الواجهة (مثل `عند_النقر`) في المترجم `sadc` تُستدعى **بلا بيانات الحدث**: لا تتلقّى إحداثيّات المؤشّر ولا دلتا الحركة. يقترح هذا الـ RFC توسيع توقيع ردود نداء الأحداث (وتوليد المترجم لها) لتمرير بنية `EventData` (x، y، deltaX، deltaY، نوع الحدث) الموجودة أصلًا في وقت التشغيل إلى منطق ص. النتيجة المرئيّة: برامج ص تفاعليّة تعرف **أين** وقع الحدث — فتُبنى وظائف كسحب النوافذ والرسم بالمؤشّر بمنطق ص خالص.
+
+# الدافع (Motivation)
+
+مدير نوافذ بيئة سطح المكتب بلغة ص (المتطلّب FR-009) يتطلّب **سحب شريط العنوان لتحريك النافذة** — وهذا يحتاج معرفة موضع المؤشّر ودلتا حركته في منطق ص. كشفت مراجعة معماريّة، وأكّدتها مراجعة تنفيذيّة، أنّ:
+
+- `dispatchCompiledEvent(const IRNode*, IREventType)` يستدعي `b.cb(b.data)` فقط (`sad_ui_runtime.cpp:911-936`) — ردّ النداء يتلقّى بيانات إغلاقه لا غير.
+- توقيع `FreestandingAppConfig.onEvent` بلا `EventData`، والجسر يُسقطها (`sad_ui_runtime.cpp:1126-1128`).
+- بنية `EventData{x, y, deltaX, deltaY}` موجودةٌ في وقت التشغيل (`types.h:486-494`) لكنّها **لا تعبر الحدّ** إلى ص.
+
+⇒ من غير هذا التوسيع، **يتسرّب منطق السحب حتمًا إلى C++** (كسر قيد «السياسة في ص، الآليّة في المكتبة»)، أو يتعذّر FR-009 كليًّا.
+
+# الشرح التوجيهي (Guide-level explanation)
+
+```sad
+# ردّ نداء يتلقّى بيانات الحدث (موضع/دلتا) — يعمل مترجَمًا
+دالة عند_سحب_الشريط(حدث)
+    # حرّك النافذة المركَّزة بمقدار حركة المؤشّر
+    النافذة.س += حدث.دلتا_س
+    النافذة.ص += حدث.دلتا_ص
+نهاية
+
+شريط_عنوان("عنوان النافذة")
+    .عند_السحب(عند_سحب_الشريط)
+```
+
+اليوم يكتب المستخدم `عند_النقر(دالّة)` والدالّة بلا وسائط. بعد المقترح، ردود نداء الأحداث المكانيّة تتلقّى وسيط `حدث` يحمل الموضع والدلتا — فيصير التفاعل المكانيّ (سحب/إفلات/رسم) ممكنًا بلغة ص.
+
+# الشرح المرجعي (Reference-level explanation)
+
+- **مصدر الحقيقة (`language-truth/`):** تعريف نوع/بنية `حدث` (EventData) في مصدر الحقيقة، وربط أنواع ردود نداء الأحداث المكانيّة بها.
+- **المحلل النحوي/AST:** لا صياغة جديدة إن مُرِّر الوسيط كبنية عاديّة؛ قد يلزم تمييز ردود النداء المكانيّة (تحمل وسيطًا) عن الفعليّة (بلا وسيط).
+- **المفسّر:** توحيد سلوك تمرير الحدث مع المترجم (قد يمرّره فعلًا أو يلزمه محاذاة).
+- **المترجم (sadc) — جوهر المقترح:** توليد SIR/LLVM لتواقيع ردود نداء الأحداث بحيث تستقبل مؤشّر/قيمة `EventData`؛ تعديل `dispatchCompiledEvent` ليمرّر `EventData` من الحلقة (`sad_ui_runtime.cpp:911-936`)، وتعديل `cfg.onEvent`/الجسر الحرّ (`:1126-1128`) لتمرير الموضع/الدلتا.
+- **نظام الأخطاء:** تحقّق تطابق توقيع ردّ النداء (بوسيط حدث مقابل بلا وسيط).
+- **الأدوات:** LSP يعرض توقيع ردّ النداء الجديد؛ المقتطفات تُحدَّث.
+- **التوافق الخلفي:** يجب أن تبقى ردود النداء بلا وسيط (`عند_النقر` بلا معامل) صالحةً — التوسيع **اختياريّ**: من يريد الموضع يعلن وسيط الحدث.
+
+# السلبيات (Drawbacks)
+
+- أكبر المقترحات الثلاثة أثرًا: يمسّ **توليد المترجم لتواقيع ردود النداء** — غير تافه ويلزمه اختبار انحدار للأحداث القائمة.
+- ازدواج تواقيع ردود النداء (بوسيط/بلا وسيط) يزيد تعقيد التحقّق.
+
+# المبرّرات والبدائل (Rationale and alternatives)
+
+- **الأفضل**: تمرير بنية `EventData` الموجودة أصلًا؛ يعيد استعمال بنية وقت التشغيل بلا اختراع نموذج جديد، ويحفظ المبدأ (السياسة في ص).
+- **بديل مرفوض**: قراءة موضع المؤشّر في C++ وتنفيذ السحب هناك — يكسر قيد المنطق-في-ص، ويبني سابقة لتسرّب منطق البيئة.
+- **بديل مرفوض**: مدمَج `موضع_المؤشّر()` عالميّ يُستقصى — يفصل الموضع عن الحدث ويولّد سباقات (الموضع وقت الاستعلام لا وقت الحدث).
+- **أثر عدم الفعل**: تعذّر FR-009 (سحب النوافذ)؛ حجب مدير النوافذ (المكوّن الجوهريّ) أو كسر قيد المنطق-في-ص.
+
+# أعمال سابقة (Prior art)
+
+- المتصفّح/DOM: معالِج الحدث يتلقّى `event` بـ`clientX/clientY/movementX`. Qt: `QMouseEvent`. Flutter: `GestureDetector` يمرّر `DragUpdateDetails.delta`. الدرس الموحَّد: الحدث المكانيّ يحمل موضعه ودلتاه إلى المعالِج — وهو ما يعتمده هذا المقترح.
+
+# أسئلة غير محسومة (Unresolved questions)
+
+- تمييز ردود النداء المكانيّة (بوسيط) عن الفعليّة (بلا وسيط): بالاستدلال من إعلان المعامل أم بأسماء أحداث مخصّصة (`عند_السحب` مقابل `عند_النقر`)؟ (يُحسم قبل الدمج.)
+- شكل بنية `حدث` المكشوفة لـص (حقول موحّدة؟). (يُحسم قبل الدمج.)
+- تكامل مع hit-test متعدّد النوافذ (توجيه الحدث للنافذة الصحيحة) — منطق ص، خارج نطاق هذا الـ RFC.
+
+# إمكانات مستقبلية (Future possibilities)
+
+أحداث لوحة المفاتيح الغنيّة (رمز/معدِّلات) لردود ص، أحداث اللمس/الإيماءات، إفلات السحب (drag-and-drop) بين النوافذ، تمرير عجلة الفأرة.
+
+---
+
+> **السياق**: آليّةٌ حاجزة في خطّة بيئة سطح المكتب الرسوميّة بلغة ص (الوضع الحرّ)، كشفتها مراجعة معماريّة. مقترحان شقيقان: [[0000-مدمج-الوقت-الحالي-للمترجم]] و[[0000-مدمجات-نظام-الملفات-في-المترجم-للوضع-الحر]]. هذا أضخم الثلاثة أثرًا على المترجم.