AVL: لغة المدار المرئية (Almadar Visual Language)
AVL هي التدوين المرئي الرسمي لبرامج Orb. كل ذرة تُعرض كعنصر SVG <g>، قابلة للتركيب في مخططات أكبر. مخططات AVL محايدة لغوياً: متطابقة عبر الإنجليزية والعربية والسلوفينية.
البدائيات الهيكلية
الكيان (Entity)
نواة الوحدة المدارية. الخطوط المشعة تمثل الحقول. نمط الخط يشير إلى نوع الاستمرارية.
| الاستمرارية | نمط الخط |
|---|---|
persistent (مستمر) | خط متصل، سمك 2.5 |
runtime (وقت التشغيل) | متقطع: 6 3 |
singleton (مفرد) | حد مزدوج، سمك 3.5 |
instance (نسخة) | تقطيع دقيق: 2 3 |
المدار (Orbital)
حدود دائرية تمثل الغلاف المداري الذي يحتوي على الكيان وسماته وصفحاته.
السمة (Trait)
مدار بيضاوي حول نواة الكيان. كل سمة هي آلة حالة تحكم جانباً واحداً من السلوك.
الصفحة (Page)
علامة مربعة على حدود المدار. تمثل مساراً يربط واجهة السمة بعنوان URL.
البدائيات السلوكية
الحالة (State)
مستطيل مدور. الحالة الأولية لها علامة نقطة صغيرة. الحالة النهائية لها حد مزدوج.
الانتقال (Transition)
سهم بين الحالات. يمكن أن يكون مستقيماً أو منحنياً.
الحدث (Event)
شكل صاعقة. يطلق الانتقال.
الحارس (Guard)
شرط يجب أن يتحقق لإطلاق الانتقال. يُعرض كنص بين أقواس: [اسم-الحارس].
التأثير (Effect)
14 نوعاً من التأثيرات، كل منها بأيقونة مميزة:
| التأثير | الوصف |
|---|---|
render-ui | عرض نمط واجهة مستخدم |
set | تعيين قيمة حقل الكيان |
persist | حفظ في التخزين |
fetch | تحميل من التخزين |
emit | بث حدث لسمات أخرى |
navigate | تغيير المسار |
notify | عرض إشعار |
call-service | استدعاء واجهة برمجية خارجية |
spawn | إنشاء نسخة كيان |
despawn | إزالة نسخة كيان |
do | تنفيذ منطق |
if | فرع شرطي |
log | تسجيل في وحدة التحكم |
بدائيات البيانات
أشكال أنواع الحقول
كل نوع بيانات له شكل SVG مميز:
| النوع | الشكل |
|---|---|
string (نص) | دائرة |
number (رقم) | مثلث |
boolean (منطقي) | مربع |
date (تاريخ) | معين |
enum (تعداد) | حلقة |
object (كائن) | سداسي |
array (مصفوفة) | أعمدة |
الربط (Binding)
يشير إلى البيانات من المخطط: @entity، @payload، @state، @now، @config، @EntityName.
بدائيات التعبيرات
ألوان فضاءات أسماء المعاملات
| الفضاء | اللون | الكود |
|---|---|---|
| حسابي (arithmetic) | أزرق | #4A90D9 |
| مقارنة (comparison) | برتقالي | #E8913A |
| منطقي (logic) | أرجواني | #9B59B6 |
| نصي (string) | أخضر | #27AE60 |
| مجموعة (collection) | سماوي | #1ABC9C |
| زمني (time) | أصفر | #F39C12 |
| تحكم (control) | أحمر | #E74C3C |
| غير متزامن (async) | وردي | #E91E8F |
المخططات المركبة (الجزيئات)
AvlStateMachine
حلقة من الحالات مع انتقالات منحنية وتسميات أحداث ونصوص حراس وأيقونات تأثيرات.
AvlOrbitalUnit
الكيان + السمات + الصفحات في الغلاف المداري. المخطط الرئيسي لعرض محتويات الوحدة المدارية.
AvlClosedCircuit
حلقة تدفق الأحداث. يعرض نمط الدائرة المغلقة.
AvlEmitListen
وحدتان مداريتان متصلتان بسلك بث/استماع. يعرض التواصل بين السمات.
AvlSlotMap
تخطيط صفحة مع مناطق فتحات مسماة.
AvlExprTree
شجرة من المعاملات والقيم الحرفية ومراجع الربط. تصور منطق التعبيرات.
الاستخدام في MDX
استورد مكونات AVL في أي ملف .md أو .mdx:
import { AvlStateMachine, AvlOrbitalUnit } from '@almadar/ui/illustrations';
<AvlStateMachine
states={[...]}
transitions={[...]}
animated
/>
كيفية قراءة مخططات AVL
- ابحث عن نواة الكيان في المركز. نمط الخط يخبرك بنوع الاستمرارية.
- عُد الخطوط المشعة لمعرفة عدد حقول الكيان.
- تتبع المدارات البيضاوية لتحديد السمات (آلات الحالة).
- ابحث عن العلامات المربعة على حدود المدار للصفحات (المسارات).
- داخل كل سمة، تشكل الحالات حلقة مع أسهم انتقال بينها.
- تسميات الانتقال تعرض: اسم الحدث (غامق)، شرط الحارس (أقواس)، أيقونات التأثيرات (أسفل).
- ترميز الألوان: ألوان فضاء أسماء المعاملات تتبع الجدول أعلاه.