المساهمة

مرحبًا بك في المساهمة بشيفرة lh-ui-plus! يقدم هذا المستند سير المساهمة بالتفصيل.

المتطلبات المسبقة

• Node.js 18+
• إدارة التبعيات عبر pnpm
• العمليات الأساسية في Git

تثبيت التبعيات

git clone https://github.com/lhgb-top/lh-ui-plus.git
cd lh-ui-plus
pnpm install

سير التطوير

1. تشغيل خادم التطوير

pnpm dev

2. تشغيل الاختبارات

pnpm test:unit      # اختبارات الوحدة للطبقة الأساسية Core
pnpm test:components  # اختبارات تكامل المكوّنات
pnpm test            # جميع الاختبارات

3. فحص الأنواع

pnpm typecheck

4. فحص الشيفرة

pnpm lint
pnpm lint:fix       # إصلاح تلقائي

5. البناء

pnpm build

6. عرض التوثيق

pnpm docs:dev

إضافة مكوّن جديد

يرجى الرجوع إلى AGENTS.md قسم «Adding or changing a component» للاطلاع على السير الكامل.

خطوات موجزة:

1. @lh-ui/share ضمن src/core/<name>/ — المنطق الأساسي + اختبارات الوحدة (تُنجَز في مستودع share، ويستهلكها هذا المستودع كتبعية npm)
2. packages/components/<name>/ — تغليف مكوّن Vue
3. packages/components/index.ts — التسجيل في lhComponents
4. src/index.ts — تحديث نقطة التصدير
5. tests/unit/components-registry.spec.ts — تحديث المصفوفة المتوقَّعة
6. tests/components/<name>.spec.ts — اختبارات المكوّن
7. docs/components/<name>.md — صفحة التوثيق
8. docs/.vitepress/config.ts — التنقّل في الشريط الجانبي

أوامر التحقق:

pnpm lint          # 0 أخطاء، 0 تحذيرات
pnpm typecheck     # بلا مخرجات
pnpm vitest run    # نجاح جميع الحالات
pnpm docs:build    # بناء ناجح

نشر موقع التوثيق

تُدار مسارات نشر موقع التوثيق مركزيًا عبر docs/.env.production (مصدر واحد)، والبناء للإنتاج مباشرة:

pnpm docs:build

متغير البيئة	الوصف	القيمة الافتراضية	مثال
DOCS_BASE	مسار base للموقع، ويجب أن يبدأ وينتهي بشرطة مائلة	/	/lhui/vue3/
DOCS_HOSTNAME	اسم النطاق الرسمي للموقع، يُستخدم في sitemap ووسوم SEO	https://www.lhgb.top	https://your-site.com

يعمل المتغيران معًا على مسارات الموارد وsitemap ووسوم SEO مثل og:url، فضلًا عن إعادة توليد robots.txt في نهاية البناء.

لماذا تُوضع في ملف .env بدلًا من المتغيرات السطرية: يحدث تحميل env المدمج في Vite بعد تقييم إعداد المستخدم، ولا بد لـ docs/.vitepress/config.ts من استدعاء loadEnv صراحةً لقراءة هذه القيم أثناء بناء الإنتاج؛ علاوة على ذلك يحوّل MSYS في Windows Git Bash متغيرات السطر مثل DOCS_BASE=/lhui/vue3/ تلقائيًا إلى مسارات مطلقة محلية. ولا يزال بالإمكان استخدام المتغيرات السطرية للتغطية المؤقتة (DOCS_BASE=/xxx/ pnpm docs:build)، لكن تعديل .env.production أكثر أمانًا في النشر اليومي.

اصطلاح بادئة النشر الموحَّد

تعتمد صفحة التنقّل لمكتبات LH-UI في بوابة فنغمو (www.lhgb.top) ضمن المسار (/ui) اصطلاحًا موحَّدًا /lhui/{اسم المكتبة}/ لمسارات نشر مواقع توثيق المكتبات، دون ربطه باسم إطار العمل. وتُنشر هذه المكتبة (نسخة Vue 3) في /lhui/vue3/ (وهي مثبَّتة في docs/.env.production)، وأمر بناء الإنتاج:

pnpm docs:build

يُرفع ناتج البناء إلى الخادم في المسار /home/webuser/nginx/lh-ui/vue3/ (النسخة المرجعية الموثوقة لجزء Nginx location موجودة في ملف العائلة docs/部署/nginx-lhui.conf.md، أما النسخة الفعلية فعلى الخادم في /etc/nginx/conf.d/nginx.conf). وقد نُشرت مواقع العائلة الثمانية كلها وفق هذا الاصطلاح:

المستودع	base	دليل alias	cleanUrls
lh-ui-plus (هذه المكتبة)	/lhui/vue3/	/home/webuser/nginx/lh-ui/vue3/	لا
lh-ui-vue2	/lhui/vue2/	/home/webuser/nginx/lh-ui/vue2/	لا (VuePress 1.x)
lh-ui-react	/lhui/react/	/home/webuser/nginx/lh-ui/react/	لا
lh-ui-uniapp	/lhui/uniapp/	/home/webuser/nginx/lh-ui/uniapp/	نعم
lh-ui-android	/lhui/android/	/home/webuser/nginx/lh-ui/android/	نعم
lh-ui-ios	/lhui/ios/	/home/webuser/nginx/lh-ui/ios/	نعم
lh-ui-harmony	/lhui/harmony/	/home/webuser/nginx/lh-ui/harmony/	نعم
lh-ui-windows	/lhui/windows/	/home/webuser/nginx/lh-ui/windows/	نعم

مواقع السلالة الأصلية الأربعة (android / ios / harmony / windows) هي مواقع VitePress تضم محاكيات HTML ثابتة مدمجة، وطريقة نشرها مطابقة تمامًا لمواقع سلالة الويب الأربعة. وأي مكتبة جديدة تتبع /lhui/{اسم المكتبة}/ مع توسيع location و.env.production خاصتها.

يجب أن يتضمن try_files في Nginx لمواقع cleanUrls (uniapp والمواقع الأصلية الأربعة) العنصر $uri.html، وإلا فلن تصل الطلبات ذات الروابط بلا امتداد إلى ملفات .html المُعالَجة مسبقًا؛ أما المواقع غير cleanUrls فلا تحتاج إلى هذا الجزء. التفاصيل في قسم «الشروط الثلاثة» من النسخة المرجعية.

معايير الشيفرة

• تستخدم فئات CSS البادئة lh- (مثل lh-button__text--primary)
• يجب أن تستخدم Composables البادئة Lh (مثل useLhConfigProvider)
• يجب أن تتبع كائنات الثوابت تسمية Snake بأحرف كبيرة بالكامل (مثل LH_TYPES_CONST)
• أسماء المسارات المستعارة: ~/* → packages/* (في هذا المستودع)؛ أما المنطق والتنسيقات المستقلة عن إطار العمل ففي @lh-ui/share وتُستورد عبر المسارات الفرعية لـ npm (@lh-ui/share/core/* و@lh-ui/share/styles/*)
• التنسيق: علامات اقتباس مفردة، وبلا فاصلة منقوطة، ومسافة بادئة بمقدار مسافتين، وعرض سطر 100 محرف

معايير الالتزام

feat: إضافة مكوّن Select المنسدل
fix: إصلاح مشكلة فقدان التركيز في Input
docs: تحديث توثيق التثبيت
test: إضافة اختبارات الحدود لـ Button
refactor: إعادة هيكلة منطق التفاعل في ConfigProvider

اصطلاحات المساعدة بالذكاء الاصطناعي

يُصان المشروع بمساعدة وكلاء ذكاء اصطناعي. وينفّذ المستخدم أوامر التحقق يدويًا، ولا يشغّل الذكاء الاصطناعي الاختبارات/البناء تلقائيًا.