Variants de composants

Un variant est un jeu de props nommé, que l'on applique à un composant SmartCommon pour en modifier l'apparence sans le surcharger à chaque usage. C'est le mécanisme qui permet d'avoir un "bouton arrondi" ou une "liste compacte" dans toute l'application sans répéter les classes Tailwind.

Anatomie d'un variant

Un variant est un objet dont les clés décrivent les éléments internes du composant.

const rounded = {
  buttonProps: {
    className: "p-app-base rounded-full",
  },
};

Deux formes de clés, reconnues à leur écriture :

Les clés en majuscule sont fusionnées récursivement : un variant de Button peut donc piloter le Spinner qu'il affiche pendant un chargement.

const outlined = {
  buttonProps: {
    className: "text-gray-800 bg-white border",
  },
  Spinner: {
    spinnerProps: {
      className: "border-primary border-l-secondary",
    },
  },
};

Pour connaître les clés disponibles sur un composant, regardez les appels à mergeProps("...") dans sa source : chacun correspond à une clé de variant. Pour Button : button, label, icon, badge et le sous-composant Spinner.

Appliquer un variant

La prop variant accepte trois formes, combinables :

// 1. Par son nom (variant natif ou declare dans la configuration)
<Button variant="rounded" />

// 2. En objet, directement
<Button variant={{ buttonProps: { className: "rounded-full" } }} />

// 3. En tableau, applique de gauche a droite
<Button variant={["rounded", "uppercase", { labelProps: { className: "text-xs" } }]} />

Ordre et règles de fusion

Les sources sont appliquées dans cet ordre, la dernière gagne :

• le variant du thème actif, s'il en désigne un pour ce composant
• les entrées de la prop variant, dans l'ordre du tableau
• les props passées directement au composant

La fusion suit trois règles selon la propriété :

Une valeur de className ou de style peut aussi être une fonction. Elle reçoit les paramètres publiés par le composant via setParams, ce qui permet un style dépendant de l'état interne.

Variants natifs

SmartCommon livre aujourd'hui cinq variants natifs, tous sur Button :

<Button variant="outlined">Annuler</Button>
<Button variant={["rounded", "uppercase"]}>Valider</Button>

Variants personnalisés

Les variants propres à votre application se déclarent dans la configuration passée au Provider, sous components.variants, indexés par nom de composant puis par nom de variant.

// src/appConfig.js
export const appConfig = {
  components: {
    variants: {
      Button: {
        danger: {
          buttonProps: {
            className: "bg-red-600 text-white hover:bg-red-700",
          },
        },
        ghost: {
          buttonProps: {
            className: "bg-transparent border-none shadow-none",
          },
        },
      },
      ListItem: {
        compact: {
          itemProps: { className: "py-1 text-sm" },
        },
      },
    },
  },
};

// src/main.jsx
<Provider config={appConfig}>
  <Router />
</Provider>

Ils s'utilisent ensuite comme les variants natifs :

<Button variant="danger">Supprimer</Button>
<ListItem variant="compact" />

Si un nom personnalisé reprend un nom natif, les deux définitions fusionnent.

Thèmes

Un thème associe, pour chaque composant, un ou plusieurs variants à appliquer par défaut dans toute l'application.

components: {
  theme: "compact",
  themes: {
    compact: {
      Button: "rounded",
      ListItem: ["compact", "borderless"],
    },
  },
}

Le variant du thème est appliqué avant la prop variant, qui peut donc le surcharger ponctuellement.

Composants qui acceptent des variants

Plus de 70 composants passent par useVariantMerger et acceptent donc une prop variant.

Accepter des variants dans son propre composant

Un composant applicatif peut utiliser le même mécanisme, avec useVariantMerger.

import { useVariantMerger } from '@cap-rel/smartcommon';

export const MyCard = (props) => {
  const { variantProps, mergeProps, setParams } = useVariantMerger("MyCard", props);

  const { title, children } = variantProps;

  return (
    <div {...mergeProps("card", props => ({
      ...props,
      className: "rounded-lg border p-4",
    }))}>
      <h3 {...mergeProps("title", props => ({
        ...props,
        className: "font-semibold",
      }))}>
        {title}
      </h3>
      {children}
    </div>
  );
};

Ce qu'il faut retenir :

• le premier argument de useVariantMerger est la clé du composant, celle qu'on utilisera dans la configuration
• variantProps contient les props après fusion : lisez-y vos props métier, pas props directement
• chaque mergeProps("<clé>", ...) crée un point d'accroche pour les variants
• une clé en majuscule (mergeProps("Spinner", ...)) désigne un sous-composant et se fusionne récursivement

Pièges à connaître

Voir aussi

• SmartCommon - liste des composants
• Thèmes - mode clair et sombre, variables CSS
• Configuration du Provider
• Composants et pages