نظام التحقق

«التحقق» في lh-ui ليس مجرد إجراء شكلي — فكل بند يعترض فئة وقوعًا حقيقيًا من الانحدار. وتشرح هذه الصفحة ماذا يُتحقَّق من كل بند وكيف تُقرأ مخرجات الفشل.

verify:dts —— اتساق أنواع المخرجات

pnpm verify:dts

ماذا يتحقق: أن ملفات .d.ts المترجمة في es/ / lib/ متطابقة مع إعلانات أنواع المصدر، وأن الملفات التي تشير إليها مفاتيح exports موجودة فعلًا.

حالات فشل نموذجية:

تغيير نوع في المصدر دون إعادة تشغيل pnpm build (المخرجات قديمة)
تولّد sync:exports مفتاح exports لكن الملف المقابل لم يُبنَ (مسار مُجمَّع خطأ)
كتابة import type على شكل import، فيحمل المخرج نسخة إضافية من كود وقت التشغيل

طريقة الإصلاح: إعادة تشغيل pnpm build كاملةً ثم pnpm verify:dts.

verify:styles —— ستة بنود

pnpm verify:styles

السكريبت: scripts/verify-styles.mjs. تُنفَّذ البنود الستة بالترتيب، ويُخرج البرنامج عند فشل أيٍ منها.

1. لوحة EP

فحص القائمة السوداء: ظهور أي من القيم التسع المتخلفة عن EP (Element Plus) (#409eff و #e6a23c و #f56c6c و #67c23a و #909399 و #606266 و #303133 و #ebeef5 و #c0c4cc) في ملفات scss داخل styles/ يُسبِّب الفشل. وهذا درع انحدار بعد تنظيف D2 يمنع عودة ألوان النظام القديم — فألوان lh-ui تأتي كلها من تعريفات الرموز في styles/theme/common/variables.scss.

2. var fallback

التحقق من أن كل var(--lh-*) في scss المكوّنات يحمل قيمة fallback:

// ✅ نجاح
color: var(--lh-text-primary, rgba(0, 0, 0, 0.88));

// ❌ فشل
color: var(--lh-text-primary);

لماذا: عند غياب الرمز (يستخدم المستخدم جزءًا من الأنماط فقط، أو الرمز غير موجود في إصدار قديم)، فإن var() دون fallback يُحَلّ إلى قيمة غير صالحة فيُهمَل الإعلار — فيصبح النص أسود افتراضيًا وتختفي الحدود. أما وجود fallback فيضمن «انحطاطًا صالحًا للاستخدام».

3. رموز @use

التحقق من أن scss المكوّنات تشير إلى طبقة الرموز عبر @use لا أنثرت قيم hex حرفية:

// ✅ نجاح
@use 'theme/common/var' as *;
.lh-card { background: var(--lh-bg-color, #fff); }

// ❌ فشل
.lh-card { background: #ffffff; }

إعفاء: يُسمح بكتابة hex في قيمة fallback الخاصة بـ var() (فهي للانحطاط). وتُسرد رسالة الفشل الملف ورقم السطر.

4. اتساق التجميع

التحقق من أن styles/index.scss (التجميع الكامل) متسق مع «قائمة المكوّنات الناتجة عن فحص styles/*/index.scss». و**styles/index.scss يُولِّده scripts/build-styles.mjs، فلا تُعدِّله يدويًا** — فعدم إعادة تشغيل التوليد بعد إضافة دليل مكوّن جديد يُسبِّب عدم الاتساق.

5. المصدر الوحيد لأسماء أصناف الانتقال

التحقق من أن scss المكوّنات لا تكتب مباشرةً القيم الحرفية -enter-from / -leave-from:

// ❌ فشل: كتابة يدوية لنسختي أسماء أصناف الانتقال
.lh-dialog-fade-enter-from { opacity: 0; }

// ✅ نجاح: استخدام mixin
@include lh-enter-both('.lh-dialog-fade') { opacity: 0; }

لماذا: فـ Vue2 يستخدم -enter و Vue3/React يستخدمان -enter-from، والكتابة اليدوية ستفلت طرفًا حتمًا (لمزيد من التفاصيل انظر transition-mixins). وكان 16 مكوّنًا تكتب نسختين في كل ملف، فيُصحَّح مكان ويُنسى آخر.

6. إمكانية الوصول في الوضع الداكن

التحقق من أن الرموز في var.scss ذات القيم #{$lh-foo} (المخبوزة فاتحة في وقت الترجمة) لديها تجاوز مقابل في var-dark.scss.

هذا أهم بند. فقد أدّى مثل هذا النقص إلى بقاء نصوص القوائم / الجداول / الخطوط الزمنية تأخذ قيمًا فاتحة في الوضع الداكن فلا تظهر (أسود فوق أسود). لمزيد من التفاصيل انظر فخ الخبز في وقت الترجمة في الوضع الداكن.

ملاحظة: وقعت من قبل إصلاح لإنذار خاطئ — أخطأ فهرس verify:styles فأنذر زورًا بسطر مُعفى من no-fallback (الإيداع 791ff32). إذا بدا رسالة الفشل غير منطقية (سطر مُعفى ما زال يُنذر)، فتأكد أولًا من أنها ليست هذه المشكلة المعروفة.

verify:theme —— بوابة تباين AA

pnpm build          # ← يجب تشغيله أولًا، فهو يقرأ مخرجات es/
pnpm verify:theme

السكريبت: scripts/verify-theme-contrast.mjs.

ماذا يتحقق: أن نسبة تباين WCAG لجميع أزواج «نص / خلفية» في السمات الداخلية الخمس (وتمثيلاتها الداكنة) ≥ 4.5:1 (مستوى AA).

لماذا يجب قراءة مخرجات es/: لأن vars المسبقة لا تبلغ شكلها النهائي إلا بعد البناء (نتيجة اشتقاق buildPresetDarkVars موجودة أيضًا في المخرجات).

حالات فشل نموذجية:

مسبقة جديدة بلون رئيسي فاتح دون --lh-color-on-primary (نص أبيض على لون رئيسي فاتح تباينه 3.x:1 فقط)
لون نص الحالة المحدَّدة (--lh-selected-color) تباينه غير كافٍ فوق خلفية التحويم

طريقة الإصلاح: تعميق / تفتيح قيم الألوان ذات الصلة حتى يبلغ التباين الحد. ويمكن حساب النسب محليًا عبر getContrastRatio() و getRelativeLuminance() (مُصدَّرتان من src/theme/themes/index.ts)، دون تشغيل البوابة كاملةً في كل مرة.

لا يُشغَّل هذا البند في CI — فهو يحتاج إلى بناء أولًا، وحسابه غير يسير. ويُحرس يدويًا قبل الإصدار محليًا.

verify:versions —— اتساق الإصدارات

pnpm verify:versions

السكريبت: scripts/check-version-sync.mjs.

ماذا يتحقق: أن نطاق تبعية @lh-ui/share في package.json لكل من lh-ui-plus / lh-ui-vue2 يغطي إصدار share الحالي.

الحالة الحالية: ينجح عندما يكون share في 0.3.0. وسيفشل بعد إصدار 0.4.0 — لأن نطاق تبعية المكتبتين لا يزال ^0.3.0. وهذا سلوك متوقَّع: فوفق الخط الأحمر 5 (يُصدر share أولًا، ثم تتبعه مكتبات واجهة المستخدم)، بعد الإصدار اذهب إلى كلا المستودعين الشقيقين وشغّل في كلٍّ منهما pnpm up @lh-ui/share@0.4.0 ثم تحقق من الانحدار.

lint و typecheck

الأمر	نطاق الفحص
`pnpm lint`	`src` / `tests` / `scripts` / `vite.config.ts` / `vitest.config.ts`
`pnpm typecheck`	`src/*/` (تضمين `tsconfig.json`)

docs/ خارج النطاق — فموقع التوثيق مشروع Astro مستقل، يحرس جودته pnpm docs:build. وبالمثل فإن styles/ خارج نطاق typecheck (فـ SCSS يديره verify:styles).

بوابة الاعتماد على إطار العمل في lint: يُجري CI بحثًا (grep) داخل src/ عن ظهور import 'vue' / import 'react' / @dcloudio/* — وهذا الخط الأحمر 1، فيجب أن تكون core مستقلة عن إطار العمل.

الاختبارات

pnpm test

tests/unit/ هي النسخة الوحيدة من اختبارات core النقية (الخط الأحمر 3): تتشارك المكتبات الثلاث نتيجتها، ولا يُسمح لها بنسخها. ولا تحتاج اختبارات الدوال النقية إلى تصيير المكوّنات — بل تُبنى قيم rect حرفية ويُؤكَّد على المخرجات، وتتشارك الأطراف الأربعة التأكيدات نفسها.

ملفات الاختبار الرئيسية:

الملف	التغطية
`theme.spec.ts`	اتساق المسبقات (مزامنة المصدرين JS vars ومتغيرات SCSS)
`core/*.spec.ts`	منطق كل مكوّن من core
`shared/*.spec.ts`	خوارزميات النواة المشتركة (popper / keyboard / virtual وغيرها)

تشغيل التحقق كاملًا

القائمة الكاملة قبل الإصدار:

pnpm install
pnpm lint
pnpm typecheck
pnpm test
pnpm build                    # انتبه: sync:exports يُعدِّل package.json
pnpm verify:dts
pnpm verify:styles            # ستة بنود
pnpm verify:theme             # يحتاج بناءً أولًا
pnpm verify:versions          # بعد الإصدار يتحول إلى معالجة في المستوى الأدنى
pnpm docs:build               # موقع التوثيق

لا يتضمَّن prepublishOnly (الذي يُطلِقه pnpm release) سوى build + verify:dts + verify:styles. ولذا يجب تشغيل test / lint / typecheck / verify:theme يدويًا صراحةً.