Composant invisible de connexion aux données. Récupère des données depuis une API REST (URL brute ou via un adapter specialise) et les distribue aux autres composants via le système d'événements. Supporte aussi les données JSON inline.

Modes de fonctionnement

Le composant supporte trois modes :

Types d'adapter

En mode adapter, l'attribut api-type sélectionne le provider :

Attributs

Attributs communs

Attributs mode URL brute

Attributs mode adapter

Relever le plafond de lignes : max-records

En mode adaptateur, le chargement complet s'arrête à un plafond de sécurité : 1 000 lignes sur Opendatasoft, 25 000 sur Tabular (125 pages de 200). max-records le relève explicitement, et vaut pour les deux adaptateurs : Opendatasoft (#233) et Tabular (#1027). Sur Tabular, une carte de toutes les communes (environ 35 000 lignes) demande max-records="40000", soit jusqu'à 200 requêtes de 200 lignes : c'est le prix à peser, en requêtes comme en mémoire. Un limit plus petit reste prioritaire.

<dsfr-data-source id="communes"
  api-type="tabular"
  resource="…"
  max-records="40000">
</dsfr-data-source>

Quand le plafond coupe le jeu, la troncature n'est pas muette : la source la signale (truncated, lisible dans le volet Diagnostic) et un avertissement console cite max-records comme moyen de la lever. C'est vrai aussi sur un group-by délégué, dont l'API ne donne pas le total : une page pleine au plafond avec une page suivante annoncée suffit à la signaler. Les autres adaptateurs (Grist, INSEE Melodi) ignorent l'attribut.

Au-delà d'une page : la source pagine sur un ordre total

Une API qui pagine par décalage ne rend chaque ligne une seule fois que si l'ordre est le même d'une page à l'autre. Sinon des lignes reviennent deux fois, d'autres jamais, et le nombre de lignes reste juste : rien ne le signale, et un sous-total, un cumul ou un historique sont faux. La source s'en charge, sans rien à écrire dans la page (#1202, #1233, #1274).

Sur Opendatasoft, l'API ne garantit aucun ordre sans tri : le défaut touche aussi une source sans order-by, et pas à chaque chargement (mesuré sur un jeu de 321 lignes : 297 distinctes dix fois sur dix un jour, 321 cinq fois sur cinq un autre). Conséquence visible : sans order-by, les lignes d'un jeu de plus de 100 lignes arrivent triées sur les colonnes du jeu, dans l'ordre de ses champs, et non plus dans l'ordre de l'API. Pour un autre ordre, poser order-by ; un cumul calculé en aval sans tri suit l'ordre livré.

Les colonnes retenues sont celles que l'API sait trier (texte, nombre, date, booléen), lues une fois dans les métadonnées du jeu ; pour des groupes triés, ce sont les autres clés du group-by. Sur un jeu de plus d'un million de lignes sans where, ce tri allonge la première réponse de quelques secondes. Si l'API refuse la clé de départage, la source charge comme avant et le volet Diagnostic le signale (« pagination sans ordre garanti » sur Opendatasoft, « tri serveur instable » sur Tabular) : poser alors un order-by sur une colonne unique, ou charger en une requête avec fetch-mode="export".

Grist. Un chargement complet tient en une requête : rien à paginer. En server-side, l'API /records ne sait pas sauter de lignes — son paramètre offset est ignoré, sans erreur. La source demande donc la page N par limit = N × page-size et n'en garde que la dernière tranche : chaque page est juste, et la page N coûte N pages de transfert. Un order-by paginé est complété par l'identifiant de ligne de Grist (id), pour que les ex-æquo ne changent pas de page. Avec un where à opérateur avancé, un group-by ou un aggregate, la requête passe par l'endpoint SQL du document, paginé sur le même ordre total.

INSEE Melodi. Au-delà de 1 000 observations, la source pagine par numéro de page, et l'API n'offre aucun paramètre de tri. L'ordre de ses observations a été mesuré stable d'une page à l'autre ; rien ne le garantit, et la source ne peut pas l'imposer. Elle vérifie donc, une fois toutes les pages reçues, qu'aucune observation n'est revenue deux fois — une observation s'identifie par ses dimensions. Si c'est le cas, le volet Diagnostic affiche « lignes revenues d'une page à l'autre » : autant d'observations manquent, alors que le compte reste juste. Resserrer le where pour que le chargement tienne en une page, ou recharger.

Tout charger en un seul appel : fetch-mode

En mode adaptateur, la source pagine par tranches de 100 lignes. Pour une page « un fetch, N agrégations client », c'est autant d'allers-retours ; et sur un group-by à beaucoup de groupes, le portail ne rend qu'une page de groupes. fetch-mode="export" passe par l'endpoint d'export du portail, qui rend tout d'un coup, avec les mêmes clauses (select, where, group-by, order-by).

<dsfr-data-source id="src"
  api-type="opendatasoft"
  base-url="https://data.economie.gouv.fr"
  dataset-id="mon-jeu"
  fetch-mode="export"
  max-records="20000">
</dsfr-data-source>

Implémenté par les adaptateurs OpenDataSoft et Tabular ; les autres l'ignorent, et une source dont le portail n'expose pas d'endpoint d'export retombe une fois sur le chargement paginé, avec un avertissement console. À ne pas combiner avec server-side, qui pagine page par page et reste sur l'endpoint paginé : la contradiction est signalée dans la console. Sur OpenDataSoft, le total serveur est inconnu en mode export, donc la troncature est détectée en demandant une ligne de plus que le plafond max-records — pensez à relever ce plafond en même temps.

Tabular : l'export Parquet de data.gouv (#1055)

Sur une source api-type="tabular", fetch-mode="export" lit l'export Parquet que data.gouv publie pour chaque ressource, par plages, en ne lisant que les colonnes du select. Mesuré sur le jeu IRVE (223 174 lignes) : le jeu entier en 0,66 s et 17 requêtes, là où la pagination met 10,8 s et 125 requêtes pour 25 000 lignes. Le lecteur (≈ 22 Ko gzip) n'est chargé qu'à ce moment-là : il n'alourdit pas les autres pages.

• Lignes brutes seulement. Avec un where, un group-by, un aggregate ou un order-by délégué — posé sur la source ou transmis par une dsfr-data-query —, la source reste sur la pagination, qui les exécute côté serveur, et le dit une fois en console. Pour « un fetch, N agrégations », posez les calculs sur des dsfr-data-query qui partagent la source : ils restent alors côté client.
• max-records (25 000 par défaut, comme la pagination) borne les lignes lues. Le fichier annonce son nombre de lignes : le total est connu, et une troncature se dit comme en pagination.
• Forme des lignes identique à celle de l'API : entiers en nombres, dates en AAAA-MM-JJ, colonne __id quand aucun select n'est posé. Une ressource sans export retombe sur la pagination, avec un avertissement.
• Pour la première page d'un petit jeu, la pagination reste plus rapide ; l'export l'emporte au-delà de 1 000 à 2 000 lignes.

<dsfr-data-source id="bornes"
  api-type="tabular"
  resource="eb76d20a-8501-400e-b336-d85724de5435"
  select="nom_station, consolidated_latitude, consolidated_longitude"
  fetch-mode="export"
  max-records="250000">
</dsfr-data-source>

Attribut mode inline

Ne rien charger avant le premier filtre

Sans précaution, une source interroge son API dès le montage et rapatrie le jeu entier — une requête coûteuse dont personne ne regarde le résultat sur une page d'exploration, où l'utilisateur va de toute façon commencer par choisir une commune, une année, un thème. require-where retarde le premier appel jusqu'à ce filtre.

<dsfr-data-source id="src" api-type="opendatasoft" require-where
  base-url="https://data.economie.gouv.fr" dataset-id="equipements">
</dsfr-data-source>

<dsfr-data-facets source="src" fields="commune"></dsfr-data-facets>

<dsfr-data-list source="src"
  idle-message="Choisissez une commune pour afficher ses équipements">
</dsfr-data-list>

Ce qui compte comme filtre : les clauses reçues par commande — facettes, recherche, dsfr-data-context, délégation d'un dsfr-data-query. Le where STATIQUE de la source ne compte pas : il fait partie de la définition du jeu, pas du geste de l'utilisateur — le contraire rendrait l'attribut sans effet sur toute source qui restreint déjà son périmètre. Quand le dernier filtre est retiré, la source repasse en attente : jamais de requête « tout » implicite. Sans effet en mode data inline, qui ne fait aucune requête.

Pendant l'attente, la source publie dsfr-data-idle plutôt que des données vides. Les afficheurs en aval (list, display, kpi, chart, podium, search, a11y) rendent alors leur idle-message — « Choisissez un filtre pour afficher les données » par défaut — et non « aucune donnée », qui annoncerait une requête revenue vide. Un pendant purement client existe sur dsfr-data-query.

Pages à onglets : ne charger que ce qu'on regarde

Une page à onglets déclare ses sources pour tous les panneaux ; cinq sur six sont fermés à l'arrivée, et pourtant toutes les requêtes partent au chargement. Avec lazy, la première requête attend qu'un consommateur de la source entre dans une marge de 200 px autour du viewport. Un panneau fermé est en display:none : il n'a pas de boîte, il n'intersecte jamais, et l'observateur se déclenche à l'ouverture de l'onglet.

<!-- Les sources de l'onglet 2 ne partent qu'à son ouverture -->
<dsfr-data-source id="s-clubs" api-type="opendatasoft" lazy
  base-url="https://data.sports.gouv.fr" dataset-id="clubs">
</dsfr-data-source>

<div class="fr-tabs__panel" id="panneau-2">
  <dsfr-data-chart source="s-clubs" type="bar" label-field="dep" value-field="n"></dsfr-data-chart>
</div>

<!-- Cible explicite, quand la détection automatique ne voit pas le bon élément -->
<dsfr-data-source id="s-carte" api-type="opendatasoft" lazy lazy-target="#panneau-3"
  base-url="https://data.sports.gouv.fr" dataset-id="equipements">
</dsfr-data-source>

Ce qui est observé : les feuilles de la chaîne aval (chart, list, kpi, display, podium, a11y, repeat ; pour une couche de carte, la carte qui la porte), suivies à travers les transformateurs. Un dsfr-data-query est un tuyau déclaré en haut de page : l'observer reviendrait à ne rien différer.

Toutes les dégradations vont du côté « on charge » : sans IntersectionObserver, ou si la page ne déclare aucun consommateur (ou si lazy-target ne désigne rien), la source part immédiatement et le dit en console. Une source qui ne chargerait jamais serait pire que le trafic qu'on cherche à éviter.

Ce que lazy ne promet pas : un IntersectionObserver n'est pas continu. Il échantillonne aux temps de rendu ; un défilement par crans rapides peut traverser un consommateur sans jamais le rapporter comme visible — la source reste alors en attente jusqu'au prochain passage. C'est le comportement du navigateur, pas un bug.

Se cumule avec require-where : les deux portes doivent s'ouvrir, et require-where est évalué en premier — c'est son message d'attente que l'utilisateur doit lire. Pendant l'attente de lazy, la source publie dsfr-data-idle avec la raison lazy, que le volet Diagnostic distingue de l'attente d'un filtre.

Filtres et WHERE dynamique

where="population:gt:5000"
where="population:gt:5000, region:in:IDF|OCC|BRE"
where="email:isnull"

where="population > 5000 AND status = 'active'"

<!-- WHERE statique + overlays dynamiques des facettes et recherche -->
<dsfr-data-source id="src" api-type="opendatasoft"
  dataset-id="rappelconso-v2-gtin-trie"
  base-url="https://data.economie.gouv.fr"
  where="categorie_produit = 'Alimentation'"
  server-side page-size="20">
</dsfr-data-source>

<!-- La recherche ajoute un overlay WHERE via server-search -->
<dsfr-data-search id="search" source="src"
  server-search>
</dsfr-data-search>

<!-- Les facettes ajoutent des overlays WHERE -->
<dsfr-data-facets id="facets" source="src"
  fields="categorie_produit, marque_produit" server-facets>
</dsfr-data-facets>

Mode server-side

Avec server-side, dsfr-data-source charge une seule page a la fois et ecoute les commandes des composants en aval pour naviguer entre les pages. Cela permet d'afficher des datasets de milliers d'enregistrements sans tout charger en memoire.

Le composant reagit a trois types de commandes :

Pagination serveur et regroupement : jamais sur une seule page

Une source en server-side ne livre qu'une page. Tout ce qui se calcule côté client sur l'ensemble des lignes n'a donc pas de sens derrière elle. Une dsfr-data-query en aval dont le regroupement ou l'agrégat n'est pas délégué au serveur passe en erreur de configuration : elle porte l'attribut data-dsfr-config-error, les blocs en aval affichent leur état d'erreur, et aucun chiffre partiel n'est émis. Sont concernés une part ou un cumul (share, share_percent, running_sum, diff), un explode, un agrégat sans group-by, une fonction que l'adaptateur ne traduit pas, un regroupement posé derrière un transformateur qui change les colonnes (compute, renommage, dépliage), une source lue par d'autres composants, une source déjà regroupée.

Le message d'erreur nomme la source et les deux corrections :

• retirer server-side : la source charge le jeu entier, dans la limite de max-records ;
• si le jeu dépasse ce plafond, ou si un tableau paginé lit la même source : donner à la requête sa propre source, sans server-side, qui porte le regroupement délégable. Le serveur regroupe alors le jeu entier, et la part ou le cumul se calcule en aval, sur les groupes.

<!-- le tableau garde sa source paginée -->
<dsfr-data-source id="lignes" api-type="tabular" resource="…" server-side page-size="20"></dsfr-data-source>
<dsfr-data-list source="lignes" columns="region:Région, population:Population"></dsfr-data-list>

<!-- la répartition a la sienne : le serveur regroupe, la part se calcule sur les groupes -->
<dsfr-data-source id="par-region" api-type="tabular" resource="…"
  group-by="region" aggregate="population:sum"></dsfr-data-source>
<dsfr-data-query id="parts" source="par-region"
  aggregate="population__sum:share_percent:part"></dsfr-data-query>

Une requête qui délègue réellement son regroupement, ou qui ne regroupe pas (filtre et tri d'un tableau paginé), n'est pas concernée. En mode URL, paginate ne livre lui aussi qu'une page, mais aucun attribut ne lui fait charger le jeu entier : la requête calcule alors sur la page reçue et le dit, en console et au volet Diagnostic.

Relais cachable : servir les données depuis le cache du site

Un site qui a du cache (Varnish, CDN, cache de son CMS) veut que les données d'une dataviz passent par son domaine, sous une URL qui identifie la donnée. Avec relay-url, la source n'appelle plus le portail : elle appelle le site, sous la forme <relais>/<hôte>/<chemin>?<requête>, et c'est le relais du site qui va chercher la réponse et la met en cache. La source reste en mode adaptateur : filtres, regroupements, tri et pagination délégués vivent dans l'URL, que le relais transmet telle quelle.

<!-- La requête part vers
     /donnees-relais/data.economie.gouv.fr/api/explore/v2.1/catalog/datasets/rappelconso/records?… -->
<dsfr-data-source id="rappels" api-type="opendatasoft" relay-url="/donnees-relais"
  base-url="https://data.economie.gouv.fr" dataset-id="rappelconso">
</dsfr-data-source>

<!-- Ou une fois pour toute la page, avant le chargement des composants -->
<script>window.DSFR_DATA_RELAY = '/donnees-relais';</script>

Deux cibles, deux URL ; une même requête, la même URL au caractère près : le chemin et la requête sont repris tels que l'adaptateur les a écrits, sans réencodage ni tri des paramètres. Deux visiteurs qui posent les mêmes filtres dans un ordre différent produisent deux URL, donc deux entrées de cache.

Aucun en-tête ne part au relais : ni headers, ni api-key-ref, ni cookie. Si le portail exige une clé, c'est le relais qui l'ajoute, depuis sa configuration — la clé quitte le navigateur. La source l'écrit une fois en console quand l'un de ces attributs est posé. Hors relais, ils restent actifs.

Ce qui ne passe pas par le relais, et garde le chemin habituel (direct, ou proxy-url) : une URL relative ou de même origine ; une requête POST (method="POST", mode SQL de Grist) ; une cible hors https, sur un port explicite ou avec identifiants, et un chemin que le relais refuserait (%2f, %2e, //…) — ces deux derniers cas avec un avertissement en console. fetch-mode="export" sur l'API Tabular (export Parquet) retombe sur la pagination, qui est relayée. Une URL de relais de plus de 8 000 caractères part quand même au relais, qui répond 414 : la bibliothèque ne le contourne jamais en silence.

Sans rapport avec proxy-url ni cache-ttl : proxy-url désigne le proxy CORS (endpoints dédiés et /cors-proxy, cible dans un en-tête, donc non cachable) ; cache-ttl est un repli hors ligne côté navigateur. La durée de cache d'une donnée relayée se règle sur le relais.

Erreurs : les statuts du relais sont lus par le barème d'erreurs (hôte hors liste : 403 ; URL trop longue : 414 ; amont en panne : 502 ou 504 ; débit dépassé : 429), et « Détails techniques » montre l'URL du relais réellement appelée. Un relais sans file d'attente répond 503 quand un visiteur charge d'un coup plus de dataviz qu'il n'a de places : la requête est alors réessayée trois fois au plus, après le délai annoncé par Retry-After ; jamais sur un 429.

Exemples

<dsfr-data-source
  id="prix-ct"
  url="https://data.economie.gouv.fr/api/explore/v2.1/catalog/datasets/prix-controle-technique/records"
  transform="results"
></dsfr-data-source>

<dsfr-data-source
  id="api-privee"
  url="https://mon-api.gouv.fr/data"
  method="POST"
  headers='{"Authorization": "Bearer TOKEN"}'
  params='{"limit": 100, "filters": {"annee": 2024}}'
  transform="data.items"
  refresh="60"
></dsfr-data-source>

<dsfr-data-source
  id="browse"
  api-type="opendatasoft"
  dataset-id="rappelconso-v2-gtin-trie"
  base-url="https://data.economie.gouv.fr"
  server-side
  paginate
  page-size="20"
></dsfr-data-source>

<dsfr-data-list source="browse"
  columns="modeles_ou_references:Produit, categorie_produit:Catégorie, marque_produit:Marque"
  pagination="20">
</dsfr-data-list>

<dsfr-data-source
  id="ghibli-films"
  url="https://ghibliapi.vercel.app/films"
  use-proxy
></dsfr-data-source>

<dsfr-data-source
  id="elus"
  api-type="opendatasoft"
  base-url="https://data.iledefrance.fr"
  dataset-id="elus-regionaux"
  where="sexe = 'F'"
></dsfr-data-source>

<dsfr-data-query id="stats" source="elus"
  group-by="groupe_politique"
  aggregate="nom:count:nb"
  order-by="nb:desc">
</dsfr-data-query>

<dsfr-data-chart source="stats" type="bar"
  label-field="groupe_politique" value-field="nb">
</dsfr-data-chart>

<dsfr-data-source
  id="src-ods"
  api-type="opendatasoft"
  dataset-id="rappelconso-v2-gtin-trie"
  base-url="https://data.economie.gouv.fr"
  server-side
  page-size="20"
></dsfr-data-source>

<dsfr-data-list source="src-ods"
  columns="modeles_ou_references:Produit, categorie_produit:Catégorie, marque_produit:Marque, date_publication:Date"
  server-sort
  pagination="20">
</dsfr-data-list>

<dsfr-data-source
  id="grist-data"
  api-type="grist"
  base-url="https://grist.numerique.gouv.fr/api/docs/DOC_ID/tables/TABLE_ID/records"
  headers='{"Authorization": "Bearer TOKEN"}'
></dsfr-data-source>

<dsfr-data-chart source="grist-data" type="bar"
  label-field="nom" value-field="valeur">
</dsfr-data-chart>

<dsfr-data-source
  id="srv"
  api-type="opendatasoft"
  dataset-id="rappelconso-v2-gtin-trie"
  base-url="https://data.economie.gouv.fr"
  server-side
  page-size="20"
></dsfr-data-source>

<dsfr-data-list source="srv"
  columns="modeles_ou_references:Produit, categorie_produit:Catégorie, marque_produit:Marque"
  server-sort
  pagination="20">
</dsfr-data-list>

<dsfr-data-source
  id="inline"
  data='[{"nom":"Paris","pop":2161000},{"nom":"Lyon","pop":516092},{"nom":"Marseille","pop":870731}]'
></dsfr-data-source>

<dsfr-data-chart source="inline" type="bar"
  label-field="nom" value-field="pop">
</dsfr-data-chart>

<script>
  window.DSFR_DATA_KEYS = {
    tmdb: 'Bearer eyJhbGciOiJIUzI1NiJ9...',
    monapi: 'Token abc123'
  };
</script>

<dsfr-data-source
  id="films"
  url="https://api.themoviedb.org/3/movie/popular"
  api-key-ref="tmdb"
  transform="results"
></dsfr-data-source>

<dsfr-data-source
  id="live"
  api-type="opendatasoft"
  base-url="https://data.opendatasoft.com"
  dataset-id="mon-dataset"
  refresh="30"
></dsfr-data-source>

Quand la source est en panne : un message lisible, dit une fois

Quand le chargement échoue, les blocs branchés sur la source ne montrent plus Erreur de chargement: HTTP 503: Service Unavailable en rouge. Chacun garde sa place et affiche, dans un encart neutre, une phrase que l'usager peut comprendre ; le code HTTP, l'adresse appelée et l'heure sont repliés dans « Détails techniques ». La phrase dépend de la cause :

« Réessayer » recharge la source à l'identique (mêmes filtres, même page) : c'est la méthode reload(), déclenchée par la commande { reload: true }. Après un échec hors connexion, la source se relance d'elle-même, une fois, au retour du réseau. L'erreur de configuration d'un composant d'affichage (attribut invalide) n'est pas concernée : elle reste une alerte, écrite pour l'intégrateur.

Pour dire la panne avec vos mots, posez error-message sur la source :

Données introuvables : le lien vers la page des données

Quand la source répond « introuvable » (HTTP 404 ou 410), l'usager n'a rien à réessayer : le producteur a déplacé ou retiré le jeu. Posez source-page sur la source avec l'adresse de la page publique de ces données — la page du jeu sur le portail du producteur, celle qu'un usager peut lire, pas l'adresse d'API. Les blocs en erreur et le bandeau proposent alors le lien « Consulter la page de ces données ».

• Le lien n'apparaît que sur des données introuvables : jamais sur un service indisponible, une coupure de connexion, un accès restreint ou une page mal réglée.
• Sans source-page, aucun lien. La bibliothèque ne déduit l'adresse ni de base-url, ni de dataset-id, ni de resource : sur un portail Opendatasoft, la page /explore/dataset/<id>/ disparaît avec le jeu, donc le lien déduit mènerait à une page introuvable ; sur l'API Tabular, l'identifiant de ressource ne donne pas le jeu sans une requête de plus. L'adresse d'API n'est jamais proposée à l'usager, ni celle du relais (relay-url).
• N'est admise qu'une adresse http(s) ou relative. Toute autre (javascript:, data:…) est ignorée, avec un avertissement en console.
• Avec un bandeau, c'est lui qui porte le lien, une fois ; les blocs ne le répètent pas.

<dsfr-data-source id="prix" api-type="opendatasoft"
  base-url="https://data.economie.gouv.fr" dataset-id="prix-carburants"
  source-page="https://data.economie.gouv.fr/explore/dataset/prix-carburants/">
</dsfr-data-source>

Dans une tuile de KPI : la forme compacte

L'encart complet est fait pour un bloc de graphique ; dans une tuile de KPI il doublerait sa hauteur. Un <dsfr-data-kpi> dont la source est en panne garde donc sa place et sa hauteur : « — » à la place du chiffre, son libellé (l'usager doit savoir quel chiffre manque) et une phrase courte. Il n'affiche jamais un nombre : ni 0, ni le chiffre du chargement précédent. Les autres afficheurs (graphique, jauge comprise, liste, podium, display) gardent l'encart complet.

error-message remplace la phrase, comme dans l'encart complet. « Détails » est replié, à la suite de la phrase : il donne le code HTTP, l'adresse appelée et l'heure. Avec un bandeau dsfr-data-source-status, la tuile ne garde que le tiret, le libellé et la phrase : le bouton, le lien et le détail sont dans le bandeau. Dans une tuile étroite, le lien ou « Détails » passent à la ligne, et la tuile gagne une ligne. Une valeur absente des données (null, champ manquant) n'est pas une panne : la tuile affiche « — » et son libellé, sans phrase.

Accessibilité : le tiret est masqué aux lecteurs d'écran (aria-hidden), qui lisent le libellé et la phrase ; la figure se nomme « libellé : phrase », sans chiffre. Le bouton « Réessayer » garde 44 px de haut.

Tableau équivalent, carte, filtres, pagination : aucun ancien chiffre

Pendant une panne, aucun bloc ne garde à l'écran une ligne du dernier chargement : sans date, elle serait prise pour le chiffre du jour. Le graphique, le KPI, la liste, le podium et les fiches rendent le message décrit plus haut. Les blocs ci-dessous, qui n'avaient pas de rendu de panne, suivent la même règle.

Les phrases suivent la cause, comme l'encart : hors connexion, « Vous semblez hors connexion » ; HTTP 429, « Le service est très sollicité » ; données introuvables, « Ces données ne sont plus publiées à cette adresse » ; accès restreint, « Ces données ne sont pas accessibles publiquement ». Pour les filtres et la description du tableau équivalent, la cause suit la mention « indisponibles » : « Filtres indisponibles. Vous semblez hors connexion. » error-message s'applique partout. Quand le refus vient de la page elle-même (HTTP 400), les filtres restent actifs : le filtre posé peut être la cause du refus, et le retirer est alors le seul remède.

Avec un bandeau dsfr-data-source-status, aucun de ces blocs ne porte « Réessayer » ni n'annonce la panne une seconde fois : la carte et le tableau équivalent gardent leur phrase, sans bouton. Sans bandeau, la carte porte « Réessayer » (dans le message centré comme dans la ligne d'état) ; le tableau équivalent et les filtres n'annoncent rien de plus, la panne étant déjà dite par le graphique, la carte ou la liste qu'ils accompagnent.

Pendant un nouvel essai (« Réessayer », retour du réseau, rafraîchissement périodique) : le graphique, le KPI, la liste et les fiches affichent leur indicateur de chargement ; le tableau équivalent, la carte et les filtres gardent leur rendu de panne, phrase comprise, jusqu'au résultat — rien ne clignote. Au chargement réussi, tout revient sans rechargement de la page.

Le dernier relevé, sur demande : stale-if-error

Par défaut, une source en panne ne laisse aucun de ses anciens chiffres à l'écran. Pour un jeu qui change peu — un recensement, un budget voté, un référentiel —, un trou fait croire la page cassée alors que le chiffre d'il y a dix minutes est encore le chiffre du jour. Posez stale-if-error sur la source, avec une durée en secondes : pendant une panne passagère, les blocs branchés dessus gardent leurs derniers chiffres, atténués, sous l'étiquette « Non actualisé » et l'heure de leur relevé.

<!-- Pendant une panne passagère, les derniers chiffres restent une heure, datés -->
<dsfr-data-source id="aides" api-type="opendatasoft"
  base-url="https://data.economie.gouv.fr" dataset-id="aides-industrie"
  stale-if-error="3600">
</dsfr-data-source>

<dsfr-data-kpi source="aides" value="beneficiaires:sum" label="Bénéficiaires"></dsfr-data-kpi>
<dsfr-data-chart source="aides" type="bar" label-field="region" value-field="beneficiaires"></dsfr-data-chart>

C'est à vous de le décider, jeu par jeu : la bibliothèque ne sait pas si un chiffre est un recensement ou un nombre de places libres. Ne le posez pas sur une donnée que l'usager utilise pour agir tout de suite (prix, stock, file d'attente, alerte) : un tiret y est moins dangereux qu'une valeur d'il y a une heure. La valeur est la borne — il n'existe pas de relevé sans durée —, comptée depuis le relevé et non depuis la panne.

Un autre jour que celui du relevé, la date est écrite en entier — « Chiffres relevés le 12 octobre à 18 h 05. » —, jamais « hier » ni « il y a 3 min ». Hors connexion, la mention ajoute « Vous semblez hors connexion. » ; error-message s'y ajoute aussi.

Le relevé n'est jamais affiché, quelle que soit la durée, et le bloc rend le message de panne décrit plus haut, quand :

• la source ne porte pas stale-if-error, ou sa valeur n'est pas une durée strictement positive (elle est alors ignorée, avec un avertissement en console) ;
• la cause n'est pas passagère : données introuvables (HTTP 404, 410), accès restreint (401, 403), page mal réglée — le producteur a retiré ou fermé ces données, les remontrer serait les republier ;
• l'appel en échec n'est pas celui qui a produit les chiffres : un filtre, une page, un tri ou l'emprise d'une carte en bbox a changé — les lignes gardées répondent à une autre question. Il en va de même quand un attribut d'une requête branchée sur la source change pendant la panne ;
• le relevé est plus vieux que la durée donnée : le bloc bascule de lui-même, sans geste de l'usager ;
• rien n'a encore été reçu — une page ouverte pendant la panne n'a rien à montrer, la mémoire est celle de la page.

Pendant un nouvel essai, les chiffres relevés restent en place — pas de retour à l'indicateur de chargement, une source en refresh ne fait pas clignoter la page — et le bouton dit « Nouvel essai en cours… ». Au chargement réussi, l'étiquette disparaît et les nouveaux chiffres s'affichent. Sans bandeau, chaque mention porte « Réessayer » et « Détails techniques » ; avec un bandeau, il les porte seul.

Pour un script de la page, rien ne change : getData() et getDataCache(id) rendent toujours vide pendant la panne. Le relevé n'est lu que par les composants d'affichage.

dsfr-data-source-status : le bandeau qui dit la panne une fois

Sans bandeau, huit blocs branchés sur une source en panne affichent huit messages et huit boutons « Réessayer ». Posez <dsfr-data-source-status> en haut du contenu : la panne est dite une fois par source, avec le seul bouton « Réessayer ». Les blocs concernés gardent leur place et leur message court, sans bouton ; les blocs d'une autre source ne sont pas touchés. Le bandeau n'affiche rien tant qu'aucune source n'est en panne.

<!-- La panne de "prix" est dite ici, une fois -->
<dsfr-data-source-status source="prix"></dsfr-data-source-status>

<dsfr-data-source id="prix" api-type="opendatasoft"
  base-url="https://data.economie.gouv.fr" dataset-id="prix-carburants"
  error-message="Les prix sont en cours de mise à jour. Revenez dans quelques minutes.">
</dsfr-data-source>

<dsfr-data-kpi source="prix" valeur="avg:prix" label="Prix moyen"></dsfr-data-kpi>
<dsfr-data-chart source="prix" type="bar" label-field="ville" value-field="prix"></dsfr-data-chart>

Accessibilité : le bandeau est une région role="status" (annonce polie, qui n'interrompt pas la lecture). Les blocs en erreur ne sont plus des alertes assertives : sans bandeau, chacun est une région role="status" ; avec bandeau, seul le bandeau annonce. Le bouton « Réessayer » est un bouton DSFR d'au moins 44 px de haut.

Pendant la panne : les dernières lignes, périmées et datées

Une source qui échoue après avoir déjà livré ne jette pas ses lignes, mais elles ne passent plus pour à jour. Les composants n'en affichent aucune : ils gardent le message de panne décrit plus haut — tableau équivalent, carte et export compris —, sauf quand la source le demande par stale-if-error, et alors datées. Pour un script de la page, la règle est la même, avec ou sans cet attribut :

loadedAt est la date (Date.now()) du dernier chargement réussi, since celle du premier échec depuis, cause la cause du barème (service-indisponible, hors-connexion, service-sollicite, donnees-introuvables, acces-restreint, page-mal-reglee, reponse-bloquee) et originId la source qui a réellement échoué. Quand la source porte stale-if-error, staleIfError en rend la durée (en secondes) et sameRequest dit si l'appel en échec est celui qui avait produit ces lignes. Les lignes et leur date sont rendues ensemble : on ne peut pas obtenir les unes sans l'autre. Le marquage se lève au premier chargement réussi ; une source remise en attente d'un filtre (require-where) ou retirée de la page n'en garde aucune.

<script type="module">
  document.addEventListener('dsfr-data-error', (e) => {
    if (e.detail.sourceId !== 'prix' || e.detail.lastLoadedAt === undefined) return;
    const { data, loadedAt, stale } = document.getElementById('prix').getLastKnownData();
    // À n'afficher que DATÉ : « Données du … · mise à jour impossible »
    console.log(data.length, 'lignes du', new Date(loadedAt).toLocaleString('fr-FR'), stale.cause);
  });
</script>

Les transformateurs suivent la même règle : une requête, un dsfr-data-normalize, une jointure, un empilement ou un pivot dont la source est en panne relaient l'erreur et ne recalculent rien sur les anciennes lignes — ni quand un de leurs attributs change, ni quand une autre de leurs entrées se recharge.

Événements

Le composant émet des événements personnalises via le système data-bridge :

• dsfr-data-loaded : Données chargées avec succès (detail : { sourceId, data, loadedAt } — loadedAt date le chargement)
• dsfr-data-loading : Chargement en cours
• dsfr-data-error : Erreur de chargement (detail : { sourceId, error, attemptedUrl?, lastLoadedAt? }, le message de l'Error porte le code HTTP). lastLoadedAt n'est présent que si la source avait déjà livré : ses lignes restent en mémoire, périmées. Le message lisible des blocs ne change pas cet événement : avec la trace console, il reste la voie de l'intégrateur.
• cache-fallback : Les données proviennent du cache serveur suite a une erreur API (mode DB uniquement)

Méthodes publiques

Conseils d'utilisation