Créer ou modifier des composants dans une bibliothèque de composants d'UI à thèmes

## Repérer les fichiers que touche un changement de composant Agissez comme une personne contribuant avec soin à une bibliothèque de composants réutilisable, personnalisable par thème et accessible. Avant toute modification, identifiez le comportement demandé, le composant ou l’utilitaire concerné et chaque surface directement liée. Appuyez-vous sur la structure réelle du dépôt, tout en prévoyant qu’un changement de composant puisse toucher certains des domaines suivants : - Composants d’exécution et fonctions composables. - Types publics et exportations. - Recettes de thème, variantes et valeurs par défaut. - Tests unitaires, de rendu, d’instantanés et d’accessibilité. - Documentation et exemples destinés aux utilisateurs. - Un bac à sable local ou une page de démonstration. Ne supposez pas que tous les domaines doivent être modifiés. Suivez le composant existant et son équivalent le plus proche, puis ne répertoriez que les surfaces requises par la demande. Limitez les conventions du code source et des tests à ces répertoires ; ne les appliquez pas sans discernement à la documentation, aux exemples ou aux outils. Préservez le comportement public existant, sauf si la tâche le modifie explicitement. Considérez la transmission des attributs, la résolution des valeurs par défaut, la sémantique d’accessibilité, le comportement de droite à gauche et les API documentées comme des contrats plutôt que comme des détails d’implémentation. ## Lire seulement les guides utiles et partir du générateur Lisez d’abord les consignes de contribution valables pour l’ensemble du dépôt, puis ne chargez que les références pertinentes pour la tâche. Par exemple, utilisez les consignes de structure des composants pour les propriétés (`props`), les emplacements (`slots`), les événements (`events`) et les modèles de gabarits ; celles des thèmes pour les emplacements et les variantes ; celles des tests pour le rendu, les instantanés et l’accessibilité ; et celles de la documentation pour les exemples et le balisage. Ne chargez pas toutes les références uniquement parce qu’elles existent. Partez du fichier concerné, examinez une implémentation récente et comparable, puis n’ouvrez des consignes supplémentaires que lorsque le changement touche le domaine correspondant. Utilisez les scripts de paquet déclarés par le projet et le gestionnaire de paquets pris en charge. Après l’installation des dépendances, exécutez toute étape obligatoire de préparation ou de génération de types avant de démarrer un bac à sable, le site de documentation ou des vérifications. Utilisez l’environnement local adapté au changement : le bac à sable de l’application principale, celui d’un autre cadriciel, un environnement de reproduction ciblé ou le site de documentation. Pour créer un composant, privilégiez le générateur approuvé par le dépôt. Examinez les fichiers générés avant de les modifier et ne demandez que les gabarits nécessaires à la tâche. Si aucun générateur ne convient, reproduisez manuellement l’organisation des fichiers et les conventions de nommage établies. ## Préserver l'ordre des valeurs par défaut du thème et la mise en page de droite à gauche Respectez systématiquement les conventions de code établies par la bibliothèque : - Séparez les importations réservées aux types lorsque la chaîne d’outils ou le guide de style l’exige. - Définissez les valeurs par défaut des propriétés à l’exécution au moyen de l’assistant standard et documentez les valeurs par défaut publiques dans l’API orientée types. - Ajoutez des marqueurs d’emplacement stables aux éléments rendus. Sur l’élément racine, un marqueur fourni par l’appelant doit remplacer la valeur de repli du composant ; les éléments internes conservent leurs propres marqueurs. - Lorsque la transmission automatique des attributs est désactivée, ordonnez ou résolvez les liaisons de la racine afin que les attributs de l’appelant ne soient pas écrasés silencieusement. - Construisez une sortie de thème réactive au moyen du mécanisme calculé standard, au lieu d’évaluer l’état du thème une seule fois. - Résolvez les valeurs par défaut selon toute la chaîne de priorité : entrée explicite du composant, contexte de groupe ou de champ le plus proche, remplacements du thème au niveau de la bibliothèque, valeurs par défaut du composant, puis configuration de l’application telle que définie par le projet. - Transmettez des entrées brutes aux assistants de contexte lorsque leur mise sous proxy modifierait la priorité d’injection. En l’absence de contexte plus proche, utilisez la valeur résolue du composant comme repli au lieu d’abandonner une valeur par défaut définie par le thème. - Transmettez les propriétés et événements de la bibliothèque de primitives au moyen de l’adaptateur du projet compatible avec les proxys afin de conserver les valeurs par défaut résolues. Utilisez des jetons de conception sémantiques plutôt que des valeurs brutes de palette. Utilisez des propriétés logiques d’espacement, de position, de bordure, de rayon et d’alignement du texte afin que les mises en page fonctionnent dans les contextes de gauche à droite comme de droite à gauche. Ajoutez des solutions de remplacement explicitement sensibles à la direction pour les transformations, curseurs, dégradés ou transitions lorsque les propriétés logiques ne peuvent pas exprimer le comportement. Maintenez l’implémentation en accord avec les modèles existants. N’introduisez pas, pour un seul composant, un système concurrent de valeurs par défaut, un autre chemin de transmission des propriétés ou une couche supplémentaire de résolution des thèmes. ## Créer le composant avec une liste de contrôle, du thème aux tests et à la documentation Suivez la création d’un composant ou d’une fonctionnalité majeure de composant à l’aide de cette liste de contrôle : 1. Générez l’ossature ou créez le composant à l’emplacement d’exécution standard. 2. Implémentez le comportement, les propriétés publiques, les emplacements, les événements et la sémantique d’accessibilité. 3. Ajoutez ou mettez à jour la recette du thème, notamment les emplacements, les variantes, les variantes composées et les jetons sémantiques. 4. Exportez les types publics et enregistrez toute interface de valeurs par défaut du composant requise par le système de thèmes. 5. Ajoutez, selon le besoin, des tests ciblés pour le comportement, les propriétés, les emplacements, la transmission des attributs, la direction et l’accessibilité. 6. Mettez à jour la documentation destinée aux utilisateurs avec l’utilisation, les exemples et les détails de l’API. 7. Ajoutez ou mettez à jour un exemple dans le bac à sable qui illustre le comportement modifié. 8. Exécutez l’analyse statique, les vérifications statiques de types et la suite de tests pertinente. N’utilisez les instantanés que lorsque le projet les considère comme un contrat utile et examinez les changements générés au lieu de les accepter automatiquement. Concentrez les tests sur les comportements significatifs de l’extérieur et sur les règles de priorité connues. Lorsque la documentation est déployée avant une version du paquet, conservez le marqueur de préversion approuvé par le projet sur les titres ou exemples concernés. Ce marqueur indique volontairement que la documentation fusionnée peut décrire une fonctionnalité qui sera livrée dans la prochaine version ; ne le retirez pas et ne le signalez pas comme incohérent sans vérifier la politique de publication. ## Lancer vraiment le lint et les tests, puis ouvrir la demande d'intégration avec les résultats Comparez le diff final avec les modèles établis les plus proches et avec la demande d’origine. Vérifiez les points suivants : - La structure du composant, les types publics et les exportations sont cohérents. - Le code du thème utilise des jetons sémantiques et préserve toute la chaîne de priorité des valeurs par défaut. - Les attributs de la racine et les marqueurs d’emplacement respectent les remplacements fournis par l’appelant. - Les propriétés logiques ou les variantes de direction explicites couvrent le comportement de droite à gauche. - Les tests couvrent les propriétés, les emplacements, les comportements et les exigences d’accessibilité modifiés. - La documentation contient l’utilisation, les exemples et les changements d’API nécessaires. - Les marqueurs intentionnels de préversion dans la documentation restent intacts. Exécutez les commandes d’analyse statique, de vérification de types et de tests pertinents du dépôt, puis indiquez leurs résultats réels. N’affirmez pas que les vérifications sont réussies sur la seule base d’une inspection. Mettez la documentation à jour lorsque le comportement public change. Utilisez la convention obligatoire du dépôt pour les messages de commit et son modèle de demande d’intégration. Associez l’élément de travail pertinent, indiquez le type de changement, décrivez le comportement et la vérification, puis ne cochez que les éléments de la liste étayés par des preuves. Ne réécrivez pas, n’effectuez pas de `rebase` ou de `force-push`, et ne condensez pas l’historique des commits d’une personne contributrice uniquement pour le rendre plus ordonné. Plusieurs commits de développement peuvent être acceptables lorsque le dépôt effectue une fusion par squash ; respectez la politique de fusion réelle du dépôt et l’autorisation de l’utilisateur.