مقدمة المشروع

@lh-ui/share هو الطبقة المشتركة الوحيدة المستقلة عن إطار العمل في عائلة مكوّنات lh-ui.

يستخرج «النصف غير المرتبط بإطار العمل» من مكتبة المكوّنات إلى مستودع مستقل: حساب أسماء الأصناف، وآلات الحالة، وحزم سمات إمكانية الوصول، ومحرك التموضع، والتمرير الافتراضي، ورموز السمة، ونصوص التدويل، ومصدر أنماط المكوّنات. تستهلك مكتبات واجهة المستخدم في كل طرف (lh-ui-plus / lh-ui-vue2 / lh-ui-react / lh-ui-uniapp) هذه الحزمة كتبعية npm في حالة النشر، بينما داخل العائلة ينعكس تعديل مصدر هذا المستودع فورًا في كل مكتبة واجهة دون الحاجة إلى بناء أو إصدار.

لماذا نحتاج هذه الطبقة

في الحقيقة لا يعتمد إلا جزء صغير من منطق مكتبة المكوّنات على تفاعلية إطار العمل:

ما إذا كان ينبغي إضافة اسم صنف ما هو حساب خالص للصيغة (size, disabled) => string؛
إلى أي جهة يجب أن ينقلب اللوحة المنسدلة هو حساب هندسي؛
الصفوف التي يجب أن تصيّرها القائمة هي حساب مجال فهرسي؛
نص زر «تأكيد» هو بحث في جدول حزم اللغة.

عند ترسيب هذه العمليات كدوال نقية، لن تضطر الأطراف الأربعة إلى كتابتها مرةً لكل طرف، والخطأ في كل مرة، وإصلاح الخطأ في كل مرة. ولا يتبقّى لطبقة إطار العمل سوى أمر واحد: ربط مخرجات الدوال النقية بالقالب، وإعادة مدخلات المستخدم إلى الدوال النقية.

ماذا يحوي المستودع

الطبقة	المحتوى	العدد
`src/core/<المكوّن>/`	دوال المكوّنات النقية (logic.ts / types.ts)، بلا استيراد لأي إطار عمل	56 مكوّنًا
`src/core/shared/`	النواة المشتركة بين المكوّنات (popper / virtual / sx / keyboard / focus-trap …)	12 وحدة
`src/theme/`	جانب السمة بلغة TS: الأنواع + 5 مسبقات إعداد + بدائيع وقت التشغيل	—
`styles/`	المصدر الوحيد لأنماط مكوّنات BEM + رموز `theme/common/*.scss`	58 مجموعة أنماط
`src/locales/`	التدويل (LhLocale باعث أحداث خالص) + هيكل لـ 6 لغات	—
`src/constants/` `src/types/` `src/utils/`	الثوابت / الأنواع / الأدوات النقية (بما فيها createNamespace)	—

منهج العد: core هو 56 دليل مكوّن، و styles هي 58 مجموعة — layout / tree-select لهما مصدر أنماط لكن منطقهما كله في طبقة واجهة المستخدم (حاوية التخطيط، والغراء الخاص بإطار العمل لمحدِّد الشجرة)، بينما يُسمّى config داخل دليل الأنماط config-provider. لمزيد من التفاصيل انظر بنية الحزمة.

مبادئ التصميم

تبعية صفرية لإطار العمل: يُمنع داخل src/ كتابة import 'vue' | 'react' | '@dcloudio/*'، وتحرس ذلك بوابة grep في CI. تستخدم هذه الحزمة external: []، أي حزم صفري التبعية بالكامل.
مصدر واحد للأنماط: styles/ هو المصدر الوحيد لأنماط مكوّنات العائلة بصيغة BEM، ولا يُسمح لأي مكتبة واجهة بإمساك نسخة من scss المكوّن. وتُستوعب اختلافات أسماء أصناف الانتقال عبر الأطراف بثلاثة mixin في transition.scss.
نسخة اختبار واحدة: توجد اختبارات core النقية في هذا المستودع فقط ضمن tests/unit/، وتتشارك المكتبات الثلاث هذه النتيجة دون تكرار النسخ.
التفاعلية لطبقة واجهة المستخدم: تُنتج core البيانات فقط، أما الاشتراك والتوصيل التفاعلي فيخصّان كل مكتبة واجهة. ولذلك فإن LhLocale باعث خالص، يعتمد على تزايد version كي يعيد كل طرف التصيير بآليته الخاصة.
الفاتح والداكن متكافئان: تدعم جميع المكوّنات افتراضيًا الوضعين الفاتح والداكن، ولا يُسمح للمكوّنات إلا باستهلاك الرموز عبر var(--lh-*, fallback)، ويحرس اكتمال الوضع الداكن البند السابع من verify:styles.

ما هو ليس

ليس مكتبة واجهة: لا تُصيّر هذه الحزمة أي شيء ولا تملك وقت تشغيل للمكوّنات. للحصول على مكوّنات جاهزة للاستخدام مباشرة، ثبّت إحدى مكتبات الأطر @lh-ui/vue3 / @lh-ui/vue2 وغيرها.
لا يعتمد على أي مكتبة واجهة أو أي إطار عمل: هو الطبقة السفلية، يُعتمَد عليه ولا يعتمد على أحد.
لا يتحكم في حالة النشر الديناميكية: ما يُنتجه تخصيص السمة هو نص <style> ومتغيرات CSS، أما كيفية حقنها في DOM فيحدده ConfigProvider في كل طرف.

تخطيط العائلة

lh-ui/
├── lh-ui-share/      ← هذا المستودع: الطبقة المشتركة المستقلة عن إطار العمل (core / theme / styles / locales)
├── lh-ui-plus/       طرف Vue3 (حقن أنماط كامل كأثر جانبي)
├── lh-ui-vue2/       طرف Vue2 (استيراد عند الطلب theme.css + style/<name>)
├── lh-ui-react/      طرف React
├── lh-ui-uniapp/     طرف uniapp
├── docs/             موقع توثيق العائلة (مستودع آخر)
└── native/           الأطراف الأصلية (android / ios / harmony، تستخدم applicationId بقيمة top.lhgb.*)

ترتيب الإصدار قيد إلزامي: يُصدر share أولًا، ثم تتبعه مكتبات واجهة المستخدم. أي تعديل على share → كتابة changeset → الإصدار → تشغيل pnpm up @lh-ui/share في كل مكتبة للتحقق.

الخطوة التالية

البدء —— تثبيت الحزمة واستيراد الأنماط وتشغيل أول دالة نقية
مداخل الحزمة والمسارات الفرعية —— كيف تختار من بين 77 مفتاح تصدير عند الطلب
كيفية الاستهلاك في كل طرف —— نماذج التوصيل لـ Vue3 / Vue2 / React / uniapp