[FEATURE] Integrate country flag assets into library

[jacobg]

It looks like the latest version sources the phone number input country flags from flagcdn. For hybrid apps that may be running offline, the flags won't render. Is it possible to integrate flag assets into the build so they can be built and hosted locally in the native app?

Thanks!

[LouisMazel]

Hi @jacobg!

That’s a great idea!
I’m planning to offer multiple flag providers in the future (SVG, CDN, emoji) so that developers can choose the most suitable option for their use case, including fully local hosting.

I’ll be releasing v4 very soon, but this feature will likely come afterward, as it requires some work to ensure everything is handled properly and flags aren’t unnecessarily loaded.

In the meantime, you can already override the flags yourself by using the selector-flag and country-list-flag slots :

<MazPhoneNumberInput v-model="phone">
  <!-- Flag in the selector (main input) -->
  <template #selector-flag="{ codeCountry }">
    <img
      :src="`/local-flags/${codeCountry}.svg`"
      :alt="codeCountry"
      width="20"
      height="15"
    />
  </template>

  <!-- Flag in the country list dropdown -->
  <template #country-list-flag="{ option, countryCode, isSelected }">
    <img
      :src="`/local-flags/${countryCode}.svg`"
      :alt="option.name"
      width="20"
      height="15"
      class="{ '--is-selected': isSelected }"
    />
  </template>
</MazPhoneNumberInput>

Obviously, you can use SVG or something else.

Thanks again for the suggestion!

[jacobg]

Thanks so much @LouisMazel !

[LouisMazel]

🤖 [po]

PRD: Support des drapeaux locaux dans MazInputPhoneNumber et MazSelectCountry

Introduction

Les applications hybrides (Capacitor, Cordova) peuvent fonctionner hors ligne. Actuellement, les drapeaux de pays sont chargés depuis flagcdn.com, ce qui les rend indisponibles sans connexion réseau. Cette feature ajoute une prop local-flags sur MazSelectCountry et MazInputPhoneNumber pour utiliser les composants SVG déjà présents dans @maz-ui/icons (déjà dépendance de packages/lib) plutôt que le CDN externe. Le comportement CDN reste le défaut — aucune régression pour les utilisateurs existants.

Objectifs

• Permettre aux applications offline d'afficher les drapeaux sans requête réseau
• Ne rien casser pour les utilisateurs existants (CDN par défaut inchangé)
• Réutiliser les 256 assets SVG déjà présents dans @maz-ui/icons

User Stories

US-001: Prop local-flags sur MazSelectCountry

Description: En tant que développeur, je veux une prop local-flags sur MazSelectCountry afin que les drapeaux soient rendus depuis les assets SVG bundlés plutôt que depuis le CDN, pour un usage offline.

Critères d'acceptation :

• Prop localFlags: boolean (défaut false) ajoutée dans MazSelectCountryProps
• Quand localFlags=true, les drapeaux sont rendus via les composants LazyMazFlagXX de @maz-ui/icons à la place de MazLazyImg + URL CDN
• Quand localFlags=true et qu'aucun asset SVG local n'existe pour un code (ex : gb-eng, us-ak), le badge coloré existant est affiché — aucune requête vers flagcdn.com
• Quand localFlags=false (défaut), le comportement est strictement identique à l'implémentation actuelle
• Le drapeau du sélecteur ET les drapeaux de la liste respectent tous deux la prop
• Tests unitaires ajoutés/mis à jour dans MazSelectCountry.spec.ts
• typecheck:all passe
• lint passe

US-002: Propagation de local-flags dans MazInputPhoneNumber

Description: En tant que développeur, je veux pouvoir poser local-flags directement sur MazInputPhoneNumber afin qu'il soit transmis au MazSelectCountry interne.

Critères d'acceptation :

• Prop localFlags: boolean (défaut false) ajoutée dans MazInputPhoneNumberProps
• Prop liée via :local-flags="localFlags" dans le template sur <MazSelectCountry> (même pattern que :hide-flags existant)
• Tests unitaires ajoutés/mis à jour dans MazInputPhoneNumber.spec.ts
• typecheck:all passe
• lint passe

US-003: Mise à jour de la documentation

Description: En tant que développeur consultant la doc, je veux voir local-flags documentée sur les deux pages composants afin de savoir comment activer le support offline.

Critères d'acceptation :

• apps/docs/src/components/maz-select-country.md documente local-flags avec exemple d'usage
• apps/docs/src/components/maz-input-phone-number.md documente local-flags avec exemple d'usage
• Le cas d'usage offline (apps hybrides) est mentionné dans la description
• typecheck:all passe
• lint passe

Exigences fonctionnelles

• FR-1 : Quand local-flags=true, aucune requête réseau vers flagcdn.com ne doit être émise
• FR-2 : Quand local-flags=false (défaut), le comportement doit être strictement identique à l'implémentation actuelle
• FR-3 : Quand un code pays n'a pas d'asset SVG local (gb-eng, gb-sct, gb-wls, gb-nir, tous les codes us-* d'états), le badge coloré existant est affiché
• FR-4 : Le chargement des drapeaux reste lazy (le SVG n'est pas chargé tant que le composant <MazFlagXX> n'est pas rendu)

Hors périmètre

• Modification de getCountryFlagUrl dans @maz-ui/utils
• Ajout de nouveaux assets SVG pour gb-eng, gb-sct, gb-wls, gb-nir, ou les états US
• Support offline d'autres composants utilisant des ressources externes
• Option de configuration globale (niveau plugin) pour local-flags

Considérations techniques

• @maz-ui/icons est déjà une dépendance de packages/lib — aucune nouvelle dépendance à ajouter
• Les composants lazy sont exportés depuis @maz-ui/icons sous la forme LazyMazFlagXX (ex : LazyMazFlagFR, LazyMazFlagUS)
• Pattern d'import recommandé dans MazSelectCountry.vue :

  import * as MazIcons from '@maz-ui/icons'
  function getLocalFlagComponent(code: string) {
    const key = `LazyMazFlag${code.toUpperCase().replace('-', '')}`
    return (MazIcons as Record<string, unknown>)[key] ?? null // null → badge fallback
  }

• Les composants LazyMazFlagXX sont déjà markRaw(defineAsyncComponent(...)) — ne pas les wrapper dans un autre defineAsyncComponent
• Fichiers touchés : MazSelectCountry.vue, MazInputPhoneNumber.vue, leurs tests, et les deux pages de documentation

Métriques de succès

• Une application Capacitor/Cordova peut afficher les drapeaux dans MazInputPhoneNumber sans connexion réseau
• Aucune régression sur les tests existants de MazSelectCountry et MazInputPhoneNumber
• La taille du bundle n'augmente pas pour les utilisateurs en mode CDN par défaut (local-flags=false)