Catalogue des sections

Vue d'ensemble

Yayaw inclut une page de gestion des sections à :

• /dashboard/content/sections

Les sections sont l'unité UI réutilisable canonique pour le contenu de page partagé. Les documents de page insèrent des références de sections, pas des copies inline, afin que chaque page résolve au runtime la dernière révision publiée de la section référencée.

Le panneau d'aperçu des sections inclut des contrôles de viewport pour les largeurs desktop (1200px), tablette (820px) et mobile (390px). Les aperçus adossés à des recettes utilisent la surface d'aperçu runtime afin que les sections pleine largeur comme les en-têtes et pieds de page ne soient pas artificiellement contraintes par le cadre du catalogue.

Le catalogue prend en charge trois scopes :

• builtin : réservé à la compatibilité avec les anciennes sections rendues par le système
• global : sections réutilisables à l'échelle du site, disponibles pour les pages globales et d'organisation
• organization : sections disponibles uniquement pour les pages de l'organisation propriétaire

Docs liées :

• Catalogue des pages pour comprendre comment les documents de page référencent les sections
• Catalogue des composants pour le rendu de composants adossé aux recettes et le comportement d'import
• Modèles de données CMS pour les bindings des menus d'en-tête/pied de page
• Vue d'ensemble du CMS pour la place des sections dans la pile de contenu

Rôle CMS

Les sections se trouvent entre les composants bas niveau et les pages complètes. Elles sont l'unité réutilisable pour les bandes de contenu, en-têtes, pieds de page, sections de preuve, CTA et blocs de landing page générés. Les documents de page référencent des sections publiées par id ou slug stable, ce qui permet à un changement de contenu de se propager à chaque page qui utilise la même section.

Créez une section quand un contenu ou une mise en page doit être réutilisé. Gardez la composition ponctuelle dans une page uniquement quand aucune réutilisation n'est attendue.

En-tête et pied de page

L'en-tête et le pied de page sont des sections de page générées, pas des éléments réutilisables intégrés du catalogue. Les nouveaux défauts de page insèrent des variantes générées header et footer dont les props sont liées aux données globales :

• header-menu/main
• footer-menu/main

Cela garde les données de menu globales et localisées au lieu de les copier dans chaque document de page. Le catalogue de sections n'expose plus d'entrées initialisées Header ou Footer dans la palette d'insertion.

Les sections générées d'en-tête et de pied de page partagent le même contrat de menu itemsJson :

• link : lien direct de navigation/action/légal/social
• group : sous-menu ou groupe de pied de page libellé contenant des liens
• themeToggle : sélecteur de thème public
• languageToggle : sélecteur de locale public
• userMenu : action de compte publique qui rend la connexion hors session et l'accès au dashboard en session

L'en-tête rend la navigation desktop avec NavigationMenu et la navigation mobile avec un menu sheet. Le pied de page lit le même contrat JSON pour les groupes de navigation, liens légaux/sociaux et bascules d'actions publiques. Les liens d'action d'en-tête sont rendus d'abord, suivis de l'action de compte, puis des bascules publiques comme le thème et la langue.

Les documents de page hérités qui référencent encore builtin-header ou builtin-footer sont mis à niveau en noeuds d'en-tête/pied de page générés lors de la normalisation des documents.

Sections de contenu générées

Les sections de page adossées à des recettes prennent en charge les variantes de contenu suivantes :

• hero : hero équilibré avec texte et visuel/carte
• immersive_hero : hero adossé à une image avec overlay, cartes de panneau de commande, badges et accents de mouvement
• value_grid : grille de propositions de valeur réutilisable
• feature_split : texte avec cartes ou média d'appui
• system_map : diagramme de système connecté pour les récits d'architecture de plateforme
• mcp_console : récit d'opération MCP de style console
• proof : section compacte de preuves/statistiques
• signal_wall : mur de preuves avec révélation animée
• cta : section de conversion ciblée

L'éditeur de page expose uniquement les props que chaque variante peut rendre. Les flux Page AI et MCP peuvent toujours lier les mêmes props à des littéraux, des ressources média ou des données CMS globales avant publication.

Les listes de cartes et de preuves de sections générées rendent chaque élément valide fourni par le JSON lié au lieu de tronquer à un nombre fixe. Les éléments cardsJson acceptent title, description et un token icon stable optionnel comme table, users, billing, shield, workflow, database, content, settings, chart, code, mcp ou rocket.

Scope, ACL et cycle de vie

Ressource ACL :

• sections:list
• sections:read
• sections:manage

Politique de rôles :

• membre d'organisation : list/read
• manager/admin d'organisation : manage
• superadmin : manage

Statut de publication :

• draft
• published
• archived

Seules les sections publiées et prêtes côté validation apparaissent dans les palettes du page builder.

Contrat de définition (V1)

Les types partagés principaux vivent dans src/lib/shared/sections/types.ts :

• SectionScopeV1
• SectionDefinitionV1
• SectionBuiltinRendererDefinitionV1
• SectionRecipeDefinitionV1
• SectionCompositionDefinitionV1

SectionDefinitionV1 a trois familles :

• builtin_renderer : renderers de compatibilité pour les anciennes sections système
• recipe : sections générées par IA adossées à une UiComponentRecipeV1
• composition : arbres réutilisables de références de composants existants

Les nouvelles sections générées devraient préférer composition. Les sections de composition peuvent déclarer des inputs de section et des slots média, puis les mapper vers des props de composants avec des bindings input_slot et asset_slot. Les noeuds PageSection au niveau page peuvent surcharger ces inputs avec des littéraux, littéraux localisés, champs de données CMS globales ou ressources média via inputBindings et mediaBindings.

Les sections recipe exposent leur propSchema comme le même contrat d'input au niveau page. Lorsqu'une section recipe est insérée dans une page, l'éditeur alimente les PageSection.inputBindings localisés depuis les valeurs par défaut de la recipe au lieu de copier du JSON de section inline. Cela garde les exemples importés visibles dans le catalogue tout en permettant au contenu Yayaw et aux ressources média de remplacer chaque prop éditable par locale au niveau page.

Traitez le catalogue de sections comme un Storybook pour sections de page. Les définitions de section devraient garder une fixture copy neutre, comme Lorem Ipsum, et exposer des inputs éditables pour contenus, liens, listes JSON et médias. Le texte final propre à une page appartient à l'instance PageSection via inputBindings et mediaBindings, pas au template réutilisable.

Les noeuds de stack de composition supportent un petit contrat de présentation sensible aux tokens :

• alignement et justification
• conteneur activé/désactivé
• ton de surface : none, subtle, card ou contrast
• preset de motion : none, fade, lift ou stagger

Ne stockez pas de chaînes de classes arbitraires dans le JSON de section. Ajoutez d'abord un support runtime first-party pour les nouveaux primitives ou presets avant de les exposer dans la génération de sections.

L'ancienne forme de composition BlockDefinitionV1 reste prise en charge comme entrée de compatibilité, mais sections est le domaine canonique pour le nouveau code.

Modèle de données

Tables de schéma système sous-jacentes :

• ui_section_registry_items
• ui_section_revisions
• ui_section_publications

Notes de conception :

• les lignes de registre portent l'identité stable (scope, slug, nom, métadonnées, propriétaire)
• les révisions portent le JSON immuable validé SectionDefinitionV1 et les diagnostics
• les lignes de publication portent l'état de cycle de vie et la dernière révision publiée
• l'unicité (registry_item_id, definition_hash) assure l'idempotence

Les anciennes tables de catalogue ui_block_* ne sont plus le modèle de données produit. Certains anciens noms d'actions existent encore comme alias de compatibilité pendant la migration des appelants vers sections.

Pipelines de création

CLI et édition JSON

La création de section peut partir de références de composants ou de JSON édité. Les nouvelles sections sont stockées dans le registre de sections, validées et publiées uniquement quand les diagnostics sont prêts.

Planificateur IA de sections

Le planificateur IA utilise encore la route historique /api/ai/blocks/plan pendant la transition, mais les entrées de catalogue persistées sont des sections. Les imports d'actions serveur recommandés sont exposés depuis src/lib/server/actions/sections :

• listSectionsAction
• openSectionForEditingAction
• createSectionFromPromptAction
• createSectionFromAiPlanAction
• publishSectionAction
• archiveSectionAction
• listAvailableSectionsForPage

La planification ne mute rien. La création ne persiste qu'après confirmation du plan par l'utilisateur et import des composants manquants.

Promotion Page AI

Page AI génère des sections réutilisables par défaut. Le flux est :

1. Générer des recettes de sections.
2. Créer et publier les sections du catalogue.
3. Insérer des références PageSection dans le document de page.
4. Enregistrer la révision de page.

Si la promotion de section échoue, la sauvegarde/génération de page retourne une erreur explicite au lieu de persister silencieusement une copie inline.

Design De Sections MCP

Les clients MCP de confiance peuvent opérer directement le catalogue de sections :

• yayaw_sections_list, yayaw_sections_get et yayaw_sections_validate inspectent l'inventaire et les diagnostics
• yayaw_sections_create_draft et yayaw_sections_save_draft persistent des révisions brouillon uniquement
• yayaw_sections_publish et yayaw_sections_archive exigent un scope de publication explicite et des IDs de révision optimistes

yayaw_cms_page_design utilise les mêmes contrats pour créer depuis un prompt des sections de composition réutilisables en brouillon et une page brouillon. Il devrait d'abord inventorier les composants et ressources existants, utiliser dryRun pour la critique, et garder la publication comme action séparée explicite.

Générateur De Sections Kibo UI

yayaw_kibo_sections_generate est l'adaptateur de plan de contrôle pour le catalogue de blocs Kibo UI. Il mappe les slugs de blocs Kibo suivis vers des sections recipe CMS natives kibo-ui-block, afin que les aperçus et l'état de publication utilisent les contrats runtime Yayaw tout en rendant du source Kibo présent dans le dépôt plutôt que du TSX tiers importé depuis la base.

Les pages publiques de blocs Kibo exposent des snippets d'installation, mais l'endpoint de registre shadcn renvoie actuellement du JSON installable pour les composants Kibo, pas pour chaque page de bloc. Yayaw stocke donc uniquement les recipes de sections dans le CMS et les rend via des exemples de blocs Kibo vendoriés et leurs dépendances Kibo/shadcn, avec une adaptation minimale des chemins d'import pour l'app locale. Les exemples présents dans le dépôt gardent les valeurs par défaut officielles Kibo, puis acceptent des props éditables CMS comme titres, descriptions, liens, URLs média et champs de listes JSON afin que les PageSection.inputBindings injectent le contenu Yayaw localisé sans forker le layout Kibo.

Le générateur suit actuellement les 28 slugs de blocs Kibo UI publics du commit 3d63cdb15b79d972e3dc38a10997987672f9b263 de shadcnblocks/kibo. Il peut créer ou mettre à jour toutes les sections suivies, ou un sous-ensemble slugs. Lancez-le avec dryRun=true pour relire les cibles de création/mise à jour. Définissez publish=true seulement lorsque l'appelant veut explicitement publier les révisions validées.

Règles runtime

Les pages référencent les sections par id ou slug stable. La résolution runtime applique les règles de visibilité du scope de page et charge la révision publiée courante.

Visibilité :

• les pages globales peuvent utiliser les sections global
• les pages d'organisation peuvent utiliser les sections global et celles de la même organisation
• les sections d'organisation n'apparaissent jamais dans une autre organisation

Comportement de rendu :

• builtin_renderer délègue aux composants runtime internes
• recipe rend via le runtime de recettes
• composition rend via le runtime de composition composants/blocs

Les noeuds inline hérités PageGeneratedSection restent lisibles pendant la transition, mais les nouvelles sauvegardes les promeuvent en sections de catalogue réutilisables.

Validation

Vérifications utiles après des changements du catalogue de sections :

bun test src/lib/server/services/sections/section-definition-runtime.test.ts
bun test src/blocks/dashboard/content/sections/block-ai-create-drawer.test.tsx
bun run check
bunx tsc --noEmit