# Modules de composants partagés Les types de composants n'inventent pas chacun leur vocabulaire. Un petit ensemble de modules partagés est injecté dans les types qui les acceptent, pour que `visibility` veuille dire la même chose sur un `button` que sur un `kanban` — et que l'apprendre une fois suffise. ```yaml - type: table props: { className: 'rounded-lg' } dataSource: { table: invoices } visibility: { roles: [admin, finance] } responsive: { md: { props: { className: 'text-sm' } } } ``` | Module | Présent sur | Ce qu'il fait | | -------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------- | | `props` | Tous les composants | Sac clé-valeur rendu en attributs HTML — `className`, `variant`, et les clés propres au composant. | | `children` | Composants conteneurs | Définitions de composants imbriquées, ou chaînes simples. Profondeur arbitraire. | | `content` | Contenu et mise en page | Texte ou markdown en ligne, avec substitution de références. | | `dataSource` | Composants liés aux données | Lie à une table ou à un point de lecture système. | | `visibility` | La plupart des composants | Si le composant est rendu — par session, rôle, capacité, enregistrement ou état d'URL. | | `responsive` | La plupart des composants | Surcharges de propriétés par point de rupture. | | `interactions` | Composants interactifs | Comportement au clic, au survol, au défilement et à l'entrée. | | `action` | Composants de formulaire et bouton | Ce que fait l'exécution du composant — `crud`, `auth`, `navigate`, `automation`, `fetch`. | | `i18n` | Composants de contenu | Variantes de contenu par langue. | `props` et `children` sont les deux universels. Les autres s'obtiennent par adhésion, et c'est la page de référence d'un type qui dit lesquels il accepte. **Un module partagé n'apparaît jamais dans le tableau d'options d'un type.** Un tableau liste ce que le type déclare pour lui-même ; les modules qu'il reçoit sont soustraits avant que le tableau soit dessiné. Les imprimer ajouterait environ cent quatre-vingt-dix lignes à chacun des quatre-vingt-dix types et enterrerait la poignée qui concerne réellement ce type-là — `button` a treize options qui lui sont propres, et deux cent six une fois les modules comptés. ## `props` Un sac ouvert. Une clé peut porter une chaîne, un nombre, un booléen, un objet ou un tableau, et une clé présente sans valeur est refusée plutôt qu'ignorée. Comme il est ouvert, il n'a pas de tableau d'options : ce que signifie une clé donnée est décidé par le type qui la lit, et documenté sur la page de ce type. `className` est la seule clé que tous les types lisent de la même façon — des classes Tailwind ajoutées après le préstyle du composant, qui l'emportent donc dans la cascade. ## `content` Du texte en ligne, ou un objet structuré pour les types qui en acceptent un. Une chaîne est le cas courant ; un objet est la façon dont un type porte plusieurs emplacements nommés (`{ button: { text, animation } }`). Les valeurs résolvent les familles de références décrites plus bas. ## `visibility` Si le composant est rendu, tout simplement. Chaque garde est évaluée côté serveur : un composant qui en échoue une est absent du HTML plutôt que masqué en CSS, si bien que son contenu n'atteint jamais un lecteur qui ne devrait pas l'avoir. | Propriété | Description | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `when` | `authenticated` ou `unauthenticated` : n'affiche que dans cet état de session. | | `roles` | N'affiche qu'aux utilisateurs portant l'un de ces rôles. | | `capability` | Un pouvoir que la session appelante doit détenir (`admin-console`, `administer-accounts`). | | `declares` | Une capacité que l'application hôte déclare dans sa propre configuration (`auth`, `tables`, `automations`, `agents`, `buckets`, …). | | `unlessDeclares` | La négation de `declares`. | | `runtime` | Une capacité que l'application déclare **et** peut réellement exécuter sur ce déploiement. `ai` est la seule aujourd'hui. | | `unlessRuntime` | La négation de `runtime`. | | `condition` | Condition sur un champ (`field`, `operator` parmi `eq`/`neq`, `value`) — par exemple `$user.plan`. | | `record` | Garde par ligne : n'affiche que sur les enregistrements dont le champ nommé satisfait la condition. Exige un ancêtre lié à un enregistrement. | | `query` | Garde sur l'état d'URL : n'affiche que lorsque la propriété `page.query` nommée satisfait la condition. | `record` et `query` prennent tous deux le vocabulaire de conditions partagé : `eq`, `neq`, `in`, `notIn`, `contains`, `gt`, `lt`, `gte`, `lte`. Plusieurs opérateurs se cumulent. Les clés `unless…` sont les négations de leurs sœurs — `unlessDeclares` n'affiche que là où l'application ne déclare **pas** la capacité, `unlessRuntime` que là où elle ne peut pas tourner ici. Elles existent pour qu'un corps de page alternatif porte ses deux moitiés au même endroit : le catalogue là où les automatisations sont déclarées, l'état vide honnête là où elles ne le sont pas. Nommer la même capacité dans les deux moitiés est refusé au décodage, puisque le composant ne s'afficherait alors nulle part. `declares` demande ce que l'application servie déclare ; `runtime` demande si cette déclaration peut réellement tourner sur ce déploiement. Sur un hôte qui déclare un agent sans fournisseur d'IA configuré, `declares: agents` s'affiche et `runtime: ai` non. ## `dataSource` Lie un composant à des lignes : soit une table de la base, soit un point de lecture système. La liste complète des options, le vocabulaire de filtrage et de tri, et les familles de références vivent dans [Liaison de données](/fr/docs/pages-data-binding). Les deux extras qui voyagent avec sont documentés ici, parce qu'aucune autre page ne les porte. ### `autoSave` | Propriété | Description | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `saveMode` | Stratégie de déclenchement : `auto` (avec anti-rebond), `onBlur` (perte du focus) ou `manual` (bouton). `manual` par défaut. | | `autoSaveDebounceMs` | Délai d'anti-rebond de l'enregistrement automatique, en millisecondes. `500` par défaut, `100` minimum. | | `showSaveIndicator` | Affiche un indicateur d'état (Enregistrement… / Enregistré / Erreur). Vrai par défaut en `auto` et `onBlur`. | | `saveIndicatorPosition` | Où apparaît l'indicateur : `inline`, `toast` ou `toolbar`. | ### `search` | Propriété | Description | | ------------- | --------------------------------------------------------------------- | | `enabled` | Active la barre de recherche. Vrai par défaut. | | `placeholder` | Texte indicatif du champ de recherche. | | `debounceMs` | Délai d'anti-rebond de la saisie, en millisecondes. `300` par défaut. | | `highlight` | Surligne les termes trouvés dans les résultats. Faux par défaut. | ## `responsive`, `interactions` et `action` `responsive` surcharge des propriétés par point de rupture ; `interactions` déclare les comportements au clic, au survol, au défilement et à l'entrée ; `action` déclare ce que fait l'exécution d'un contrôle. Les trois sont assez vastes pour avoir leur propre page de référence — voir [Conception adaptative](/fr/docs/responsive-design), [Interactions](/fr/docs/interactions) et les familles d'actions sous [Scripts d'interactivité](/fr/docs/interactivity-scripts). ## `i18n` Les variantes de contenu d'un composant par langue. Une carte ouverte indexée par code de langue : elle ne porte donc pas de tableau d'options, ses clés étant les langues que l'application déclare. ## Substitution de références Les valeurs de `content` et de `props` résolvent quatre familles de références au moment du rendu : - `$record.` — l'enregistrement lié, sur un composant ayant un ancêtre qui lie un enregistrement. - `$vars.` — les variables de page. - `$currentUser.` — le contexte de session. - `$t:` — une clé de traduction des fichiers de langue de l'application. Une page rendue depuis du markdown ajoute `$frontmatter.*`. Ce que chacune résout, et ce qui se passe quand elle ne résout rien, est dans [Liaison de données](/fr/docs/pages-data-binding). ## Pages connexes - [Présentation des composants](/fr/docs/components-overview) — le catalogue des types. - [Liaison de données](/fr/docs/pages-data-binding) — `dataSource` en entier, filtres, tris et références. - [Références de page](/fr/docs/pages-references) — les familles `$record`, `$vars`, `$currentUser` et `$t:`.