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èmeglobal: sections réutilisables à l'échelle du site, disponibles pour les pages globales et d'organisationorganization: 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
Formulaires dans les pages pour les sections formulaire, qui affichent la vue Formulaire d'une table dans les pages d'organisation
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/mainfooter-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/socialgroup: sous-menu ou groupe de pied de page libellé contenant des liensthemeToggle: sélecteur de thème publiclanguageToggle: sélecteur de locale publicuserMenu: 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/carteimmersive_hero: hero adossé à une image avec overlay, cartes de panneau de commande, badges et accents de mouvementdata_insights: cartes métriques, wrappers CTA, presets de filtres en haut et cartes de graphiques compactesvalue_grid: grille de propositions de valeur réutilisablefeature_split: texte avec cartes ou média d'appuisystem_map: diagramme de système connecté pour les récits d'architecture de plateformemcp_console: récit d'opération MCP de style consoleproof: section compacte de preuves/statistiquessignal_wall: mur de preuves avec révélation animéecta: 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:listsections:readsections: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 :
draftpublishedarchived
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 :
SectionScopeV1SectionDefinitionV1SectionBuiltinRendererDefinitionV1SectionRecipeDefinitionV1SectionCompositionDefinitionV1
SectionDefinitionV1 a trois familles :
builtin_renderer: renderers de compatibilité pour les anciennes sections systèmerecipe: sections générées par IA adossées à uneUiComponentRecipeV1composition: 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,cardoucontrastpreset de motion :
none,fade,liftoustagger
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_itemsui_section_revisionsui_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é
SectionDefinitionV1et les diagnosticsles 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 :
listSectionsActionopenSectionForEditingActioncreateSectionFromPromptActioncreateSectionFromAiPlanActionpublishSectionActionarchiveSectionActionlistAvailableSectionsForPage
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 :
Générer des recettes de sections.
Créer et publier les sections du catalogue.
Insérer des références
PageSectiondans le document de page.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_getetyayaw_sections_validateinspectent l'inventaire et les diagnostics ; la liste filtre par scope, statut, kind et recherche, tandis queincludeDefinitions=truerenvoie les définitions normalisées, inputs et slots médiayayaw_sections_create_draftetyayaw_sections_save_draftpersistent des révisions brouillon uniquementyayaw_sections_publishetyayaw_sections_archiveexigent 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
globalles pages d'organisation peuvent utiliser les sections
globalet celles de la même organisationles sections d'organisation n'apparaissent jamais dans une autre organisation
Comportement de rendu :
builtin_rendererdélègue aux composants runtime internesreciperend via le runtime de recettescompositionrend via le runtime de composition composants/blocsles 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