dsfr-postale

Autocomplétion d'adresse postale

À propos

Ce composant Vue 3 interroge l'API Géocodage de la Géoplateforme (IGN), qui s'appuie sur la Base Adresse Nationale, pour auto-compléter un champ et restituer l'adresse postale choisie.

Il est destiné à s'intégrer au sein de l'écosystème du système de design de l'État (DSFR).

Accéder à la démonstration

Mise en œuvre

Installation

npm i dsfr-postale

Vue 3.5 ou plus récent est requis (dépendance de pair). Pour une mise à jour depuis la version 1, consultez le journal des modifications.

Le DSFR doit être chargé par l'application hôte. Importez aussi la feuille de style du composant :

import 'dsfr-postale/style.css'

Utilisation

<script setup lang="ts">
import { ref } from 'vue'
import DsfrPostale, { type SelectedAddress } from 'dsfr-postale'

// Repasse à null dès que l'usager modifie le texte après son choix.
const adresse = ref<SelectedAddress | null>(null)
</script>

<template>
  <DsfrPostale v-model:address="adresse" label="Adresse postale" />
</template>

Propriétés

Liaisons (v-model)

Événements

Textes

La prop messages accepte listboxLabel (nom de la liste), results (fonction recevant le nombre de suggestions), noResults et serviceError :

<DsfrPostale :messages="{ noResults: 'Aucune adresse ne correspond.' }" />

Les types SelectedAddress, AddressType et DsfrPostaleMessages sont exportés par le paquet.

SelectedAddress contient label, housenumber, street, postcode, city, citycode (code INSEE), lat et lng.

Comportement réseau

Les réponses récentes sont gardées en mémoire (20 requêtes) : effacer des caractères ne rappelle pas l'API. La connexion à l'API est préparée au premier focus du champ. Si l'API ne répond pas dans le délai timeout, ou renvoie une erreur, un message informe l'usager qu'il peut saisir l'adresse manuellement ; le champ n'est pas marqué invalide pour autant.

Politique de sécurité du contenu

Si votre application définit une CSP, autorisez l'API : connect-src https://data.geopf.fr.

Accessibilité

Le composant met en œuvre le motif ARIA « combobox » (liste de suggestions) : navigation au clavier (flèches, Entrée, Échap, Tab), identifiants uniques, nombre de résultats restitué aux technologies d'assistance, message d'erreur relié au champ, partie saisie mise en évidence dans chaque suggestion. Chaque état du composant (liste fermée, ouverte, erreur) est audité par axe-core dans les tests, et la démonstration par pa11y (axe et HTML_CodeSniffer) dans la CI, liste fermée puis ouverte, en thèmes clair et sombre (?scheme=dark force le thème de la démonstration). Ces contrôles automatiques ne remplacent pas un audit RGAA.

Développement

npm install
npm run dev          # démonstration locale, sur les sources
npm run typecheck    # vérification des types
npm test             # tests unitaires, rendu serveur et accessibilité (axe-core)
npm run test:coverage  # idem, avec seuils de couverture
npm run test:umd     # chargement du build UMD sans outil de build (après npm run build)
npm run build        # paquet npm (dist/)
npm run build:demo   # démonstration (dist-demo/), déployée sur GitHub Pages par la CI
npm run preview      # aperçu de la démonstration construite (http://127.0.0.1:4173/dsfr-postale/)
npm run check        # toutes les vérifications, comme avant une publication

Publication

La publication est automatisée (.github/workflows/publish.yml) par Trusted Publishing : aucun jeton npm n'est stocké dans le dépôt, et chaque version est accompagnée d'une attestation de provenance.

Au fil des modifications, décrivez-les dans la section ## [Non publiée] en tête de CHANGELOG.md. Pour publier, une seule commande, dépôt à jour et sans modification en attente :

npm version minor   # patch pour une correction, major pour un changement cassant

Elle vérifie que la section « Non publiée » est remplie et rejoue toutes les vérifications (npm run check), puis met à jour le numéro de version, renomme la section avec ce numéro et la date du jour, crée le commit « Version x.y.z » et son tag, et pousse le tout. Le tag déclenche la publication sur npm, puis la création de la release GitHub avec la section correspondante du journal.

La publication échoue si le tag ne correspond pas à la version du package.json ou si le journal n'a pas de section datée pour cette version, et ne fait rien si la version existe déjà sur npm.

Données personnelles

Le texte saisi est transmis à l'API Géocodage de l'IGN pour obtenir les suggestions. Si l'adresse est celle de l'usager, mentionnez ce transfert dans l'information prévue par le RGPD (article 13) de votre service.

Source des données

Base Adresse Nationale (BAN), via l'API Géocodage de la Géoplateforme. Le service est public et sans clé, mais soumis à une limite de requêtes : gardez la temporisation (debounce) activée.

Licence

MIT