# @cgdd-bun/dido-widgets

> Widgets Library for DiDo Api as Web Components

Latest version **2.2.3** (published 2025-09-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install @cgdd-bun/dido-widgets
pnpm add @cgdd-bun/dido-widgets
yarn add @cgdd-bun/dido-widgets
bun add @cgdd-bun/dido-widgets
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 2.2.3 |
| Published | 2025-09-08 |
| First published | 2022-02-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 14 |
| Unpacked size | 9.4 MB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Author | Christophe BARRIERE |
| Maintainers | charloup |

## Links

- npm: https://www.npmjs.com/package/@cgdd-bun/dido-widgets
- Repository: https://gitlab-forge.din.developpement-durable.gouv.fr/cgdd/sdsed-bun/datalake/widget-library
- npm.io page: https://npm.io/package/@cgdd-bun/dido-widgets

## Dependencies (14)

- [vue](https://npm.io/package/vue.md) 3.2.37
- [axios](https://npm.io/package/axios.md) ^1.11.0
- [jszip](https://npm.io/package/jszip.md) ^3.10.1
- [quasar](https://npm.io/package/quasar.md) 2.7.*
- [semver](https://npm.io/package/semver.md) ^7.7.2
- [leaflet](https://npm.io/package/leaflet.md) ^1.9.4
- [rapidoc](https://npm.io/package/rapidoc.md) ^9.3.8
- [@turf/union](https://npm.io/package/@turf/union.md) ^7.2.0
- [highlight.js](https://npm.io/package/highlight.js.md) ^11.11.1
- [leaflet-draw](https://npm.io/package/leaflet-draw.md) ^1.0.4
- [@quasar/extras](https://npm.io/package/@quasar/extras.md) ^1.17.0
- [@gouvminint/vue-dsfr](https://npm.io/package/@gouvminint/vue-dsfr.md) ^3.6.0
- [passive-events-support](https://npm.io/package/passive-events-support.md) ^1.1.0
- [@highlightjs/vue-plugin](https://npm.io/package/@highlightjs/vue-plugin.md) ^2.1.2

## Recent versions

- 2.2.3 (latest) — 2025-09-08
- 2.2.2 — 2025-09-04
- 2.2.1 — 2025-09-02
- 2.2.0 — 2025-08-11
- 2.1.1 — 2025-06-10
- 2.1.0 — 2025-06-06
- 2.0.3 — 2024-02-06
- 2.0.2 — 2023-11-29
- 2.0.1 — 2023-10-04
- 2.0.0 — 2023-04-25
- 1.0.18 — 2023-02-24
- 1.0.17 — 2023-02-20
- 1.0.16 — 2022-12-12
- 1.0.15 — 2022-10-18
- 1.0.14 — 2022-10-06
- … 12 more at https://npm.io/package/@cgdd-bun/dido-widgets/versions

## README

# DiDo Wigets as Custom Elements Library

This project is a library of [web components](https://developer.mozilla.org/fr/docs/Web/Web_Components).
This web components are widgets for interaction with the DiDo API.

Actually there are 10 web components in the library:

- a web component for displaying a "dataset" detail
- a web component for displaying a "dataset" card
- a web component for displaying a "datafile" detail
- a web component for displaying a "datafile" card
- a web component for displaying a "millesime" detail
- a web component for downloading data from api
- a web component for displaying a pagination for datasets or datafiles resources
  (with infinite scroll)
- a web component for displaying an explore page (pagination with ui filter)
- a web component for displaying global apidoc
- a web component for displaying a full catalog

## Usage of the library

The library is developped with [Vue3](https://v3.vuejs.org/).
But for optimization Vue is not included in the library and must be loaded before.

The library expose a function for registering each web component with a custom tag.
If you don't specify a custom tag, the default tag for the component will be used;

Example of usage of web component dataset:

```html
<!-- Loading of Vue3 -->
<script src="https://unpkg.com/vue@3.2.37/dist/vue.global.prod.js"></script>
<!-- Loading of DiDo Library -->
<script src="https://unpkg.com/@cgdd-bun/dido-widgets/dist/dido-widgets.umd.js"></script>
<!-- Registering dido dataset custom element as my-custom-tag web component -->
<script>
  DidoWidgets.register("dataset", "my-custom-tag");
</script>
<!-- Web component will be here in shadow dom -->
<my-custom-tag
  dido-url="http://api.diffusion.dido.fr/v1"
  dido-dataset-id="61d4612eb90992002e39724f"
/>
```

## Interaction with library

Each web component get props for initializing.
Ex: url of api and dataset id for the web component "dataset".

Each web component emit events. You can attach listener to these events

Ex: attaching an event listener to event 'datafile-selection' of web component "dataset":

```js
// get webcomponent
const comp = document.querySelector("dido-dataset");

// attach listener to event 'datafile-selection'
comp.addEventListener("datafile-selection", (event) =>
  console.log(
    "click on card of datafile " +
      event.detail[0].datafileRid +
      " of dataset " +
      event.detail[0].datasetId,
  ),
);
```

## Dataset web component

- Default tag for registration: `dido-dataset`
- Props:
  - `dido-url`:
    - url of DiDo api
    - required
  - `dido-dataset-id`:
    - id of Dataset
    - required
- Events emitted
  - `widget-mounted`:
    - emitted when widget is mounted
    - event.detail[0]: `{ type }`
  - `bad-configuration`:
    - emitted when a required prop is not set
    - event.detail[0]: empty
  - `widget-unmounted`:
    - emitted when widget is mounted
    - event.detail[0]: `{ type }`
  - `dataset-retrieved`:
    - emitted when the dataset is retrieved with api
    - event.detail[0]: `{ datasetId }`
  - `dataset-not-retrieved`:
    - emitted when the dataset is unavailable
    - event.detail[0]: `{ datasetId }`
  - `label-selection`:
    - emitted when a label is clicked
    - event.detail[0]: `{ type, value }`
  - `datafile-selection`:
    - emitted when a datafile in the dataset is clicked
    - event.detail[0]: `{ datasetId, datafileRid }`

## Dataset Card web component

- Default tag for registration: `dido-dataset-card`
- Props:
  - `dido-url`:
    - url of DiDo api
    - required
  - `dido-dataset-id`:
    - id of Dataset
    - required
- Events emitted
  - `widget-mounted`:
    - emitted when widget is mounted
    - event.detail[0]: `{ type }`
  - `bad-configuration`:
    - emitted when a required prop is not set
    - event.detail[0]: empty
  - `widget-unmounted`:
    - emitted when widget is mounted
    - event.detail[0]: `{ type }`
  - `dataset-retrieved`:
    - emitted when the dataset is retrieved with api
    - event.detail[0]: `{ datasetId }`
  - `dataset-not-retrieved`:
    - emitted when the dataset is unavailable
    - event.detail[0]: `{ datasetId }`
  - `label-selection`:
    - emitted when a label is clicked
    - event.detail[0]: `{ type, value }`
  - `click-card`:
    - emitted when dataset card is clicked
    - event.detail[0]: `{ datasetId }`

## Datafile web component

- Default tag for registration: `dido-datafile`
- Props:
  - `dido-url`:
    - url of DiDo api
    - required
  - `dido-datafile-rid`:
    - rid of Datafile
    - required
  - `dido-datafile-millesime`:
    - millesime of datafile preselected
    - not required (if not set the last millesime is preselected)
  - `dido-initial-filter`:
    - initial filter in the table of data of selected millesime
    - not required, if set, format of json string:

      ```json
      {
        "orderBy": "-COLUMN1",
        "columns": "COLUMN1,COLUMN3,COLUMN4",
        "COLUMN1": { "type": "neq", "value": "valeur1" },
        "COLUMN4": { "type": "withinCogZones", "value": "dpt:63@2020" }
      }
      ```

- Events emitted
  - `widget-mounted`:
    - emitted when widget is mounted
    - event.detail[0]: `{ type }`
  - `bad-configuration`:
    - emitted when a required prop is not set
    - event.detail[0]: empty
  - `widget-unmounted`:
    - emitted when widget is mounted
    - event.detail[0]: `{ type }`
  - `datafile-retrieved`:
    - emitted when the datafile is retrieved with api
    - event.detail[0]: `{ datafileRid }`
  - `datafile-not-retrieved`:
    - emitted when the datafile is unavailable
    - event.detail[0]: `{ datafileRid }`
  - `label-selection`:
    - emitted when a label is clicked
    - event.detail[0]: `{ type, value }`
  - `dataset-selection`:
    - emitted when the dataset of the datefile is clicked
    - event.detail[0]: `{ datasetId }`
  - `millesime-selection`:
    - emitted when a millesime in the datefile is clicked
    - event.detail[0]: `{ datafileRid, datafileMillesime }`

## Datafile Card web component

- Default tag for registration: `dido-datafile-card`
- Props:
  - `dido-url`:
    - url of DiDo api
    - required
  - `dido-datafile-rid`:
    - rid of Datafile
    - required
- Events emitted
  - `widget-mounted`:
    - emitted when widget is mounted
    - event.detail[0]: `{ type }`
  - `widget-unmounted`:
    - emitted when widget is mounted
    - event.detail[0]: `{ type }`
  - `bad-configuration`:
    - emitted when a required prop is not set
    - event.detail[0]: empty
  - `datafile-retrieved`:
    - emitted when the datafile is retrieved with api
    - event.detail[0]: `{ datafileRid }`
  - `datafile-not-retrieved`:
    - emitted when the datafile is unavailable
    - event.detail[0]: `{ datafileRid }`
  - `label-selection`:
    - emitted when a label is clicked
    - event.detail[0]: `{ type, value }`
  - `click-card`:
    - emitted when datafile card is clicked
    - event.detail[0]: `{ datafileRid }`

## Millesime web component

- Default tag for registration: `dido-millesime`
- Props:
  - `dido-url`:
    - url of DiDo api
    - required
  - `dido-datafile-rid`:
    - rid of Datafile of millesime
    - required
  - `dido-datafile-millesime`:
    - millesime
    - required
  - `dido-initial-filter`:
    - initial filter in the table of data
    - not required, if set, format of json string:

      ```json
      {
        "orderBy": "-COLUMN1",
        "columns": "COLUMN1,COLUMN3,COLUMN4",
        "COLUMN1": { "type": "neq", "value": "valeur1" },
        "COLUMN4": { "type": "withinCogZones", "value": "dpt:63@2020" }
      }
      ```

- Events emitted
  - `widget-mounted`:
    - emitted when widget is mounted
    - event.detail[0]: `{ type }`
  - `widget-unmounted`:
    - emitted when widget is mounted
    - event.detail[0]: `{ type }`
  - `bad-configuration`:
    - emitted when a required prop is not set
    - event.detail[0]: empty
  - `millesime-retrieved`:
    - emitted when the millesime is retrieved with api
    - event.detail[0]: `{ datafileRid, datafileMillesime }`
  - `millesime-not-retrieved`:
    - emitted when the millesime is unavailable
    - event.detail[0]: `{ datafileRid, datafileMillesime }`

## Download web component

- Default tag for registration: `dido-download`
- Props:
  - `dido-url`:
    - url of DiDo api
    - required
  - `dido-widget-type`
    - level of widget (available values are dataset, datafile and millesime)
    - required
  - `dido-dataset-id`:
    - id of Dataset
    - required if dido-widget-type is `dataset`
  - `dido-datafile-rid`:
    - id of Datafile
    - required if dido-widget-type is `datafile` or `millesime`
  - `dido-datafile-millesime`:
    - millesime of datafile preselected
    - required if dido-widget-type is `millesime`
- Events emitted
  - `widget-mounted`:
    - emitted when widget is mounted
    - event.detail[0]: `{ type }`
  - `widget-unmounted`:
    - emitted when widget is mounted
    - event.detail[0]: `{ type }`
  - `bad-configuration`:
    - emitted when a required prop is not set
    - event.detail[0]: empty
  - `widget-type-unknown`:
    - emitted when dido-widget-type is not valid
    - event.detail[0]: `{ datasetId }`
  - `dataset-retrieved`:
    - emitted when dido-widget-type is `dataset` and the dataset is retrieved
      with api
    - event.detail[0]: `{ datasetId }`
  - `dataset-not-retrieved`:
    - emitted when dido-widget-type is `dataset` and the dataset is unavailable
    - event.detail[0]: `{ datasetId }`
  - `datafile-retrieved`:
    - emitted when dido-widget-type is `datafile` and the datafile is retrieved
      with api
    - event.detail[0]: `{ datafileRid }`
  - `datafile-not-retrieved`:
    - emitted when dido-widget-type is `datafile`and the datafile is unavailable
    - event.detail[0]: `{ datafileRid }`
  - `millesime-retrieved`:
    - emitted when dido-widget-type is `millesime` and the millesime is retrieved
      with api
    - event.detail[0]: `{ datafileRid, datafileMillesime }`
  - `millesime-not-retrieved`:
    - eemitted when dido-widget-type is `millesime` and the millesime is unavailable
    - event.detail[0]: `{ widgetType }`

## Pagination web component

- Default tag for registration: `dido-pagination`
- Props:
  - `dido-url`:
    - url of DiDo api
    - required
  - `dido-filter`:
    - filter used for pagination
    - required (you can pass {} for default value)
    - default value:

      ```json
      {
        "itemsType": "dataset",
        "order": { "field": "last_modified", "sort": "desc" },
        "text": "",
        "lastModified": { "max": "", "min": "" },
        "temporalCoverage": { "from": "", "to": "" },
        "topics": [],
        "tags": [],
        "licenses": [],
        "zones": [],
        "granularities": [],
        "frequencies": []
      }
      ```

- Events emitted
  - `widget-mounted`:
    - emitted when widget is mounted
    - event.detail[0]: `{ type }`
  - `bad-configuration`:
    - emitted when a required prop is not set
    - event.detail[0]: empty
  - `widget-unmounted`:
    - emitted when widget is mounted
    - event.detail[0]: `{ type }`
  - `click-card`:
    - emitted when a card id clicked
    - event.detail[0]: `{ type, datasetId, datafileRid }`
  - `label-selection-on-card`:
    - emitted when a label in a card is clicked
    - event.detail[0]: `{ card, type, value }`
  - `init`:
    - emitted when a pagination with new filter is initialized
    - event.detail[0]:

      ```js
      {
        itemsType,
        order: { field, sort },
        text,
        lastModified: { min, max },
        temporalCoverage: { from, to },
        topics,
        tags,
        frequencies,
        zones,
        granularities,
        licenses
      }
      ```

## Explore web component

- Default tag for registration: `dido-explore`
- Props:
  - `dido-url`:
    - url of DiDo api
    - required
  - `dido-filter`:
    - filter used for explore
    - required (you can pass {} for default value)
    - default value:

      ```json
      {
        "itemsType": "dataset",
        "order": { "field": "last_modified", "sort": "desc" },
        "text": "",
        "lastModified": { "max": "", "min": "" },
        "temporalCoverage": { "from": "", "to": "" },
        "topics": [],
        "tags": [],
        "licenses": [],
        "zones": [],
        "granularities": [],
        "frequencies": []
      }
      ```

- Events emitted
  - `widget-mounted`:
    - emitted when widget is mounted
    - event.detail[0]: `{ type }`
  - `bad-configuration`:
    - emitted when a required prop is not set
    - event.detail[0]: empty
  - `widget-unmounted`:
    - emitted when widget is mounted
    - event.detail[0]: `{ type }`
  - `click-card`:
    - emitted when a card id clicked
    - event.detail[0]: `{ type, datasetId, datafileRid }`
  - `label-selection-on-card`:
    - emitted when a label in a card is clicked
    - event.detail[0]: `{ card, type, value }`
  - `new-filter`:
    - emitted when a new filter is activated
    - event.detail[0]:

      ```js
      {
        itemsType,
        order: { field, sort },
        text,
        lastModified: { min, max },
        temporalCoverage: { from, to },
        topics,
        tags,
        frequencies,
        zones,
        granularities,
        licenses
      }
      ```

## Global apidoc web component

- Default tag for registration: `dido-apidoc`
- Props:
  - `dido-url`:
    - url of DiDo api
    - required
- Events emitted
  - `widget-mounted`:
    - emitted when widget is mounted
    - event.detail[0]: `{ type }`
  - `bad-configuration`:
    - emitted when a required prop is not set
    - event.detail[0]: empty
  - `widget-unmounted`:
    - emitted when widget is mounted
    - event.detail[0]: `{ type }`

## Catalog web component

- Default tag for registration: `dido-catalog`
- Props:
  - `dido-url`:
    - url of DiDo api
    - required
  - `dido-catalog-contact-url`:
    - url for contact point
    - not required (default: <https://statistiques.developpement-durable.gouv.fr/contact>)
  - `dido-linked-docs-url`:
    - url for linked docs from external api
    - schema for external api:

      ```json
      [
        {
          // the external id
          "nid": "5825",
          "type_dido": "dataset",
          "datasetid": "631b03afb61e5c6479370169",
          "datafileRid": "",
          "datafileMillesime": "",
          "created": "2023-05-05",
          // Url encoded
          "content_title": "Donn\u00e9es mensuelles de l\u0026#039;\u00e9nergie",
          // Url encoded
          "content_summary": "Principales donn\u00e9es mensuelles.......",
          // Url encoded
          "content_link": "https://www.statistiques.developpement-durable.gouv.fr/donnees-mensuelles-de-lenergie"
        }
      ]
      ```

    - not required (if not set linked docs functionnality is disabled)

  - `dido-initial-explore-url`:
    - not required
    - used for setting an initial filter in explore page when first loading and querystring in url is empty
    - format of string example:

      `type=datafile&pagination=1&sortField=title&sortOrder=desc&topics=Environnement&tags=territoire,indicateur&licenses=fr-lo&zones=country:fr&granularities=fr:commune&frequencies=annual`

  - `dido-message-service`:
    - not required
    - default value is false
    - used to activate the message service

  - `dido-message-service-type`:
    - not required
    - default value is primary
    - possible values are all [Quasar colors](https://quasar.dev/style/color-palette)
    - used for the color of the message service (used only if dido-message-service is true)

  - `dido-message-service-content`:
    - not required
    - default value is 'Un message de service'
    - used for the content of the service message

  - `dido-message-service-permanen`t
    - not required
    - default value is false
    - used to set the service message as permanent or dismissible

- Events emitted
  - `widget-mounted`:
    - emitted when widget is mounted
    - event.detail[0]: `{ type }`
  - `bad-configuration`:
    - emitted when a required prop is not set
    - event.detail[0]: empty
  - `widget-unmounted`:
    - emitted when widget is mounted
    - event.detail[0]: `{ type }`

- Scopes:
  - `didoMessageServiceContent`:
    - slot used for rich-text in service message.
    - supercharge attribute `dido-message-service-content`
    - examples:
      - a simple positive permanent message:

        ```html
        <dido-catalog
          dido-url="{your_dido_url_api}"
          dido-message-service
          dido-message-service-type="positive"
          dido-message-service-content="un simple message de service dans l'attribut dido-message-service-content de la balise dido-catalog"
          dido-message-service-permanent
        ></dido-catalog>
        ```

      - a riche negative dismissible message:

        ```html
        <dido-catalog
          dido-url="{your_dido_url_api}"
          dido-message-service
          dido-message-service-type="negative"
        >
          <p slot="didoMessageServiceContent">
            <style>
              .text-bold {
                font-weight: bold;
              }
              .text-uppercase {
                text-transform: uppercase;
              }
            </style>
            <span class="text-bold">Le titre du message en gras</span>
            <br /><br />
            On peut mettre tout le texte qui suit en majuscule :
            <span class="text-uppercase"
              >Ceci est un message enrichi qui provient du slot</span
            >
            didoMessageServiceContent
            <span class="text-uppercase">de la balise</span>
            <span class="text-uppercase">dido-catalog</span>
          </p>
        </dido-catalog>
        ```

---
_Source: https://npm.io/package/@cgdd-bun/dido-widgets · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._