Ariane

Les composants sont des Custom Elements natifs — ils s'utilisent directement en HTML, aucun framework requis.

<ar-alert variant="success">
  Votre message a bien été envoyé.
</ar-alert>

<ar-spinner></ar-spinner>

Les Custom Elements s'enregistrent de manière asynchrone. Si votre code JavaScript interagit avec un composant au chargement de la page, attendez qu'il soit défini avant d'agir dessus.

await customElements.whenDefined('ar-alert');
const alert = document.querySelector('ar-alert');
alert.setAttribute('variant', 'success');

Via npm :

// Sous-path sans effet de bord : n'enregistre aucun composant
import { whenAllDefined } from '@ariane-ui/core/utils';
await whenAllDefined();
// Tous les composants ar-* sont prêts

await whenAllDefined({ prefix: 'acme-' });
// Préfixe personnalisé (import headless)

await whenAllDefined({ root: monElement });
// Limité à un sous-arbre (élément ou shadow root)

Via CDN (cdn/utils.js, sans enregistrer de composant) :

<script type="module">
  import { whenAllDefined } from 'https://unpkg.com/@ariane-ui/core@<version>/cdn/utils.js';

  await whenAllDefined();
  // Tous les composants ar-* sont prêts
</script>

Comme tout élément HTML, les composants Ariane se configurent par attributs (valeur texte, visible dans le HTML) ou par propriétés JavaScript (n'importe quelle valeur, y compris un objet ou une fonction).

<ar-pagination current="1" total="10"></ar-pagination>

Les attributs booléens suivent la convention native : leur simple présence suffit à activer le comportement, peu importe leur valeur.

<!-- Ces deux écritures activent "compact" -->
<ar-pagination compact></ar-pagination>
<ar-pagination compact="false"></ar-pagination>

<!-- Seule l'absence de l'attribut le désactive -->
<ar-pagination></ar-pagination>

Une propriété ne se pose qu'en JavaScript, jamais en attribut HTML — c'est le cas dès que la valeur n'est pas une chaîne de caractères (fonction, tableau, objet). Par exemple, ar-datepicker expose une propriété isDateDisabled pour désactiver certaines dates :

const datepicker = document.querySelector('ar-datepicker');

// Désactive les dimanches
datepicker.isDateDisabled = (date) => date.getDay() === 0;

La liste complète des attributs et propriétés de chaque composant est documentée dans sa Référence API, section « Attributs & Propriétés ».

Les <slot> permettent de projeter votre propre contenu à un emplacement précis du composant. Le slot par défaut (sans attribut slot) reçoit le contenu principal :

<ar-dialog label="Confirmation">
  <p>Voulez-vous vraiment supprimer cet élément ?</p>
</ar-dialog>

Un slot nommé cible un emplacement spécifique via l'attribut slot sur l'élément projeté — par exemple, le déclencheur d'ar-collapse :

<ar-collapse>
  <button slot="trigger">Afficher les détails</button>
  <p>Contenu affiché/masqué au clic sur le déclencheur.</p>
</ar-collapse>

Les slots disponibles pour chaque composant sont documentés dans la partie Référence API, section « Slots ».

Pour plus d'information sur ce sujet, voir la documentation complète sur MDN.

Les composants Ariane émettent des CustomEvent standards, préfixés par le nom du tag (ar-pagination-page-changed, ar-collapse-shown...). Écoutez-les comme n'importe quel événement DOM :

const pagination = document.querySelector('ar-pagination');

pagination.addEventListener('ar-pagination-page-changed', (event) => {
    console.log(`Page changée : ${event.detail.from} → ${event.detail.to}`);
});

Avec un préfixe personnalisé, seul le tag change : les noms d'événements restent en ar-* (<acme-pagination> émet ar-pagination-page-changed).

Les événements annulables sont indiqués dans la section « Événements » de la Référence API.

Le detail de chaque événement est un objet qui porte au minimum une clé id : la valeur de l'attribut id de l'élément au moment de l'émission, undefined s'il n'en a pas.

La liste complète des événements de chaque composant, avec le type de leur detail, est documentée dans la partie Référence API, section « Événements ».

Pour plus d'information sur ce sujet, voir la documentation complète sur MDN.

Certaines actions s'appellent directement en JavaScript sur l'élément, une fois le composant défini :

<ar-collapse>
    <button slot="trigger" class="ar-btn ar-btn-secondary">Révéler le contenu</button>
    <p>Contenu qui se révèle à l'ouverture</p>
</ar-collapse>

<script>
    const collapse = document.querySelector('ar-collapse');
    collapse.show();
</script>

La liste des méthodes disponibles par composant est documentée dans sa partie Référence API, section « Méthodes ».
Voir aussi la section précédente Attendre le chargement pour garantir que le composant est prêt avant d'appeler une méthode.

Le paquet npm publie des fichiers de données VS Code générés automatiquement depuis le Custom Elements Manifest — autocomplétion des tags ar-*, de leurs attributs, et des custom properties CSS (--ar-*). Référencez-les dans le .vscode/settings.json de votre projet :

{
    "html.customData": ["node_modules/@ariane-ui/core/dist/vscode.html-custom-data.json"],
    "css.customData": ["node_modules/@ariane-ui/core/dist/vscode.css-custom-data.json"]
}