@cyrilld/zestds 0.1.0

package/dist/flags.d.cts

@@ -0,0 +1,151 @@
+import * as react from 'react';
+import { SVGProps } from 'react';
+
+/**
+ * Le catalogue des drapeaux — LA source unique.
+ *
+ * ⚠️  GÉNÉRÉ depuis le Figma de Zest, cadre « Country icons » (`3853:17761`).
+ * Ne pas corriger à la main : corriger le Figma, puis régénérer. Une retouche
+ * locale serait écrasée sans laisser de trace.
+ *
+ * 234 drapeaux, tous en pastille ronde de 24, tous autonomes — un dessin par
+ * symbole, aucune composition.
+ *
+ * ------------------------------------------------------------------------
+ * LES COULEURS NE SONT PAS PORTÉES SUR LES JETONS
+ * ------------------------------------------------------------------------
+ * Le bleu du drapeau français est `#0052B4` et le restera. Les couleurs d'un
+ * drapeau ne sont pas une décision de Zest : ce sont des faits nationaux, et
+ * les rapprocher de la palette de marque produirait des drapeaux faux. C'est
+ * l'inverse exact de la règle des icônes de type de fichier, où la couleur
+ * catégorise et doit donc suivre le thème.
+ *
+ * Conséquence à connaître : un drapeau ne suit PAS la couleur du texte, et ne
+ * répond pas au thème.
+ *
+ * ------------------------------------------------------------------------
+ * UNE SEULE FORME : LA PASTILLE RONDE
+ * ------------------------------------------------------------------------
+ * Le rond est découpé dans les tracés eux-mêmes, pas par un masque : chaque
+ * SVG est complet et se copie tel quel. Il n'y a ni rectangle bordé ni carré —
+ * la question était ouverte, le Figma l'a tranchée en ne dessinant que le rond.
+ *
+ * ------------------------------------------------------------------------
+ * CINQ CODES DU FIGMA SONT FAUX, ET ILS SONT CORRIGÉS ICI
+ * ------------------------------------------------------------------------
+ * Relevé en regardant les dessins, pas en lisant les noms. Le dessin fait foi :
+ * un jeu de drapeaux se consulte par code, et une étiquette fausse rend le
+ * drapeau introuvable — un sélecteur de pays n'aurait jamais rendu le Soudan.
+ *
+ *     DS      → SD        le dessin est le Soudan. `SD` était absent du jeu,
+ *                         et `DS` n'est pas un code ISO : une transposition.
+ *     CD (×2) → CG        deux symboles portaient `CD` avec DEUX dessins
+ *                         différents. L'un est bien le Congo-Kinshasa, l'autre
+ *                         est le Congo-Brazzaville. `CG` était absent du jeu.
+ *     GB-2    → GB-ENG    le dessin est l'Angleterre. Son code ISO 3166-2.
+ *     BQ (×3) → BQ-BO     Bonaire
+ *               BQ-SE     Saint-Eustache
+ *               BQ-SA     Saba
+ *
+ * ⚠️  `BQ` ×3 N'EST PAS UNE ERREUR DU FIGMA, contrairement aux trois autres.
+ * `BQ` désigne les Pays-Bas caribéens, qui sont trois îles, chacune avec son
+ * drapeau : un code pour trois dessins. Le jeu les distingue par leur code de
+ * subdivision, et `FLAG_ALIAS` renvoie `BQ` sur Bonaire, la plus peuplée, pour
+ * qu'une recherche par alpha-2 ne tombe pas dans le vide.
+ *
+ * Chaque entrée corrigée garde `codeFigma`, le code tel que le Figma l'écrit,
+ * pour que l'écart reste trouvable au lieu d'être lissé. Le Figma reste à
+ * corriger — voir « En attente » dans le README.
+ *
+ * ------------------------------------------------------------------------
+ * CE QUI MANQUE
+ * ------------------------------------------------------------------------
+ * 19 codes ISO 3166-1 alpha-2 n'ont pas de dessin. Pour l'essentiel des
+ * territoires : AQ Antarctique, BV Île Bouvet, CI Côte d'Ivoire, CV Cap-Vert,
+ * GF Guyane française, GP Guadeloupe, GS Géorgie du Sud, HM Îles Heard, MF
+ * Saint-Martin, NC Nouvelle-Calédonie, PM Saint-Pierre-et-Miquelon, RE La
+ * Réunion, SH Sainte-Hélène, SJ Svalbard, TF Terres australes françaises, UM
+ * Îles mineures des États-Unis, VA Vatican, WF Wallis-et-Futuna, YT Mayotte.
+ *
+ * ⚠️  CINQ SONT DES DÉPARTEMENTS ET COLLECTIVITÉS FRANÇAIS — Guadeloupe, La
+ * Réunion, Mayotte, Guyane, Saint-Pierre-et-Miquelon. Sur un produit français,
+ * c'est le trou qui se remarquera en premier. À relever au Figma.
+ *
+ * ------------------------------------------------------------------------
+ * LE POIDS, ET LE POINT D'ENTRÉE
+ * ------------------------------------------------------------------------
+ * 317 Ko une fois nettoyés, contre 197 Ko pour tout le reste du paquet. Un
+ * catalogue est un objet de données : aucun secouage d'arbre ne retire les 233
+ * drapeaux qu'un écran n'affiche pas. Ils sont donc derrière un point d'entrée
+ * séparé, `@cyrilld/zestds/flags`, que seul un consommateur qui en veut paie.
+ *
+ * Les noms français viennent de `Intl.DisplayNames`, pas d'une liste recopiée :
+ * une liste se périme, l'ICU du navigateur non.
+ */
+interface ZestFlag {
+    /** Le code. ISO 3166-1 alpha-2 en général, 3166-2 pour les subdivisions, `earth` pour le globe. */
+    code: string;
+    /** Le nom, en français. */
+    nom: string;
+    /** Le code que le Figma écrit, QUAND IL DIFFÈRE. Voir l'en-tête. */
+    codeFigma?: string;
+    /** Le contenu du `<svg>`, boîte de 24, pastille ronde. */
+    svg: string;
+}
+/** Les 234 drapeaux, triés par nom français. */
+declare const ZEST_FLAGS: ZestFlag[];
+/**
+ * Les codes qui n'ont pas leur propre dessin et vers quoi les renvoyer.
+ *
+ * `BQ` est un vrai code — les Pays-Bas caribéens — mais le jeu dessine les
+ * trois îles séparément. Un sélecteur qui interroge `BQ` doit rendre quelque
+ * chose plutôt qu'un trou.
+ */
+declare const FLAG_ALIAS: Record<string, string>;
+/** Un drapeau par son code, insensible à la casse, alias compris. */
+declare const findFlag: (code: string) => ZestFlag | undefined;
+
+/**
+ * Les drapeaux, en composant.
+ *
+ * ⚠️  UN SEUL COMPOSANT, PAS 234. Les 121 icônes du design system ont chacune
+ * la leur parce qu'un écran les cite par leur nom, à l'écriture. Un drapeau se
+ * choisit À L'EXÉCUTION — depuis la langue du navigateur, le pays d'une
+ * adresse, une liste d'indicatifs téléphoniques. `<FlagIcon code={pays} />` le
+ * fait ; 234 exports nommés ne serviraient à personne et pèseraient dans
+ * l'autocomplétion de tout le monde.
+ */
+interface FlagIconProps extends Omit<SVGProps<SVGSVGElement>, "code"> {
+    /** Le code du pays. Insensible à la casse, alias compris. Ex. `FR`, `bq`, `GB-ENG`. */
+    code: string;
+    /** Le diamètre, en pixels. 24 est la taille de dessin. */
+    size?: number;
+    /**
+     * Le nom à annoncer, s'il doit l'être.
+     *
+     * Par défaut le drapeau est décoratif : `aria-hidden`. Voir plus bas.
+     */
+    titre?: string;
+}
+/**
+ * Un drapeau, en pastille ronde.
+ *
+ * ⚠️  IL EST DÉCORATIF PAR DÉFAUT, et c'est le cas courant : dans un sélecteur
+ * de pays, dans une liste d'indicatifs, à côté d'une langue, le nom est écrit
+ * juste à côté. L'annoncer ferait entendre « France » deux fois.
+ *
+ * ⚠️  ET UN DRAPEAU N'EST PAS UNE LANGUE. Un drapeau seul, sans texte, pour
+ * dire « anglais » ou « espagnol », désigne un pays et pas une langue — il y a
+ * plus d'hispanophones au Mexique qu'en Espagne. Quand le drapeau est la SEULE
+ * indication, passer `titre` pour qu'il porte un nom accessible ; mais la vraie
+ * réponse est presque toujours d'écrire le nom à côté.
+ *
+ * ⚠️  IL NE RÉPOND PAS AU THÈME. Les couleurs d'un drapeau sont des faits
+ * nationaux, pas des jetons — voir l'en-tête du catalogue.
+ */
+declare const FlagIcon: {
+    ({ code, size, titre, ...props }: FlagIconProps): react.JSX.Element | null;
+    displayName: string;
+};
+
+export { FLAG_ALIAS, FlagIcon, type FlagIconProps, ZEST_FLAGS, type ZestFlag as ZestDrapeau, type ZestFlag, findFlag };

package/dist/flags.d.ts

@@ -0,0 +1,151 @@
+import * as react from 'react';
+import { SVGProps } from 'react';
+
+/**
+ * Le catalogue des drapeaux — LA source unique.
+ *
+ * ⚠️  GÉNÉRÉ depuis le Figma de Zest, cadre « Country icons » (`3853:17761`).
+ * Ne pas corriger à la main : corriger le Figma, puis régénérer. Une retouche
+ * locale serait écrasée sans laisser de trace.
+ *
+ * 234 drapeaux, tous en pastille ronde de 24, tous autonomes — un dessin par
+ * symbole, aucune composition.
+ *
+ * ------------------------------------------------------------------------
+ * LES COULEURS NE SONT PAS PORTÉES SUR LES JETONS
+ * ------------------------------------------------------------------------
+ * Le bleu du drapeau français est `#0052B4` et le restera. Les couleurs d'un
+ * drapeau ne sont pas une décision de Zest : ce sont des faits nationaux, et
+ * les rapprocher de la palette de marque produirait des drapeaux faux. C'est
+ * l'inverse exact de la règle des icônes de type de fichier, où la couleur
+ * catégorise et doit donc suivre le thème.
+ *
+ * Conséquence à connaître : un drapeau ne suit PAS la couleur du texte, et ne
+ * répond pas au thème.
+ *
+ * ------------------------------------------------------------------------
+ * UNE SEULE FORME : LA PASTILLE RONDE
+ * ------------------------------------------------------------------------
+ * Le rond est découpé dans les tracés eux-mêmes, pas par un masque : chaque
+ * SVG est complet et se copie tel quel. Il n'y a ni rectangle bordé ni carré —
+ * la question était ouverte, le Figma l'a tranchée en ne dessinant que le rond.
+ *
+ * ------------------------------------------------------------------------
+ * CINQ CODES DU FIGMA SONT FAUX, ET ILS SONT CORRIGÉS ICI
+ * ------------------------------------------------------------------------
+ * Relevé en regardant les dessins, pas en lisant les noms. Le dessin fait foi :
+ * un jeu de drapeaux se consulte par code, et une étiquette fausse rend le
+ * drapeau introuvable — un sélecteur de pays n'aurait jamais rendu le Soudan.
+ *
+ *     DS      → SD        le dessin est le Soudan. `SD` était absent du jeu,
+ *                         et `DS` n'est pas un code ISO : une transposition.
+ *     CD (×2) → CG        deux symboles portaient `CD` avec DEUX dessins
+ *                         différents. L'un est bien le Congo-Kinshasa, l'autre
+ *                         est le Congo-Brazzaville. `CG` était absent du jeu.
+ *     GB-2    → GB-ENG    le dessin est l'Angleterre. Son code ISO 3166-2.
+ *     BQ (×3) → BQ-BO     Bonaire
+ *               BQ-SE     Saint-Eustache
+ *               BQ-SA     Saba
+ *
+ * ⚠️  `BQ` ×3 N'EST PAS UNE ERREUR DU FIGMA, contrairement aux trois autres.
+ * `BQ` désigne les Pays-Bas caribéens, qui sont trois îles, chacune avec son
+ * drapeau : un code pour trois dessins. Le jeu les distingue par leur code de
+ * subdivision, et `FLAG_ALIAS` renvoie `BQ` sur Bonaire, la plus peuplée, pour
+ * qu'une recherche par alpha-2 ne tombe pas dans le vide.
+ *
+ * Chaque entrée corrigée garde `codeFigma`, le code tel que le Figma l'écrit,
+ * pour que l'écart reste trouvable au lieu d'être lissé. Le Figma reste à
+ * corriger — voir « En attente » dans le README.
+ *
+ * ------------------------------------------------------------------------
+ * CE QUI MANQUE
+ * ------------------------------------------------------------------------
+ * 19 codes ISO 3166-1 alpha-2 n'ont pas de dessin. Pour l'essentiel des
+ * territoires : AQ Antarctique, BV Île Bouvet, CI Côte d'Ivoire, CV Cap-Vert,
+ * GF Guyane française, GP Guadeloupe, GS Géorgie du Sud, HM Îles Heard, MF
+ * Saint-Martin, NC Nouvelle-Calédonie, PM Saint-Pierre-et-Miquelon, RE La
+ * Réunion, SH Sainte-Hélène, SJ Svalbard, TF Terres australes françaises, UM
+ * Îles mineures des États-Unis, VA Vatican, WF Wallis-et-Futuna, YT Mayotte.
+ *
+ * ⚠️  CINQ SONT DES DÉPARTEMENTS ET COLLECTIVITÉS FRANÇAIS — Guadeloupe, La
+ * Réunion, Mayotte, Guyane, Saint-Pierre-et-Miquelon. Sur un produit français,
+ * c'est le trou qui se remarquera en premier. À relever au Figma.
+ *
+ * ------------------------------------------------------------------------
+ * LE POIDS, ET LE POINT D'ENTRÉE
+ * ------------------------------------------------------------------------
+ * 317 Ko une fois nettoyés, contre 197 Ko pour tout le reste du paquet. Un
+ * catalogue est un objet de données : aucun secouage d'arbre ne retire les 233
+ * drapeaux qu'un écran n'affiche pas. Ils sont donc derrière un point d'entrée
+ * séparé, `@cyrilld/zestds/flags`, que seul un consommateur qui en veut paie.
+ *
+ * Les noms français viennent de `Intl.DisplayNames`, pas d'une liste recopiée :
+ * une liste se périme, l'ICU du navigateur non.
+ */
+interface ZestFlag {
+    /** Le code. ISO 3166-1 alpha-2 en général, 3166-2 pour les subdivisions, `earth` pour le globe. */
+    code: string;
+    /** Le nom, en français. */
+    nom: string;
+    /** Le code que le Figma écrit, QUAND IL DIFFÈRE. Voir l'en-tête. */
+    codeFigma?: string;
+    /** Le contenu du `<svg>`, boîte de 24, pastille ronde. */
+    svg: string;
+}
+/** Les 234 drapeaux, triés par nom français. */
+declare const ZEST_FLAGS: ZestFlag[];
+/**
+ * Les codes qui n'ont pas leur propre dessin et vers quoi les renvoyer.
+ *
+ * `BQ` est un vrai code — les Pays-Bas caribéens — mais le jeu dessine les
+ * trois îles séparément. Un sélecteur qui interroge `BQ` doit rendre quelque
+ * chose plutôt qu'un trou.
+ */
+declare const FLAG_ALIAS: Record<string, string>;
+/** Un drapeau par son code, insensible à la casse, alias compris. */
+declare const findFlag: (code: string) => ZestFlag | undefined;
+
+/**
+ * Les drapeaux, en composant.
+ *
+ * ⚠️  UN SEUL COMPOSANT, PAS 234. Les 121 icônes du design system ont chacune
+ * la leur parce qu'un écran les cite par leur nom, à l'écriture. Un drapeau se
+ * choisit À L'EXÉCUTION — depuis la langue du navigateur, le pays d'une
+ * adresse, une liste d'indicatifs téléphoniques. `<FlagIcon code={pays} />` le
+ * fait ; 234 exports nommés ne serviraient à personne et pèseraient dans
+ * l'autocomplétion de tout le monde.
+ */
+interface FlagIconProps extends Omit<SVGProps<SVGSVGElement>, "code"> {
+    /** Le code du pays. Insensible à la casse, alias compris. Ex. `FR`, `bq`, `GB-ENG`. */
+    code: string;
+    /** Le diamètre, en pixels. 24 est la taille de dessin. */
+    size?: number;
+    /**
+     * Le nom à annoncer, s'il doit l'être.
+     *
+     * Par défaut le drapeau est décoratif : `aria-hidden`. Voir plus bas.
+     */
+    titre?: string;
+}
+/**
+ * Un drapeau, en pastille ronde.
+ *
+ * ⚠️  IL EST DÉCORATIF PAR DÉFAUT, et c'est le cas courant : dans un sélecteur
+ * de pays, dans une liste d'indicatifs, à côté d'une langue, le nom est écrit
+ * juste à côté. L'annoncer ferait entendre « France » deux fois.
+ *
+ * ⚠️  ET UN DRAPEAU N'EST PAS UNE LANGUE. Un drapeau seul, sans texte, pour
+ * dire « anglais » ou « espagnol », désigne un pays et pas une langue — il y a
+ * plus d'hispanophones au Mexique qu'en Espagne. Quand le drapeau est la SEULE
+ * indication, passer `titre` pour qu'il porte un nom accessible ; mais la vraie
+ * réponse est presque toujours d'écrire le nom à côté.
+ *
+ * ⚠️  IL NE RÉPOND PAS AU THÈME. Les couleurs d'un drapeau sont des faits
+ * nationaux, pas des jetons — voir l'en-tête du catalogue.
+ */
+declare const FlagIcon: {
+    ({ code, size, titre, ...props }: FlagIconProps): react.JSX.Element | null;
+    displayName: string;
+};
+
+export { FLAG_ALIAS, FlagIcon, type FlagIconProps, ZEST_FLAGS, type ZestFlag as ZestDrapeau, type ZestFlag, findFlag };