بنية الحزمة

بنية الحزمة

جانب المصدر

lh-ui-share/
├── src/
│   ├── core/                  طبقة دوال المكوّنات النقية (بلا استيراد لأي إطار عمل، بوابة grep في CI)
│   │   ├── <المكوّن>/            ثلاثي logic.ts / types.ts / index.ts
│   │   └── shared/            النواة المشتركة بين المكوّنات (12 وحدة، مُوحَّدة في <name>/index.ts)
│   ├── theme/                 جانب السمة بلغة TS: types + 5 مسبقات إعداد + بدائيع وقت التشغيل
│   ├── constants/             ثوابت LH_* (LH_SIZE_DEFAULT / LH_LANGUAGE_DEFAULT …)
│   ├── locales/               LhLocale (باعث خالص) + lang/ هياكل لغات الست
│   ├── types/                 الأنواع العامة (locale / components)
│   ├── utils/                 أدوات نقية (createNamespace / deepMerge …)
│   └── index.ts               مدخل التجميع الكامل
├── styles/                    المصدر الوحيد لأنماط مكوّنات BEM
│   ├── <المكوّن>/index.scss      58 مجموعة أنماط المكوّنات
│   └── theme/
│       ├── common/
│       │   ├── var.scss       رموز الوضع الفاتح (:root، 185 متغيرًا --lh-*)
│       │   ├── var-dark.scss  تجاوزات الوضع الداكن ([data-theme='dark'], .dark، 118 عنصرًا)
│       │   ├── variables.scss 183 متغيرًا SCSS من نوع $lh-* (!default)
│       │   ├── patterns.scss  6 mixin للزخارف الصينية
│       │   ├── transition.scss ثلاثة mixin لأسماء أصناف الانتقال (تستوعب اختلاف الطرفين)
│       │   └── a11y.scss      أنماط مساعدة لإمكانية الوصول
│       └── index.scss         تجميع السمة
│   └── index.scss             التجميع الكامل (الرموز + كل المكوّنات، يُولَّد بسكريبت، لا تُعدَّل يدويًا)
├── tests/unit/                النسخة الوحيدة من اختبارات core (تتشاركها المكتبات الثلاث، دون نسخ مكرر)
├── scripts/                   سكريبتات البناء والتحقق
├── docs/                      موقع التوثيق هذا (Astro Starlight)
└── .changeset/                changesets قبل النشر

مسؤوليات كل دليل

الدليل	المسؤولية	الخط الأحمر
src/core/<name>/	دوال المكوّنات النقية: حساب أسماء الأصناف / آلة الحالة / حزمة سمات aria	ممنوع import 'vue' | 'react' | '@dcloudio/*'
src/core/shared/	النواة المشتركة بين المكوّنات، يُعاد استخدامها مباشرة في كل طرف	نفس ما سبق؛ مُوحَّدة في <name>/index.ts
styles/	المصدر الوحيد لأنماط مكوّنات BEM	يُمنع نسخ الأنماط إلى مكتبة واجهة وتعديلها يدويًا؛ أسماء الأصناف lh-*؛ والألوان دائمًا var(--lh-*, fallback)
tests/unit/	النسخة الوحيدة من اختبارات core	لا تُنسخها مكتبات واجهة المستخدم
scripts/	extract-from-plus (لمرة واحدة) / build-styles / verify-* / release	—

منهج عدّ المكوّنات: 56 أم 58

كلا الرقمين صحيح، لكن كلًّا منهما يقيس شيئًا مختلفًا:

المنهج	الرقم	المصدر
مكوّنات دوال core النقية	56	أدلة المكوّنات ضمن src/core/ (دون shared/)
مجموعات أنماط المكوّنات	58	أدلة المكوّنات ضمن styles/ (دون theme/)

والاختلاف في هذه الثلاثة:

الاسم	core	styles	السبب
layout	—	✅	حاوية تخطيط، منطقها كله في طبقة واجهة المستخدم (توصيل نقاط التوقف التفاعلية لـ row/col)
tree-select	—	✅	الغراء الخاص بالمحدِّد في جانب إطار العمل، أما منطق بيانات الشجرة فيُعاد استخدامه من core/tree
config ↔ config-provider	config	config-provider	الشيء نفسه باسمَي دليل مختلفين

مخرجات البناء

يُنتج pnpm build أربعة أدلة، وfiles ينشر هذه الأربعة فقط:

المخرَج	البنية	الوصف
es/	تحاكي preserveModules بنية src/	ESM، كل ملف على حدة عند الطلب عبر المسار الفرعي
lib/	مماثل	CJS (شرط require)
dist/	dist/theme/*.css dist/styles/index.css	مخرجات الأنماط المجمَّعة
styles/	تُنشر كما هي مع الحزمة	مصدر SCSS، ليترجمها المشروع بنفسه

تبقى المخرجات صفرية الاعتماد على إطار العمل: يفحص verify:dts ملفات es/**/*.d.ts، ويفشل عند ظهور أي استيراد لإطار عمل.

شكل مخرجات مكوّن واحد (مثال button)

es/button/
├── index.d.ts        الأنواع
├── index.js          ESM
├── logic.d.ts
├── logic.js
├── types.d.ts
└── style/
    ├── index.css     أنماط المكوّن المترجمة (شكل طرف plus)
    └── index.scss    المصدر (أُعيدت كتابة @use إلى bare specifier، ويُوزَّع مع المخرجات)

lib/button/ مماثل في البنية. ثم تُغلِّف كل من مكتبتَي واجهة المستخدم الطبقة بمستوى إضافي es/components/<name>/style/index.css (طرف vue2 ينشر css فقط، ولا ينشر scss).