Skip to content

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:

ts
import { cn, formatCurrency, formatDate, truncate } from "@sia-ui/utils";

Import ciblé:

ts
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 :

ts
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 manque

Une 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églageDéfautUtilisé par
localefr-FRdates, nombres, montants, tri, recherche, listes, tailles de fichier
currencyXAFformatCurrency, AmountDisplay, CurrencyInput
dateLocalelocalela langue des dates seules : des montants en francs CFA à la française, des dates en anglais
hour12l'usage de la langueheure sur 12 (true, « 2:30 PM ») ou 24 heures (false, « 14:30 »)
timeZonecelui du posteformatDate, formatDateTime, formatDateRange
empty—tous les formateurs, pour null, undefined, une date illisible, NaN
minusSignunicodeformatCurrency, formatAmount, formatNumber, formatPercent
decimalSeparatorcelui de la langue (, en français, . en anglais)affichage et lecture des nombres et montants, InputNumber, CurrencyInput
groupSeparatorcelui 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 :

tsx
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 :

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

ts
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 ​

  • formatCurrency
  • formatAmount
  • parseCurrency
  • minorToMajor
  • majorToMinor
  • getCurrencySymbol

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 ; parseCurrency relit 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 ​

  • parseDate
  • diffInDays
  • formatDate
  • formatDateTime
  • formatRelativeDate
  • formatTimeAgo
  • formatDateRange
  • addDays
  • subDays
  • addMonths
  • subMonths
  • addYears
  • subYears
  • getFirstDayOfMonth
  • getLastDayOfMonth
  • isPastDate
  • toIsoDate
  • toDisplayDate

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 quel
  • null, undefined ou une date illisible donnent la valeur de repli (« — »), jamais le 1er janvier 1970

Exemples:

ts
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 ​

  • formatNumber
  • formatPercent
  • clamp
  • round
  • toNumber — lit « 12,5 » en français, « 1,234.5 » en anglais, selon les séparateurs en vigueur
  • parseDecimal
  • roundCurrency
  • formatRate
  • safeDivide

string ​

  • truncate
  • capitalize
  • titleCase
  • initials
  • slugify
  • normalizeIdentifier
  • normalizeSpaces
  • maskMiddle
  • isBlank

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 :

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

Publié sous licence MIT.