dsfr-data

dsfr-data est un module complementaire au Systeme de design de l'Etat (DSFR) pour l'integration de donnees dynamiques. Il s'agit d'une bibliotheque de Web Components (Lit), sous la forme de balises HTML <dsfr-data-*>, a destination des developpeurs et integrateurs ayant besoin d'afficher des donnees issues d'APIs ouvertes dans leurs pages web.

dsfr-data s'appuie sur DSFR Chart pour le rendu des graphiques.

Demo

L'ensemble des composants et leurs options sont documentes sur la page de specifications.

Installation

Fichiers statiques (CDN)

Prerequis : le projet doit utiliser le DSFR et DSFR Chart.

<!-- DSFR -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@gouvfr/[email protected]/dist/dsfr.min.css">

<!-- DSFR Chart -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@gouvfr/[email protected]/dist/DSFRChart/DSFRChart.css">
<script type="module" src="https://cdn.jsdelivr.net/npm/@gouvfr/[email protected]/dist/DSFRChart/DSFRChart.js"></script>

<!-- dsfr-data -->
<script src="https://unpkg.com/dsfr-data/dist/dsfr-data.core.umd.js"></script>

NPM

npm install dsfr-data

import 'dsfr-data';

Structure des bundles

Trois bundles sont disponibles selon les besoins :

| Bundle | Contenu | Taille (gzip) | |--------|---------|---------------| | dsfr-data.core.{esm,umd}.js | Tous les composants sauf carte du monde | ~52 Ko | | dsfr-data.world-map.{esm,umd}.js | Composant dsfr-data-world-map (d3-geo) | ~30 Ko | | dsfr-data.{esm,umd}.js | Tout-en-un (core + world-map) | ~70 Ko |

Composants disponibles

Les composants se chainent de facon declarative pour former un pipeline :

dsfr-data-source → dsfr-data-normalize → dsfr-data-query → dsfr-data-chart / dsfr-data-kpi / dsfr-data-list
                                                          → dsfr-data-facets / dsfr-data-search
                                                          → dsfr-data-a11y

Source de donnees (dsfr-data-source)

Composant invisible de connexion aux donnees. Recupere des donnees depuis une API REST ou des donnees inline et les distribue aux autres composants.

Parametres

Obligatoires (mode URL) :

• url : (String) URL de l'API a interroger.

Obligatoires (mode adapter) :

• api-type : (String) Type de provider. Valeurs possibles : opendatasoft, tabular, grist, generic.
• base-url : (String) URL de base du portail de donnees.
• dataset-id : (String) Identifiant du jeu de donnees (ODS) ou document (Grist).

Optionnels :

• transform : (String) Chemin JSON vers les donnees dans la reponse (ex: results, records).
• resource : (String) Identifiant de la ressource (Tabular) ou table (Grist).
• server-side : (Boolean) Active la pagination server-side.
• page-size : (Number) Nombre d'enregistrements par page (defaut: 100).
• where : (String) Filtre server-side (syntaxe ODSQL ou colon selon le provider).
• select : (String) Colonnes a selectionner.
• group-by : (String) Regroupement server-side.
• order-by : (String) Tri server-side.
• limit : (Number) Nombre maximum d'enregistrements.
• refresh : (Number) Intervalle de rafraichissement en secondes.
• data : (String) Donnees JSON inline (alternative a url).
• headers : (String) En-tetes HTTP (JSON).
• cache-ttl : (Number) Duree du cache en secondes.

Exemple

<dsfr-data-source id="src" api-type="opendatasoft"
  base-url="https://data.economie.gouv.fr"
  dataset-id="industrie-du-futur"
  limit="100">
</dsfr-data-source>

Requetage (dsfr-data-query)

Transformateur client-side : filtre, regroupe, agrege et trie les donnees recues d'une source.

Parametres

Obligatoires :

• source : (String) ID du composant source a ecouter.

Optionnels :

• filter : (String) Expression de filtre (ex: population > 5000).
• group-by : (String) Champ(s) de regroupement.
• aggregate : (String) Agregation au format champ:fonction:alias (ex: population:sum:total). Fonctions : sum, avg, count, min, max, first, last, distinct.
• order-by : (String) Tri au format champ:asc|desc.
• limit : (Number) Nombre maximum de resultats.

Exemple

<dsfr-data-query id="q" source="src"
  group-by="nom_region"
  aggregate="nombre_beneficiaires:sum:total"
  order-by="total:desc" limit="10">
</dsfr-data-query>

Normalisation (dsfr-data-normalize)

Nettoie et transforme les donnees avant traitement.

Parametres

• source : (String) ID du composant source.
• to-number : (String) Champs a convertir en nombre (separes par des virgules).
• rename : (String) Renommage de colonnes au format ancien:nouveau.
• trim : (Boolean) Supprime les espaces en debut/fin des valeurs texte.
• replace : (String) Remplacement de valeurs au format champ:ancien:nouveau.

Graphique DSFR (dsfr-data-chart)

Connecte les donnees a un graphique DSFR Chart.

Parametres

Obligatoires :

• source : (String) ID du composant source.
• type : (String) Type de graphique. Valeurs possibles : bar, line, pie, radar, scatter, gauge, bar-line, map, map-reg.
• label-field : (String) Champ pour les etiquettes.
• value-field : (String) Champ pour les valeurs.

Optionnels :

• value-field-2 : (String) Champ pour une seconde serie (bar-line).
• titre : (String) Titre du graphique.
• selected-palette : (String) Palette de couleurs : default, neutral, categorical, sequentialAscending, sequentialDescending, divergentAscending, divergentDescending.
• unit-tooltip : (String) Unite affichee dans l'infobulle (ex: %, EUR).
• horizontal : (Boolean) Barres horizontales (types bar, bar-line).
• stacked : (Boolean) Barres empilees (types bar, bar-line).

Exemple

<dsfr-data-chart source="q" type="bar"
  label-field="nom_region" value-field="total"
  titre="Beneficiaires par region"
  selected-palette="categorical">
</dsfr-data-chart>

Indicateur cle (dsfr-data-kpi)

Affiche un indicateur chiffre (KPI) avec formatage, couleur conditionnelle et icone.

Parametres

• source : (String) ID du composant source.
• value-field : (String) Champ de la valeur.
• aggregate : (String) Fonction d'agregation : sum, avg, count, min, max.
• format : (String) Format d'affichage : number, percent, euro, decimal.
• label : (String) Libelle affiche sous la valeur.
• icon : (String) Classe Remix Icon (ex: ri-line-chart-line).
• color : (String) Couleur : blue, green, orange, red, ou auto (seuils automatiques).

Tableau (dsfr-data-list)

Affiche les donnees sous forme de tableau avec recherche, tri, pagination et export CSV.

Parametres

• source : (String) ID du composant source.
• colonnes : (String) Colonnes a afficher (separes par des virgules, vide = toutes).
• pagination : (Number) Nombre de lignes par page (0 = tout afficher).
• search : (Boolean) Active la barre de recherche.
• export-csv : (Boolean) Active l'export CSV.

Filtres a facettes (dsfr-data-facets)

Ajoute des filtres interactifs (checkbox, radio, select) sur les donnees.

Parametres

• source : (String) ID du composant source.
• fields : (String) Champs filtrables (separes par des virgules).
• type : (String) Type de rendu : checkbox, radio, select.

Recherche (dsfr-data-search)

Barre de recherche textuelle avec filtrage client ou server-side.

Parametres

• source : (String) ID du composant source.
• fields : (String) Champs dans lesquels chercher.
• placeholder : (String) Texte d'indication.
• server-side : (Boolean) Delegue la recherche au serveur.

Affichage libre (dsfr-data-display)

Template HTML libre pour afficher les donnees sous forme de cartes, fiches ou grilles.

Parametres

• source : (String) ID du composant source.
• template : (String) Template HTML avec placeholders {{champ}}.
• empty-message : (String) Message quand aucune donnee.

Carte du monde (dsfr-data-world-map)

Carte choropleth du monde coloree par valeurs.

Parametres

• source : (String) ID du composant source.
• code-field : (String) Champ contenant le code pays ISO.
• value-field : (String) Champ contenant la valeur.
• label-field : (String) Champ contenant le nom du pays.

Necessite le bundle dsfr-data.world-map.umd.js en complement du bundle core.

Accessibilite (dsfr-data-a11y)

Companion d'accessibilite : tableau de donnees alternatif, export CSV, description textuelle.

Parametres

• for : (String) ID du composant graphique associe.
• source : (String) ID du composant source de donnees.
• table : (Boolean) Affiche un tableau alternatif.
• download : (Boolean) Ajoute un lien d'export CSV.
• description : (String) Description textuelle du graphique.

Exemple

<dsfr-data-a11y for="mon-graph" source="q" table download></dsfr-data-a11y>

Exemple complet

<!-- Charger DSFR + DSFR Chart + dsfr-data (voir section Installation) -->

<!-- Source de donnees -->
<dsfr-data-source id="data"
  url="https://data.economie.gouv.fr/api/explore/v2.1/catalog/datasets/industrie-du-futur/records?limit=100"
  transform="results">
</dsfr-data-source>

<!-- Agregation par region -->
<dsfr-data-query id="q" source="data"
  group-by="nom_region"
  aggregate="nombre_beneficiaires:sum:beneficiaires"
  order-by="beneficiaires:desc" limit="10">
</dsfr-data-query>

<!-- Graphique en barres -->
<dsfr-data-chart id="mon-graph" source="q" type="bar"
  label-field="nom_region" value-field="beneficiaires"
  titre="Beneficiaires par region">
</dsfr-data-chart>

<!-- Accessibilite -->
<dsfr-data-a11y for="mon-graph" source="q" table download></dsfr-data-a11y>

Applications de creation

Le projet inclut des applications web permettant de generer le code HTML des composants sans ecrire de code :

| Application | Description | |-------------|-------------| | Builder | Generateur visuel de graphiques pas-a-pas | | Builder IA | Generateur par conversation avec l'IA Albert | | Playground | Editeur de code interactif avec apercu temps reel | | Dashboard | Editeur visuel de tableaux de bord multi-widgets | | Sources | Gestionnaire de connexions aux APIs | | Favoris | Sauvegarde et reutilisation des creations | | Monitoring | Suivi des widgets deployes en production |

Developpement

Prerequis

• Node.js >= 20
• npm >= 9

Installation

git clone https://github.com/bmatge/dsfr-data.git
cd dsfr-data
npm install

Commandes

| Commande | Description | |----------|-------------| | npm run dev | Serveur de dev Vite (port 5173) | | npm run build | Build bibliotheque (ESM + UMD) | | npm run build:shared | Build du package @dsfr-data/shared | | npm run build:apps | Build de toutes les applications | | npm run build:all | Build complet (shared + lib + apps) | | npm run test | Tests Vitest en watch mode | | npm run test:run | Tests une seule fois | | npm run test:e2e | Tests E2E Playwright |

Documentation

• Specifications des composants -- Demo interactive et reference des parametres
• Guide utilisateur -- Parcours pas-a-pas
• Architecture -- Architecture technique detaillee
• Fiche produit -- Positionnement, comparatif, cibles
• Contribuer -- Guide de contribution
• Proxy CORS -- Deploiement du proxy

Licence

MIT