Utilitaires

API des utilitaires

Toutes les classes utilitaires de Cauri sont produites par une seule map Sass, $utilities. Vous pouvez y ajouter, modifier ou supprimer des utilitaires sans écrire une seule règle CSS à la main.

Principe

Chaque entrée de la map $utilities décrit une propriété CSS, le nom de la classe et la liste des valeurs. Lors de la compilation, le fichier scss/utilities/_api.scss parcourt la map et, pour chaque entrée, appelle le mixin generate-utility. Celui-ci écrit une classe par valeur, puis la répète pour chaque point de rupture si l’utilitaire est responsive.

Le résultat est prévisible : la clé "float" avec les valeurs start, end et none donne .float-start, .float-end, .float-none, puis .float-md-start… pour chaque largeur. Par défaut, chaque déclaration porte !important afin que l’utilitaire l’emporte sur les styles des composants.

Clés d'un utilitaire

Clés d'un utilitaire
Clé	Rôle	Valeur attendue
`property`	Propriété CSS écrite dans la classe. Avec plusieurs propriétés séparées par un espace (`margin-right margin-left`), chacune reçoit la valeur.	Nom de propriété, ou liste de noms
`class`	Préfixe du nom de classe. S’il est absent, le premier nom de `property` est utilisé. Avec `null`, aucun préfixe : la classe se limite à la clé de la valeur (`.visible`).	Texte ou `null`
`values`	Valeurs possibles. Une liste simple (`auto hidden`) crée une classe par mot ; une map associe un nom de classe à une valeur ; la clé `null` donne une classe sans suffixe (`.shadow`).	Liste ou map
`responsive`	Génère aussi les variantes `-sm`, `-md`, `-lg`, `-xl` et `-xxl`.	`true` (défaut : `false`)
`print`	Génère aussi des variantes `-print` dans une règle `@media print`.	`true` (défaut : `false`)
`state`	Génère des variantes pour une pseudo-classe : `.cursor-pointer-hover:hover`.	Liste de pseudo-classes (`hover`, `focus`…)
`css-var`	Au lieu d’une propriété, la classe définit une variable CSS (`--bs-nom: valeur`). Sert aux utilitaires d’opacité.	`true`
`css-variable-name`	Nom de la variable CSS (sans `--bs-`) quand `css-var` est actif. Par défaut, la valeur de `class`.	Texte
`local-vars`	Variables CSS locales déclarées dans la même classe, avec leur valeur par défaut. Exemple : `--bs-text-opacity: 1` dans `.text-primary`.	Map `("nom": valeur)`
`rfs`	Applique le redimensionnement fluide RFS à la valeur (utilisé par `.fs-*`).	`true`
`rtl`	Avec `false`, les règles sont entourées des commentaires `rtl:begin:remove` et `rtl:end:remove`, que reconnaissent les outils de conversion de sens d’écriture.	`false`

Façons de décrire `values`

Façons de décrire `values`
Forme	Exemple Sass	Classes produites
Liste de mots	`values: auto hidden visible scroll`	`.overflow-auto`, `.overflow-hidden`, `.overflow-visible`, `.overflow-scroll`
Map nom → valeur	`values: (start: left, end: right, none: none)`	`.float-start`, `.float-end`, `.float-none`
Clé `null`	`values: (null: var(--bs-box-shadow), sm: var(--bs-box-shadow-sm))`	`.shadow`, `.shadow-sm`
Valeur `null`	`values: (10: null)`	Aucune classe : la valeur est ignorée

Ajouter un utilitaire#

Importez d’abord les variables de Cauri, déclarez votre map $utilities, puis importez le framework complet. Vos entrées sont fusionnées avec celles de Cauri.

@import "@bdu/cauri/scss/variables";

$utilities: (
  "cursor": (
    property: cursor,
    class: cursor,
    responsive: true,
    values: auto pointer not-allowed,
  ),
);

@import "@bdu/cauri/scss/cauri";

Classes obtenues

L’exemple précédent produit .cursor-auto, .cursor-pointer et .cursor-not-allowed, puis les mêmes classes avec chaque suffixe : .cursor-md-pointer, .cursor-xl-not-allowed… Dans le HTML, il suffit d’écrire class="cursor-pointer".

Modifier un utilitaire existant#

Pour changer une entrée de Cauri, importez aussi config : il expose la map complète. Fusionnez ensuite votre version. Ici, on ajoute la valeur 10 à l’opacité et on rend les bordures disponibles à l’impression.

@import "@bdu/cauri/scss/variables";
@import "@bdu/cauri/scss/config";

$utilities: map-merge(
  $utilities,
  (
    "opacity": map-merge(
      map-get($utilities, "opacity"),
      (
        values: map-merge(
          map-get(map-get($utilities, "opacity"), "values"),
          (10: .1),
        ),
      )
    ),
    "border-width": map-merge(
      map-get($utilities, "border-width"),
      (print: true)
    ),
  )
);

@import "@bdu/cauri/scss/cauri";

Supprimer un utilitaire#

Associez la clé à null : l’API ignore tout ce qui n’est pas une map. N’utilisez pas map-remove, car Cauri fusionne ses valeurs par défaut lors de l’import et l’utilitaire réapparaîtrait.

@import "@bdu/cauri/scss/variables";

$utilities: (
  "float": null,
  "shadow": null,
);

@import "@bdu/cauri/scss/cauri";

Utilitaire avec état et variable CSS#

Avec state, chaque classe gagne une variante -hover. Avec css-var, la classe définit une variable que vos propres règles peuvent lire.

@import "@bdu/cauri/scss/variables";

$utilities: (
  "cursor": (
    property: cursor,
    class: cursor,
    state: hover,
    values: (pointer: pointer, aide: help),
  ),
  "accent": (
    css-var: true,
    css-variable-name: accent,
    class: accent,
    values: (primary: #2B62AA, vert: #387A1B),
  ),
);

@import "@bdu/cauri/scss/cauri";

// Classes produites :
// .cursor-pointer, .cursor-pointer-hover:hover, .cursor-aide, .cursor-aide-hover:hover
// .accent-primary { --bs-accent: #2B62AA; }  .accent-vert { --bs-accent: #387A1B; }

Ajouter une couleur aux utilitaires#

Les utilitaires de couleur lisent la map $theme-colors. Une couleur ajoutée là donne .text-or, .bg-or, .border-or et .text-bg-or. Les variantes -subtle et -emphasis restent propres aux couleurs d’origine.

@import "@bdu/cauri/scss/variables";

$theme-colors: map-merge($theme-colors, ("or": #8A6A00));

@import "@bdu/cauri/scss/cauri";

Suffixes responsives

Les classes responsives s’appliquent à partir de la largeur indiquée et au-dessus (approche mobile d’abord). Sans suffixe, la classe vaut pour toutes les largeurs.

Suffixes responsives
Suffixe	Largeur minimale	Exemple
(aucun)	0	`d-block`
`-sm`	576 px	`d-sm-block`
`-md`	768 px	`d-md-block`
`-lg`	992 px	`d-lg-block`
`-xl`	1 200 px	`d-xl-block`
`-xxl`	1 400 px	`d-xxl-block`

Variables Sass associées

Variables Sass associées
Variable	Défaut	Effet
`$utilities`	Map de tous les utilitaires	Point d’entrée de l’API. Vos entrées sont fusionnées avec celles de Cauri.
`$enable-important-utilities`	`true`	Ajoute `!important` à chaque déclaration d’utilitaire. Avec `false`, les composants peuvent reprendre la main.
`$grid-breakpoints`	`xs: 0, sm: 576px, md: 768px, lg: 992px, xl: 1200px, xxl: 1400px`	Détermine les suffixes responsives et leurs largeurs.
`$prefix`	`bs-`	Préfixe des variables CSS écrites par les utilitaires (`--bs-text-opacity`).
`$utilities-text-colors`, `$utilities-bg-colors`, `$utilities-border-colors`	Maps issues de `$theme-colors`	Valeurs des utilitaires de couleur de texte, de fond et de bordure.

Bonnes pratiques

À faire

Gardez vos ajouts dans un seul fichier Sass importé avant cauri, pour que l’équipe sache où chercher.
Activez responsive seulement quand le besoin existe : chaque utilitaire responsive multiplie ses classes par six.
Nommez les classes avec un préfixe parlant (cursor, accent) et gardez les clés de valeurs courtes.

À éviter

Ne créez pas un utilitaire pour une seule page : une règle dans la feuille du composant suffit.
N’utilisez pas map-remove pour supprimer une entrée : employez null.
Ne modifiez pas les fichiers de node_modules : personnalisez par la map $utilities.

Accessibilité

Un utilitaire qui masque ou déplace du contenu (display, visibility, position) doit rester utilisable au clavier et avec un lecteur d’écran.
Ne supprimez pas les utilitaires de visibilité nécessaires aux textes réservés aux lecteurs d’écran.