Utils Partagés
Objectif
Le package @sia-ui/utils rassemble les helpers transverses que tes applications recodent souvent: classes CSS, montants, dates, nombres et texte.
Philosophie
- API petite et prévisible
- dépendances minimales
- import global ou ciblé
- zéro logique métier trop spécifique
Imports
Import global:
import { cn, formatCurrency, formatDate, truncate } from "@sia-ui/utils";Import ciblé:
import { formatCurrency } from "@sia-ui/utils/currency";
import { formatDate } from "@sia-ui/utils/date";
import { truncate } from "@sia-ui/utils/string";Régler une fois : configureFormats
Sans réglage global, la langue, la devise et le fuseau se répètent à chaque appel, et chaque application finit par envelopper ces fonctions dans son propre config.ts. configureFormats se pose une fois, au démarrage :
import { configureFormats } from "@sia-ui/utils";
configureFormats({
locale: "fr-CM",
currency: "XAF",
timeZone: "Africa/Douala",
empty: "—", // une valeur absente ou invalide
minusSign: "unicode", // « − », le vrai signe moins ; "ascii" pour un export CSV
});
formatCurrency(-4500); // « −4 500 FCFA »
formatDate(facture.payeeLe); // « — » si elle manqueUne option passée à l'appel gagne toujours. Dans les composants, la langue d'un SiaProvider qui en reçoit une passe devant celle de configureFormats. Sans language sur le fournisseur, c'est le réglage global qui fait foi.
| Réglage | Défaut | Utilisé par |
|---|---|---|
locale | fr-FR | dates, nombres, montants, tri, recherche, listes, tailles de fichier |
currency | XAF | formatCurrency, AmountDisplay, CurrencyInput |
dateLocale | locale | la langue des dates seules : des montants en francs CFA à la française, des dates en anglais |
hour12 | l'usage de la langue | heure sur 12 (true, « 2:30 PM ») ou 24 heures (false, « 14:30 ») |
timeZone | celui du poste | formatDate, formatDateTime, formatDateRange |
empty | — | tous les formateurs, pour null, undefined, une date illisible, NaN |
minusSign | unicode | formatCurrency, formatAmount, formatNumber, formatPercent |
decimalSeparator | celui de la langue (, en français, . en anglais) | affichage et lecture des nombres et montants, InputNumber, CurrencyInput |
groupSeparator | celui de la langue (espace fine en français, , en anglais) | idem ; " ", "." ou "" possibles |
Le réglage est partagé entre tous les points d'entrée du paquet (@sia-ui/utils, @sia-ui/utils/date…), même en CommonJS où chacun embarque sa copie du module.
Le hook, côté React
@sia-ui/utils ne dépend de rien, pas même de React. Le hook vit dans @sia-ui/headless :
import { useFormat } from "@sia-ui/headless";
const f = useFormat();
<td>{f.formatCurrency(ligne.montant, { symbol: "short" })}</td>
<td>{f.formatDate(ligne.echeance)}</td>Il redessine le composant quand configureFormats change, et prend la langue du SiaProvider quand celui-ci en a une. Ses formateurs de dates suivent dateLocale, ses montants et nombres locale ; il en va de même pour les composants (useFormatLocale("date") dans les sélecteurs de dates, le calendrier, les métadonnées). Sans @sia-ui/headless, le même hook tient en une ligne :
const reglages = useSyncExternalStore(subscribeFormatDefaults, getFormatDefaults);Les séparateurs
Par défaut, ils suivent la langue : en français la virgule sépare les décimales et une espace fine les milliers, en anglais c'est le point et la virgule. Ils se règlent pour toute l'application ou à l'appel, et valent dans les deux sens : ce qui s'affiche se relit.
configureFormats({ decimalSeparator: ",", groupSeparator: " " });
formatNumber(1234567.5); // "1 234 567,5" — espace ordinaire
toNumber("1 234 567,5"); // 1234567.5
toNumber("1.234,5", 0, { decimalSeparator: ",", groupSeparator: "." }); // 1234.5
formatNumber(1234.5, { decimalSeparator: ".", groupSeparator: "" }); // "1234.5"À la lecture, trois règles rendent la saisie tolérante sans la rendre ambiguë :
- quand « . » et « , » sont tous deux présents, le dernier est le décimal : « 1,500.50 » et « 1.500,50 » valent 1500,5 quelle que soit la langue ;
- un point tapé sur un poste français (« 12.5 ») est lu comme décimal, sauf si le point est le séparateur de milliers réglé ;
- un texte qui contient des lettres n'est pas un nombre :
toNumber("12abc")rend la valeur de repli, il n'en extrait pas « 12 ».
numberSeparators() donne les séparateurs en vigueur et parseLocaleNumber() la lecture brute, pour un champ maison.
Les modules
classname
cn(...inputs)
But:
- normaliser la composition de classes dans tous les composants
currency
formatCurrencyformatAmountparseCurrencyminorToMajormajorToMinorgetCurrencySymbol
But:
- couvrir les écrans finance, paiement, caisse et reporting
Décision:
- base
Intl.NumberFormat, un formateur construit une seule fois par réglage - le vrai signe moins (−) par défaut ;
parseCurrencyrelit les deux signes symbol: "short"pour les colonnes de tableau : « 4 500 F » pour les francs CFA (XAF,XOF…), le symbole étroit ailleurs (« $12.00 ») ;getCurrencySymbol("XAF", locale, { short: true })donne « F »- devises sans décimales (
XAF,XOF,JPY…) arrondies à l'unité
date
parseDatediffInDaysformatDateformatDateTimeformatRelativeDateformatTimeAgoformatDateRangeaddDayssubDaysaddMonthssubMonthsaddYearssubYearsgetFirstDayOfMonthgetLastDayOfMonthisPastDatetoIsoDatetoDisplayDate
But:
- unifier le rendu des dates avant d'introduire des besoins plus avancés
Décision:
- base
Intl - pas de dépendance date externe
dateStyle: "medium"par défaut, sauf si l'appel demande des parties précises (day,month,hour…) : le navigateur refuse de mêler les deux, et le format demandé est rendu tel quelnull,undefinedou une date illisible donnent la valeur de repli (« — »), jamais le 1er janvier 1970
Exemples:
formatTimeAgo(createdAt, { prefix: "Créée" });
// "Créée il y a 10 minutes"
formatDate(echeance, { day: "2-digit", month: "2-digit" }); // "13/06"
formatDate(null); // "—"
formatDate(null, { fallback: "" }); // ""
formatTimeAgo(commande.creeeLe, { style: "short" }); // "il y a 3 h" au lieu de "il y a 3 heures"number
formatNumberformatPercentclamproundtoNumber— lit « 12,5 » en français, « 1,234.5 » en anglais, selon les séparateurs en vigueurparseDecimalroundCurrencyformatRatesafeDivide
string
truncatecapitalizetitleCaseinitialsslugifynormalizeIdentifiernormalizeSpacesmaskMiddleisBlank
maskMiddle cache un caractère par caractère masqué : la longueur du numéro se devine. maskLength fixe le nombre de caractères de masque, quelle que soit la longueur :
maskMiddle("+237699112233", { visibleStart: 4, visibleEnd: 2, maskLength: 4, maskChar: "•" });
// "+237••••33"Règles d'évolution
- ajouter un utilitaire seulement s'il répond à un besoin répété;
- préférer les sous-modules stables à un gros fichier fourre-tout;
- documenter et tester chaque nouveau domaine.