Catalogue des composants

Vue d'ensemble

Yayaw inclut un catalogue interne de composants à :

• /dashboard/content/components

Le catalogue prend en charge un inventaire mixte :

• composants locaux depuis src/components/ui/*
• composants importés stockés dans des snapshots DB (non exécutables)

Docs liées :

• Catalogue des sections pour la création de sections réutilisables depuis des recettes de composants
• Design tokens pour le comportement d'aperçu des tokens au runtime
• Plan de contrôle pour les attentes de sécurité d'automatisation
• Vue d'ensemble du CMS pour toute la pile de contenu

Rôle CMS

Le catalogue des composants est l'inventaire de rendu du CMS. Il documente et prévisualise les pièces UI bas niveau que les sections peuvent utiliser, y compris les composants locaux et les snapshots de source importés. Les composants ne sont pas du contenu édité en eux-mêmes ; ce sont les primitives de rendu sûres utilisées par les sections réutilisables et les références directes de page.

Gardez les imports de composants non exécutables, compilez-les en recettes validées et ne publiez que les entrées qui réussissent les contrôles de compilation et de smoke render.

Objectifs :

• lister les composants UI depuis src/components/ui
• lister les composants UI importés depuis les révisions DB
• prévisualiser les composants compatibles avec des contrôles de props vivants
• afficher les fichiers source utilisés par chaque entrée
• valider le rendu compatible tokens avec les design tokens runtime courants

Scope et conventions

La source de vérité locale reste explicite : src/components/ui/catalog/registry.ts.

Scope actuel :

• fichiers de premier niveau dans src/components/ui/*.tsx
• entrées clés pour src/components/ui/kibo-ui/*/index.tsx
• entrée clé pour src/components/ui/yayaw-table/index.ts
• entrées importées depuis la DB (ui_component_registry_items) fusionnées dans le même inventaire

Conventions :

• une entrée de catalogue par composant clé
• un composant clé par dossier pour les répertoires de composants imbriqués
• le point d'entrée cible est index.tsx pour les dossiers imbriqués (les exceptions héritées sont explicites dans le registre)
• les entrées importées sont des éléments de registre à scope global avec snapshots source uniquement
• la règle de collision est déterministe : imported > local pour le même slug/id

Modèle d'aperçu

Le comportement d'aperçu est piloté par les recettes et partagé avec le rendu runtime :

• src/lib/server/services/components/ui-component-recipe-compiler.ts
• src/components/ui/catalog/ui-recipe-renderer-server.tsx
• src/components/ui/catalog/ui-recipe-renderer-client.tsx

Flux :

1. Le snapshot source est compilé en UiComponentRecipeV1.
2. L'aperçu du catalogue rend la recette avec des contrôles générés depuis propSchema, apiSchema et harnessSchema.
3. Le runtime de blocs résout les révisions de recettes publiées et utilise le même chemin de renderer.

Politique d'aperçu runtime uniquement :

• l'aperçu du catalogue utilise toujours le renderer de recettes interne
• aucune iframe de docs externe n'est intégrée dans le panneau d'aperçu
• les contrôles de parité d'aperçu passent par des onglets de variantes quand plusieurs bibliothèques exposent la même clé de composant

Garde de publication :

• compiled + smoke render OK => published (auto-publication pour imports ou recompilation)
• sinon => draft_blocked

Suppression douce :

• les composants importés sont retirés du catalogue avec le statut de publication deleted
• les snapshots source restent en DB pour audit/rejeu

Intégration AI SDK

Le fallback de compilation piloté par IA et la classification utilisent désormais Vercel AI SDK :

• src/lib/server/services/components/ui-component-ai-client.ts
• src/lib/server/services/components/ui-component-recipe-ai-fallback.ts
• src/lib/server/services/components/ui-component-import-classifier.ts

Règles :

• toutes les sorties IA sont validées avec des schémas zod stricts
• l'utilisation des modèles suit une chaîne de fallback résiliente intégrée ; les builders de pages/blocs peuvent encore demander un modèle préféré depuis les contrôles UI
• un fallback déterministe est toujours disponible si l'IA est indisponible
• aucun échec IA ne bloque les pipelines d'import ou de compilation

Classification par bibliothèque et catégorie

Les composants importés sont classifiés avec une stratégie hybride :

1. cache par sourceHash (réutilise les métadonnées de classification précédentes)
2. heuristiques déterministes (bibliothèque + groupe)
3. enrichissement AI SDK (affinage bibliothèque/catégorie)

Métadonnées persistées sur les lignes de registre :

• library
• group
• classificationSource
• classificationVersion
• classificationModel (quand l'IA est utilisée)

Politique de catégorie :

• normalisation en kebab-case minuscule
• les nouvelles catégories sont acceptées automatiquement après normalisation

Politique de bibliothèque :

• valeurs contrôlées : shadcn-ui, kibo-ui, yayaw, ai-sdk, custom

Composants vendoriés AI Elements

AI Elements est vendorié sous un namespace dédié :

• src/components/ui/ai-elements/*
• les ids du registre local de catalogue utilisent ai-elements-* pour éviter les collisions avec les ids shadcn principaux

Script d'installation/mise à jour :

• bun run components:install-ai-elements

Comportement du script :

• résout l'index de registre @ai-elements
• installe chaque élément de registre dans src/components/ui/ai-elements
• ignore les fichiers existants par défaut (--all pour réinstaller chaque élément)
• régénère src/components/ui/ai-elements/index.ts
• régénère les surcharges déterministes d'aperçu composite dans src/lib/server/services/components/ui-component-ai-elements-preview-overrides.generated.ts
• continue en cas d'échec par élément et rapporte un résumé

Comportement du catalogue :

• les fichiers AI Elements vendoriés sont listés dans src/components/ui/catalog/registry.ts
• ils sont tagués comme bibliothèque ai-sdk
• les familles AI Elements inconnues compilent en recettes composite par défaut afin de garder les aperçus disponibles
• les recettes composites locales ai-elements-* sont enrichies par des surcharges déterministes générées depuis les snapshots source (components:generate-ai-elements-previews)
• les éléments AI Elements importés utilisent automatiquement le préfixe de slug ai-elements-* quand leur slug de base entrerait en collision avec un id de catalogue local existant
• quand plusieurs bibliothèques exposent la même clé canonique de composant, des onglets d'aperçu permettent aux utilisateurs de changer de variante et indiquent si leurs sources normalisées sont identiques ou différentes
• le dashboard ne charge d'abord que les résumés de catalogue ; la recette et la source de la variante sélectionnée sont chargées à la demande afin que l'ouverture de la page Components ne compile ni ne transfère tous les aperçus de composants

Entrées unifiées et onglets de variantes

L'inventaire est groupé par clé logique de composant, pas par id brut de registre.

Règles :

• une ligne d'inventaire par clé canonique de composant
• chaque ligne peut exposer plusieurs variantes de bibliothèque (onglets dans l'aperçu)
• sélectionner un filtre de bibliothèque garde une ligne visible quand elle a au moins une variante de cette bibliothèque
• sélectionner un filtre de catégorie garde une ligne visible quand au moins une variante correspond à cette catégorie

Règles de regroupement par clé canonique

La résolution de clé canonique est définie dans :

• src/components/ui/catalog/catalog-identity.ts

Normalisation actuelle :

• les ids ai-elements-* sont groupés sous leur clé de base sans préfixe
• tous les autres ids conservent leur valeur d'origine comme clé canonique

L'ordre des variantes de bibliothèque est déterministe :

• shadcn-ui
• ai-sdk
• kibo-ui
• yayaw
• custom

Flux d'import et synchronisation de registre

La V2 prend en charge la gestion de composants depuis l'UI du catalogue pour les utilisateurs avec components:manage.

Flux d'ajout pris en charge :

• entrée de commande shadcn
• import de synchronisation d'alias de registre complet (onlyNew=true par défaut)
• collage de snapshot source (name, sourceFile, sourceSnapshot)
• import de snapshot source MCP via yayaw_component_import

Action de synchronisation de registre :

• syncRegistryAliasComponents(registryAlias, { onlyNew: true })

Politique non bloquante pour les nouvelles versions de bibliothèques :

• la découverte du registre utilise les candidats de payload d'index (index.json et registry.json)
• les éléments pas encore vendoriés localement peuvent quand même être importés via le pipeline de snapshots DB
• la validation allowlist reste appliquée pour les domaines source

Les outils MCP de composants exposent la même frontière de catalogue adossée à la base :

• yayaw_components_list et yayaw_component_get inspectent l'inventaire de composants
• yayaw_component_import stocke et compile un snapshot source
• yayaw_component_recompile recompile un snapshot stocké
• yayaw_component_publish publie une révision compilée et smoke-renderable
• yayaw_component_delete soft-delete une entrée importée

Ces outils ne mutent pas les fichiers source locaux du dépôt en production. Si un agent doit ajouter ou modifier des fichiers React first-party, c'est un changement de code qui doit passer par une branche et une pull request.

Indications d'usage pour le planificateur de blocs

Le planificateur IA de blocs consomme les indications d'usage du catalogue quand elles sont disponibles :

• court extrait d'exemple depuis le contexte CLI/persisté
• dépendances clés de registre
• liens docs/exemples

Ces métadonnées sont en lecture seule et passées dans le payload de prompt pour améliorer la sélection de composants et de props dans les arbres de blocs générés. Elles n'exécutent aucun code source DB.

Enrichissement de contexte CLI-first

Les imports résolvent maintenant le contexte depuis la CLI shadcn officielle en premier, puis appliquent des fallbacks déterministes.

Points d'implémentation :

• src/lib/server/actions/components/component-registry-actions.ts
• src/lib/server/services/components/ui-component-shadcn-cli-context.ts
• src/lib/server/services/components/shadcn-cli-runner.ts
• src/lib/server/services/components/ui-component-recipe-import-enrichment.ts
• src/lib/server/services/components/ui-component-import-preview-evidence.ts

Comportement :

• le runner CLI est local-first (bunx shadcn) avec fallback npx -y shadcn@latest, timeout, retry et logs structurés
• le résolveur agrège :
  • métadonnées/fichiers de payload shadcn view
  • liens shadcn docs --json pour les composants shadcn principaux
  • shadcn search + shadcn view pour les blocs d'exemples de registre
• le contexte résolu inclut :
  • sourceTitle / sourceDescription
  • exampleSnippets
  • registryDependencies
  • liens de docs (docs, examples)
  • indice d'interaction (click-trigger, selection ou fallback inline)
• la priorité des preuves d'aperçu est déterministe : CLI -> payload -> web -> source snapshot
• le contexte est mis en cache dans les métadonnées d'import par sourceHash (contextVersion, liens, extraits, dépendances), ce qui évite les appels CLI répétés lors des imports répétés
• quand le contexte CLI est indisponible, l'import reste non bloquant et le comportement de garde compilation/publication ne change pas
• aucun code source externe n'est exécuté ; seules les métadonnées et snapshots sont parsés

Politique interaction-first :

• les aperçus de type overlay doivent préférer des déclencheurs de clic explicites plutôt que des états toujours ouverts
• les blueprints IA composites sont neutres par défaut (pas de microcopy spécifique IA/chat sauf si les preuves source l'exigent explicitement)

Comportement des design tokens

L'aperçu du catalogue ne dépend pas uniquement du CSS de base.

Il résout les tokens runtime effectifs pour la session courante (surcharges globales + organisation) et applique des variables CSS scopées à la surface d'aperçu. Cela permet aux utilisateurs du dashboard de valider les composants UI contre les mêmes valeurs de tokens sémantiques que celles utilisées au runtime.

Validation

La cohérence du registre est validée par des tests :

• unicité des ids d'entrée
• existence des fichiers source
• références demoId résolues par la carte de démo

Gardes runtime/catalogue :

• aucune exécution de code DB (les snapshots source ne sont jamais évalués)
• publication bloquée quand les diagnostics de compilation ou le smoke render échouent

Commandes utiles :

bun test src/components/ui/catalog/registry.test.ts
bun test src/lib/server/services/components/ui-component-recipe-compiler.test.ts
bun test src/lib/server/services/components/ui-component-catalog-query.test.ts
bun run components:generate-ai-elements-previews

Variables d'environnement

• OPENAI_API_KEY
• OPENAI_COMPONENTS_AI_FALLBACK

Ces variables OpenAI sont optionnelles et n'affectent que l'enrichissement AI SDK pour les composants importés. Les surcharges locales d'aperçu AI Elements sont entièrement déterministes et ne requièrent pas OPENAI_API_KEY.

Direction du contrat

• scope produit global
• stockage de snapshot source pour audit/rejeu
• aucune exécution runtime de code stocké en DB

Type de référence :

• UiComponentRegistryItemV1 dans src/components/ui/catalog/types.ts

Tables DB :

• ui_component_registry_items
• ui_component_recipe_revisions
• ui_component_publications