Skip to Content
Documentation

Catalogue des sections

Sections globales et d'organisation réutilisables pour la composition de pages.

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. Les références ordinaires résolvent au runtime la dernière révision publié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 :

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

  • data_insights : cartes métriques, wrappers CTA, presets de filtres en haut et cartes de graphiques compactes

  • 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.

Les sections data_insights ajoutent insightLayout, insightFiltersJson, metricsJson et chartsJson. insightLayout accepte grid ou bento. insightFiltersJson reprend le vocabulaire des filtres Yayaw Table pour type (text, number, date, select ou multiSelect), columnId, operator, value et options séparées par des virgules. Les métriques et graphiques peuvent définir title, value, description, delta, deltaLabel, trend, size, ctaLabel, ctaHref et ctaTarget ; les métriques acceptent aussi icon, tandis que les graphiques acceptent type (line, area, bar ou progress) et des points séparés par des virgules.

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

Ces politiques sont la seule source d'accès : le dashboard, les actions serveur des blocks, le plan IA de block et les outils MCP de sections interrogent can() sur sections, dans l'organisation active pour les blocks d'organisation. Une chaîne de rôle de membre Better Auth, owner compris, n'accorde jamais l'accès à elle seule ; un membre sans groupe portant une politique sections est refusé.

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.

Au niveau page, PageStack.container, PageStack.gap et PageStack.sectionFrame pilotent respectivement la largeur, le rythme et le wrapper PublicPageSectionFrame. Les plans contextuels renseignent ces trois choix via page.layout; "none" retire le cadre partagé pour une composition art-directed.

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 ; la liste filtre par scope, statut, kind et recherche, tandis que includeDefinitions=true renvoie les définitions normalisées, inputs et slots média

  • 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_draft utilise les mêmes contrats pour construire une page brouillon à partir de 1 à 24 sections. Chaque entrée crée une nouvelle section de composition (kind: "create" avec une definition complète) ou réutilise une section publiée du scope (kind: "reuse" avec sectionSlug), avec des bindings d'inputs et de médias au niveau page validés contre les inputs et slots média déclarés par la section. Les nouvelles sections sont créées et publiées dans la bibliothèque de sections dans le même appel : une section publiée n'est qu'une brique réutilisable, et rien n'est public tant qu'une page qui l'affiche n'est pas publiée. Lisez d'abord les sections réutilisables, les composants et les images avec yayaw_cms_context_get, utilisez dryRun pour valider et gardez la publication de la page comme une action séparée.

Les valeurs par défaut des inputs et les bindings littéraux de page acceptent directement du JSON récursif borné. Déclarez tableaux et objets avec des valueShape récursifs afin que les diagnostics pointent le chemin imbriqué exact. Les anciennes listes JSON stringifiées restent compatibles.

Nettoyage du catalogue

Le catalogue CMS ne garde une section globale que si une page publiée du site de la plateforme la référence (ou si ce site la sème pour lui-même : la famille public-site-color-field et builder-value-grid), et un composant du catalogue que si une section gardée ou une page vitrine l'utilise. L'ancien générateur de sections Kibo UI est retiré ; le rendu des blocs Kibo reste, pour que les sections déjà copiées dans une organisation s'affichent encore.

bun run sections:inventory tourne à blanc : il lit DATABASE_URL et écrit inventaire-catalogue.md (en français) et inventaire-catalogue.json dans --out (par défaut catalog-inventory/), avec l'empreinte du plan. Pour les sections puis les composants, il liste ce qui est gardé et par quelle page vitrine, ce qui est archivé et pourquoi, ce qui est copié, dans quelle organisation et pour quelle page, et les fichiers de code proposés à la suppression avec la preuve du graphe d'imports (un fichier qu'un autre importe est gardé, avec qui l'importe).

bun run sections:inventory --apply --approve <empreinte> exécute exactement le plan approuvé, en une transaction : il copie d'abord (chaque section ou composant global retiré qu'une organisation utilise encore devient le sien, avec les métadonnées legacy: "true", legacySourceId et legacySourceSlug), puis repointe les pages et sections de l'organisation vers les copies par une nouvelle révision au contenu identique, puis archive (sections archived, composants disabled). Rien n'est effacé, et chaque changement est noté avec la valeur qu'il remplace dans ui_catalog_cleanup_journal (migration 0167, qui crée ce journal et ne change rien d'autre). Le plan est recalculé dans la transaction et refusé si son empreinte a changé ; une empreinte déjà appliquée ne fait rien. En production, ne le lancez qu'après lecture et accord sur le rapport de la base de production.

Les copies legacy gardent leurs propriétés visuelles brutes : les contrôles statiques de page ne leur opposent pas leurs couleurs et polices écrites en dur, le contexte de conception du site ne les liste jamais, et yayaw_sections_list les marque legacy.

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 sections perdent le cadre public partagé seulement lorsque leur stack parent définit explicitement sectionFrame: "none"

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