Faisceau UI est une bibliothèque de composants DOM accessibles pour navigateurs modernes. Elle associe les machines d'état de Zag.js à @lilian1315/create-element et faisceau, sans dépendre d'un framework. Son apparence s'inspire de shadcn/ui, avec des styles Sass compilés en CSS, les icônes open source de Lucide et des classes internes préfixées par fui-.
La bibliothèque fournit actuellement Select, Combobox, Checkbox, Collapsible, Tooltip, Dialog, Drawer et Toast. Chaque composant peut construire son propre DOM ou adopter un markup HTML déjà présent.
Le monorepo contient deux bibliothèques publiées sous un nom non scopé sur npm :
faisceau-zag: pont générique entre une machine Zag, les valeurs réactives Faisceau et des éléments DOM. Il gère le cycle de vie, les mises à jour et l'application réactive des props Zag.faisceau-uisur npm : composants, markup et styles. Il utilise le pont précédent et une machine Zag dédiée pour chaque composant lorsqu'elle existe.
Le package privé published-smoke importe les sorties construites par leurs points d'entrée publics,
vérifie leurs types et exécute une interaction réelle dans Chrome.
pnpm add faisceau-uiImporter un composant suffit, sa feuille de styles est incluse automatiquement
avec le JavaScript (chaque entrée importe son SCSS, compilé vers dist/styles/
pendant le build) :
import { createSelect } from 'faisceau-ui/select'Les sources Sass vivent dans src/styles/ : un fragment par composant, la base
partagée (base.scss), la liste partagée de la Combobox (listbox.scss) et les
partiels internes (_tokens.scss, _mixins.scss). Les consommateurs équipés de
Sass peuvent aussi reprendre ces sources pour construire une variante.
Chaque composant est également disponible depuis son sous-chemin, par exemple
faisceau-ui/select, faisceau-ui/collapsible, faisceau-ui/dialog ou
faisceau-ui/toast.
Pour utiliser directement le pont de bas niveau :
pnpm add faisceau-zag @zag-js/vanilla faisceauLe pont suit l'adapter Vanilla officiel et déclare ses runtimes en peer dependencies. Cette
version utilise Zag 2.0.0-next.3 et Faisceau 0.3.x. Le projet cible uniquement les navigateurs
modernes ; le rendu serveur ne fait pas partie de son contrat.
createSelect construit le markup avec @lilian1315/create-element. Le contrôleur reste arrêté jusqu'à son montage :
import { createSelect } from 'faisceau-ui/select'
const select = createSelect({
label: "Mode d'affichage",
placeholder: 'Choisir un mode',
clearable: true,
name: 'display-mode',
items: [
{ value: 'simple', label: 'Simple' },
{
value: 'expert',
label: 'Expert',
description: 'Affiche tous les réglages',
},
{ value: 'legacy', label: 'Historique', disabled: true },
],
})
select.mount(document.querySelector('#app')!)Une chaîne peut servir de raccourci d'item ; sa valeur et son libellé seront identiques.
Les options suivent Zag 2.0.0-next.3 : multiple, defaultValue, value, onValueChange,
disabled, readOnly, required, deselectable, loopFocus et alignItemWithTrigger.
Avec alignItemWithTrigger: true, l'option sélectionnée est alignée après le calcul de la hauteur
plafonnée du popup, y compris dans une longue liste. Sans sélection, en mode multiple ou lorsque
l'alignement exact ne tient pas dans la zone visible, Select conserve le positionnement standard
de Zag et Floating UI. La valeur vide est réservée au placeholder. Les items sont fixes pendant la
vie du contrôleur.
Références : machine v2, tests e2e d'alignement et démo du site.
La Combobox filtre par défaut les libellés sans tenir compte de la casse. Une fonction filter permet de remplacer ce comportement.
import { createCombobox } from 'faisceau-ui'
const combobox = createCombobox({
label: 'Commande',
placeholder: 'Rechercher une commande',
emptyLabel: 'Aucun résultat',
items: [
{ value: 'build', label: 'Build' },
{ value: 'test', label: 'Test' },
{ value: 'deploy', label: 'Déployer', disabled: true },
],
})
combobox.mount(document.querySelector('#app')!)Les deux composants acceptent multiple: true. Un Select affiche les libellés sélectionnés dans son trigger et garde sa liste ouverte pour permettre plusieurs choix. Une Combobox affiche chaque valeur sélectionnée sous forme de pastille retirable et vide son champ après une sélection afin de poursuivre la recherche.
createSelect({
label: 'Pays',
name: 'countries',
multiple: true,
defaultValue: ['fr', 'be'],
items: [
{ value: 'fr', label: 'France' },
{ value: 'be', label: 'Belgique' },
{ value: 'ch', label: 'Suisse' },
],
}).mount(document.querySelector('#countries')!)
createCombobox({
label: 'Villes',
name: 'cities',
multiple: true,
getRemoveLabel: (item) => `Retirer ${item.label}`,
items: [
{ value: 'paris', label: 'Paris' },
{ value: 'lyon', label: 'Lyon' },
{ value: 'lille', label: 'Lille' },
],
}).mount(document.querySelector('#cities')!)En mode enhance, l'attribut HTML natif suffit : <select multiple>. Les options portant selected deviennent les valeurs initiales. Pour récupérer toutes les valeurs d'un formulaire, utilisez new FormData(form).getAll(name).
Select et Combobox gardent un véritable <select> dans le document. Le contrôle natif porte le name, participe à FormData, applique required et disabled, et retrouve sa valeur initiale lors de form.reset(). Pour une Combobox, la valeur soumise est bien la valeur de l'option, pas son libellé visible.
Une sélection effectuée depuis l'interface visuelle émet les événements natifs bouillonnants input, puis change, sur ce <select>. Les listeners déjà attachés à un markup amélioré continuent donc de fonctionner. Si la validation native échoue, le focus est transféré vers le trigger du Select ou le champ de la Combobox.
const form = document.querySelector<HTMLFormElement>('#profile')!
createCombobox({
label: 'Ville',
name: 'city',
required: true,
items: [
{ value: 'paris', label: 'Paris' },
{ value: 'lyon', label: 'Lyon' },
],
}).mount(form)
form.addEventListener('submit', (event) => {
event.preventDefault()
console.log(new FormData(form).get('city'))
})Les fonctions enhanceSelect, enhanceCombobox et enhanceCheckbox adoptent un markup
existant minimal. Les classes fui-* constituent le contrat d'anatomie et doivent être présentes
avant l'appel. Le contrôle natif reste dans le document et conserve la soumission, la validation et
le reset du formulaire.
<form id="settings">
<div class="fui-select" id="mode-select">
<label class="fui-label">Mode d'affichage</label>
<select class="fui-select-native-select" name="display-mode" required>
<option value="" data-placeholder>Choisir un mode</option>
<option value="simple" selected>Simple</option>
<option value="expert">Expert</option>
</select>
</div>
</form>import { enhanceSelect } from 'faisceau-ui'
const select = enhanceSelect(document.querySelector<HTMLDivElement>('#mode-select')!)Seuls le conteneur fui-select et le <select class="fui-select-native-select"> sont
requis. Le label fui-label et la description fui-select-description sont optionnels ;
ils peuvent aussi être fournis dans les options. Le contrôle visible et le popup sont générés à
partir des options natives. La destruction retire les éléments générés, restaure le markup initial
et conserve la sélection native courante. Une option data-placeholder fournit le texte du
placeholder et ne figure pas dans la liste des choix ; l'option placeholder passée à
enhanceSelect peut remplacer ce texte.
<div class="fui-combobox" id="command-combobox">
<label class="fui-field-label">Commande</label>
<select class="fui-combobox-native-select" name="command">
<option value="" data-placeholder>Rechercher une commande</option>
<option value="build">Build</option>
<option value="test">Test</option>
</select>
</div>import { enhanceCombobox } from 'faisceau-ui'
const combobox = enhanceCombobox(document.querySelector<HTMLDivElement>('#command-combobox')!, {
emptyLabel: 'Aucun résultat',
})La saisie, le trigger, la liste filtrable et l'état vide sont générés ; seuls le conteneur
.fui-combobox et son <select> natif sont requis. Les valeurs des options doivent être uniques.
Les options disabled et les <optgroup disabled> sont reconnues ; la seule l'option vide
portant data-placeholder est réservée au placeholder.
createCheckbox construit un contrôle relié à un véritable input[type="checkbox"], compatible avec FormData, required et le reset natif :
import { createCheckbox } from 'faisceau-ui'
createCheckbox({
label: 'Accepter les conditions',
name: 'terms',
required: true,
value: 'accepted',
}).mount(document.querySelector('#terms')!)Pour l'enhancement, le label, l'input natif et le contrôle visuel suffisent :
<label class="fui-checkbox" id="newsletter">
<input class="fui-checkbox-input" type="checkbox" name="newsletter" />
<span class="fui-field-label">Recevoir la newsletter</span>
</label>import { enhanceCheckbox } from 'faisceau-ui'
enhanceCheckbox(document.querySelector<HTMLLabelElement>('#newsletter')!, {})createCollapsible construit un disclosure accessible. enhanceCollapsible adopte une anatomie
existante composée de .fui-collapsible-trigger, .fui-collapsible-trigger-text,
.fui-collapsible-indicator et .fui-collapsible-content.
import { createCollapsible } from 'faisceau-ui'
createCollapsible({
trigger: 'Réglages avancés',
content: 'Options rarement utilisées',
defaultOpen: false,
}).mount(document.body)createTooltip génère un bouton et son infobulle accessible. enhanceTooltip peut utiliser le title d'un trigger existant ; l'attribut est temporairement retiré pour éviter la double infobulle puis restauré par destroy().
import { createTooltip, enhanceTooltip } from 'faisceau-ui'
createTooltip({ content: 'Créer un document', trigger: 'Créer' }).mount(document.body)
enhanceTooltip(document.querySelector<HTMLElement>('[title]')!)Dialog et Drawer acceptent le même modèle : la variante create* construit le panneau,
tandis que enhance* part d'un contenu existant portant la classe namespacée
fui-dialog-content ou fui-drawer-content.
Les triggers ne sont jamais possédés : chaque composant accepte un triggerSelector
dont tous les éléments correspondants ouvrent le panneau. Drawer utilise sa machine Zag dédiée :
il expose directement swipeDirection, les snap points, le grabber et une zone de swipe optionnelle.
import { createDialog, createDrawer, createToaster } from 'faisceau-ui'
createDialog({
triggerSelector: '#ouvrir-profil',
title: 'Profil',
content: 'Contenu',
}).mount(document.body)
createDrawer({
triggerSelector: '#ouvrir-filtres',
title: 'Filtres',
content: 'Contenu',
swipeDirection: 'end',
snapPoints: [0.5, 1],
swipeArea: true,
}).mount(document.body)
const toaster = createToaster({ placement: 'bottom-end' }).mount(document.body)
toaster.store.success({ title: 'Enregistré', description: 'Les changements sont conservés.' })Le thème clair est appliqué par défaut. Le thème sombre s'active sur la page entière ou sur un sous-arbre :
<html data-fui-theme="dark"></html>Les couleurs, rayons, dimensions et durées sont exposés sous forme de variables --fui-* et peuvent être redéfinis localement :
.my-form {
--fui-color-ring: oklch(0.62 0.19 255);
--fui-radius-md: 12px;
}Toutes les classes appartenant à la bibliothèque commencent par fui-. Les attributs d'état et d'accessibilité ajoutés par Zag restent disponibles pour des ajustements ciblés.
Les composants pilotés par une machine unique renvoient un contrôleur commun :
root: élément racine du composant ;api: valeur réactive Faisceau en lecture seule contenant l'API Zag courante, accessible aveccontroller.api.get();started: indique si la machine a été démarrée ;mount(target): ajoute un composant créé au DOM et le démarre ;start(): démarre un composant dont le DOM a été inséré manuellement ;destroy(): arrête les effets et écouteurs de façon idempotente.
destroy() retire le markup produit par une fonction create*. Pour une fonction enhance*, seuls les éléments générés sont retirés et le markup natif est restauré.
Le contrôleur Toast suit le même cycle de vie, mais expose store à la place de api afin de
créer, mettre à jour et fermer plusieurs notifications.
const select = createSelect({ label: 'Mode', items: ['Simple', 'Expert'] })
document.body.append(select.root)
select.start()
console.log(select.api.get().value)
select.destroy()Depuis la racine du monorepo :
# Installer et synchroniser le workspace Vite+
vp install
# Installer Chrome for Testing pour Vitest Browser (première utilisation)
vp exec playwright install chromium
# Formater, lint et vérifier les types
vp check
# Tester dans Chrome for Testing puis empaqueter toutes les bibliothèques
vp run -r test
vp run -r build
# Exécuter toute la validation, y compris les imports publics construits dans Chrome
vp run ready
# Lancer le site de démonstration
vp run devLes scripts build des bibliothèques utilisent vp pack, la commande Vite+ destinée aux packages
publiables. Chaque build vérifie le manifeste npm avec Publint. Le workflow de publication accepte
les tags faisceau-ui@<version> et faisceau-zag@<version> après avoir vérifié que package.json
et le tag déclarent la même version.