Contribution

Merci de contribuer à lh-ui-plus ! Ce document décrit en détail le processus de contribution.

Prérequis

• Node.js 18+
• Gestion des dépendances avec pnpm
• Bases de Git

Installation des dépendances

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

Flux de développement

1. Démarrer le serveur de développement

pnpm dev

2. Exécuter les tests

pnpm test:unit      # Tests unitaires de la couche Core
pnpm test:components  # Tests d'intégration des composants
pnpm test            # Tous les tests

3. Vérification des types

pnpm typecheck

4. Analyse du code (lint)

pnpm lint
pnpm lint:fix       # Correction automatique

5. Construction

pnpm build

6. Consulter la documentation

pnpm docs:dev

Ajouter un composant

Le flux complet est décrit dans AGENTS.md, section « Adding or changing a component ».

Étapes résumées :

1. @lh-ui/share → src/core/<name>/ — logique core + tests unitaires (réalisés dans le dépôt share, consommés ici en tant que dépendance npm)
2. packages/components/<name>/ — encapsulation des composants Vue
3. packages/components/index.ts — enregistrement dans lhComponents
4. src/index.ts — mise à jour des exports
5. tests/unit/components-registry.spec.ts — mise à jour du tableau attendu
6. tests/components/<name>.spec.ts — tests du composant
7. docs/components/<name>.md — page de documentation
8. docs/.vitepress/config.ts — barre latérale et navigation

Commandes de vérification :

pnpm lint          # 0 erreur, 0 avertissement
pnpm typecheck     # Aucune sortie
pnpm vitest run    # Tous les cas passent
pnpm docs:build    # Réussit

Déploiement du site de documentation

Le chemin de déploiement du site de documentation est configuré de manière centralisée dans docs/.env.production (source unique), la construction de production se résumant à :

pnpm docs:build

Variable d'environnement	Description	Valeur par défaut	Exemple
DOCS_BASE	Chemin de base du site, slashes obligatoires en début et en fin	/	/lhui/vue3/
DOCS_HOSTNAME	Nom de domaine canonique du site, utilisé pour le sitemap et les métadonnées SEO	https://www.lhgb.top	https://your-site.com

Ces deux variables s'appliquent simultanément aux chemins de ressources, au sitemap, aux balises SEO telles que og:url, ainsi qu'au fichier robots.txt régénéré en fin de construction.

Pourquoi dans un fichier .env plutôt que dans des variables en ligne : le chargement des variables d'environnement intégré à Vite intervient après l'évaluation de la configuration utilisateur, docs/.vitepress/config.ts doit appeler explicitement loadEnv pour lire ces valeurs lors de la construction de production ; de plus, MSYS sous Windows Git Bash convertit automatiquement DOCS_BASE=/lhui/vue3/ saisi en ligne de commande en un chemin absolu local. Une variable en ligne reste possible pour un remplacement temporaire (DOCS_BASE=/xxx/ pnpm docs:build), mais au quotidien il est plus sûr de modifier .env.production.

Convention de préfixe de déploiement unifiée

La page de navigation des bibliothèques de composants LH-UI du portail Fengmo (www.lhgb.top) (/ui) applique la convention unifiée /lhui/{nom-de-la-bibliotheque}/ aux chemins de déploiement des sites de documentation de chaque bibliothèque, sans liaison avec le nom du framework. Cette bibliothèque (version Vue 3) est déployée sous /lhui/vue3/ (inscrite dans docs/.env.production), commande de construction de production :

pnpm docs:build

Les artéfacts de construction sont transférés sur le serveur dans /home/webuser/nginx/lh-ui/vue3/ (la copie de référence faisant autorité des fragments de configuration Nginx se trouve dans docs/部署/nginx-lhui.conf.md de la famille de dépôts, la version en production se trouvant sur le serveur dans /etc/nginx/conf.d/nginx.conf). Les huit sites de la famille sont tous déployés selon cette convention :

Dépôt	base	Répertoire alias	cleanUrls
lh-ui-plus (cette bibliothèque)	/lhui/vue3/	/home/webuser/nginx/lh-ui/vue3/	Non
lh-ui-vue2	/lhui/vue2/	/home/webuser/nginx/lh-ui/vue2/	Non (VuePress 1.x)
lh-ui-react	/lhui/react/	/home/webuser/nginx/lh-ui/react/	Non
lh-ui-uniapp	/lhui/uniapp/	/home/webuser/nginx/lh-ui/uniapp/	Oui
lh-ui-android	/lhui/android/	/home/webuser/nginx/lh-ui/android/	Oui
lh-ui-ios	/lhui/ios/	/home/webuser/nginx/lh-ui/ios/	Oui
lh-ui-harmony	/lhui/harmony/	/home/webuser/nginx/lh-ui/harmony/	Oui
lh-ui-windows	/lhui/windows/	/home/webuser/nginx/lh-ui/windows/	Oui

Les quatre sites de la lignée native (android / ios / harmony / windows) sont des sites VitePress intégrant un simulateur HTML statique ; leur mode de déploiement est strictement identique à celui des quatre sites de la lignée web. Toute nouvelle bibliothèque étendra les location et .env.production selon la même convention /lhui/{nom-de-la-bibliotheque}/.

Pour les sites cleanUrls (uniapp et les quatre extrémités natives), le try_files de Nginx doit obligatoirement inclure $uri.html, faute de quoi les URL sans suffixe ne trouveront pas le .html pré-rendu ; les sites sans cleanUrls n'en ont pas besoin. Voir la section « les trois contrats » de la copie de référence.

Conventions de code

• Les classes CSS utilisent le préfixe lh- (par ex. lh-button__text--primary)
• Les composables doivent utiliser le préfixe Lh (par ex. useLhConfigProvider)
• Les objets constants doivent utiliser un nommage en MAJUSCULES_SNAKE (par ex. LH_TYPES_CONST)
• Alias de chemins : ~/* → packages/* (ce dépôt) ; la logique et les styles indépendants du framework sont dans @lh-ui/share, accessibles via les sous-chemins npm (@lh-ui/share/core/*, @lh-ui/share/styles/*)
• Formatage : guillemets simples, pas de point-virgule, indentation de 2 espaces, largeur de ligne de 100 caractères

Convention de commit

feat: ajout du composant Select déroulant
fix: correction de la perte de focus du champ Input
docs: mise à jour de la documentation d'installation
test: ajout des tests aux limites du Button
refactor: refactor de la logique réactive du ConfigProvider

Convention d'assistance IA

Le projet est maintenu avec l'assistance d'agents IA. Les commandes de vérification sont exécutées manuellement par l'utilisateur ; l'IA ne lance jamais les tests ou les constructions automatiquement.