Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Faisceau UI

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.

Architecture

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-ui sur 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.

Installation

pnpm add faisceau-ui

Importer 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 faisceau

Le 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.

Créer un Select

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.

Créer une Combobox

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')!)

Sélection multiple

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).

Formulaires HTML natifs

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'))
})

Améliorer un markup existant

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.

Select existant

<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.

Combobox existante

<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.

Checkbox

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')!, {})

Collapsible

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)

Tooltip

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, Drawer et Toast

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.' })

Thèmes et personnalisation

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.

Cycle de vie

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 avec controller.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()

Développement

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 dev

Les 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.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages