@cityway/bo-ui 1.1.0-beta004 → 1.1.0-beta006

package/docs/components/export-button.md

@@ -0,0 +1,198 @@
+# `cw-export-button` — Bouton d'export
+
+> Lib : `@cityway/bo-ui` · Sélecteur : `cw-export-button` · Standalone : oui
+> Import : `import { ExportButtonComponent } from '@cityway/bo-ui';`
+
+---
+
+> ⚠️ **Prérequis d'intégration : `<cw-toast>` doit être monté dans le layout racine.**
+> Le toast d'échec passe par `ToastService`, dont la pile n'est rendue que par le conteneur
+> `<cw-toast>` de `basic-ui`. **Il n'est monté nulle part dans le template BO à ce jour** :
+> sans lui, un export qui échoue ne produit **aucun message visible**. À placer une seule
+> fois, typiquement dans le composant racine (cf. `basic-ui/docs/components/toast.md`).
+
+---
+
+## 1. Rôle & quand l'utiliser
+
+Bouton *Exporter* qui déclenche la production d'un fichier et le remet au navigateur.
+**Une seule option** → bouton simple ; **deux ou plus** → menu déroulant listant les options.
+
+Le composant **ne porte aucun métier** : il ne connaît ni le format exporté, ni la façon de
+nommer le fichier, ni ce qui est exporté. L'hôte sérialise et nomme (`ExportPayload`) ; la
+lib déclenche, restitue l'état et transporte. Conséquence : aucune dépendance à `xlsx`,
+`file-saver` ou quoi que ce soit d'autre — JSON, CSV, XLSX, PDF sont indifférents.
+
+À ne PAS utiliser pour : un import (`cw-import-button`), un simple lien de téléchargement
+vers une URL connue (`cw-file-to-download` de `basic-ui`).
+
+---
+
+## 2. API
+
+### Inputs
+
+| Input | Type | Défaut | Description |
+|-------|------|--------|-------------|
+| `options` | `ExportOptions` | — (**requis**) | Options proposées, dans l'ordre d'affichage. **Tuple non vide.** |
+| `label` | `I18nKey` | `_COMMON._ACTION.EXPORT` | Clé i18n du libellé du bouton (ou du menu). |
+| `errorKey` | `I18nKey` | `_COMMON._EXPORT.ERROR` | Clé i18n du message du toast d'échec. |
+| `successKey` | `I18nKey \| null` | `null` | Clé i18n d'un toast de succès. `null` → **aucun toast**. |
+
+Aucun output : ni le succès ni l'échec ne demandent d'action de l'hôte — l'export ne
+modifie rien, il n'y a donc rien à recharger.
+
+---
+
+## 3. Types
+
+```ts
+interface ExportPayload {
+  blob: Blob;        // contenu déjà sérialisé par l'hôte
+  filename: string;  // nom complet, extension comprise
+}
+
+interface ExportOption {
+  label: I18nKey;                        // clé i18n, traduite par le composant
+  fn: () => Observable<ExportPayload>;   // produit le fichier
+  disabled?: boolean;                    // [Option] désactive CETTE option seule
+}
+
+/** Tuple non vide : `[]` ne compile pas. */
+type ExportOptions = readonly [ExportOption, ...ExportOption[]];
+```
+
+### Ce que le type rend inexprimable
+
+| Configuration invalide | Empêchée par |
+|---|---|
+| Aucune option | tuple non vide `[ExportOption, ...ExportOption[]]` — le rendu « bouton simple » ne peut plus lire un `options[0]` absent |
+| Libellé d'option en texte déjà traduit | `label: I18nKey` — la conversion doit être écrite noir sur blanc |
+
+**Le type nominal `I18nKey` n'est pas une garantie de contenu** : il dit d'où vient la
+chaîne, pas ce qu'elle contient. `i18nKey('Tout exporter')` compile. Ce qu'il apporte : la
+conversion est explicite donc visible en revue, et on ne peut plus passer une **variable**
+de texte déjà localisé dans un champ de clé sans l'écrire.
+
+---
+
+## 4. Exemples
+
+### Deux options, dans l'en-tête de page
+
+```html
+<cw-page-header [title]="'DOMAIN.USERS.TITLE'" [actions]="[actionEnum.add]" (action)="onAction($event)">
+  <cw-export-button cwPageHeaderExport [options]="exportOptions" />
+</cw-page-header>
+```
+
+```ts
+import { buildFilename, ExportOptions, i18nKey, jsonBlob, todayIsoDate } from '@cityway/bo-ui';
+
+readonly exportOptions: ExportOptions = [
+  {
+    label: i18nKey('DOMAIN.USERS.EXPORT_ALL'),
+    fn: () => this.api.exportAll().pipe(
+      map(rows => ({
+        blob: jsonBlob(rows),
+        // Tout le métier de nommage est ICI : la lib n'en compose aucune partie.
+        filename: buildFilename(['utilisateurs', this.instance()?.code, todayIsoDate()], 'json'),
+      }))
+    ),
+  },
+  {
+    label: i18nKey('DOMAIN.USERS.EXPORT_FILTERED'),
+    fn: () => this.api.export(this.filters()).pipe(map(rows => ({ … }))),
+    // Un droit qui porte sur un périmètre, pas sur l'export entier.
+    disabled: !this.canExportFiltered(),
+  },
+];
+```
+
+### Export CSV / XLSX via `ExportService` de `bo-core`
+
+Le composant ne sérialise pas ; il consomme le blob que vous produisez. `ExportService`
+(`@cityway/bo-core`) télécharge lui-même via `file-saver` — pour l'utiliser ici, produisez
+le blob plutôt que de laisser le service l'enregistrer, ou construisez-le directement :
+
+```ts
+fn: () => this.api.exportAll().pipe(
+  map(rows => ({
+    blob: new Blob([toCsv(rows)], { type: 'text/csv;charset=utf-8' }),
+    filename: buildFilename(['tarifs', todayIsoDate()], 'csv'),
+  }))
+),
+```
+
+### Utilitaires fournis
+
+```ts
+downloadBlob(payload)            // utilisé par le composant ; disponible pour un usage direct
+jsonBlob(data)                   // Blob JSON indenté
+todayIsoDate()                   // 'YYYY-MM-DD', en heure LOCALE (pas toISOString, qui décale en UTC)
+buildFilename(parts, extension)  // ignore les fragments absents, sans tiret orphelin
+```
+
+---
+
+## 5. Notes d'intégration
+
+- **`<cw-toast>` doit être monté** — voir l'avertissement en tête de page.
+- **Pas d'interruption, pas d'annulation, délibérément.** Contrairement à l'import,
+  l'export **n'écrit rien** : un export abandonné n'a aucune conséquence sur l'intégrité
+  des données. Le traitement de l'interruption de `cw-import-wizard` ne s'applique pas
+  ici, et ce n'est **pas un oubli**. Ne l'« harmonisez » pas.
+- **Un seul export à la fois.** Un second clic pendant qu'un export est en vol est ignoré.
+  Ce garde-fou est dans le code et **pas** dans le rendu : `cw-button [isLoading]` ne pose
+  pas `[disabled]`, le bouton reste cliquable pendant tout l'export.
+- **Aucun spinner sur le bouton.** `[isLoading]` n'est pas utilisé : il injecte sa propre
+  région live `role="status"`, ce qui ferait deux régions concurrentes pour un seul
+  événement (et il n'existe de toute façon pas dans la branche `isDropdown`). L'état de
+  chargement est porté par la région du composant, cf. ci-dessous.
+- **Restitution (RGAA)** : le composant possède **une** région `role="status"`
+  *visually-hidden*, permanente dans le DOM, qui annonce successivement *Export en cours* →
+  *Export terminé, le téléchargement de « … » a démarré* / *L'export a échoué*.
+  - C'est une région live et non un déplacement de focus — à la différence de
+    `cw-import-wizard` — parce que l'export ne fait apparaître **aucun contenu** vers
+    lequel déplacer le focus : le téléchargement est une action du navigateur, invisible
+    dans le document.
+  - La région est **vidée puis réécrite au tour de boucle suivant** à chaque annonce : une
+    région `role="status"` n'est réannoncée que si son contenu change, et deux exports
+    synchrones successifs y écriraient deux fois la même phrase.
+  - Elle double le toast d'échec, qui n'est aujourd'hui **jamais annoncé** : la chaîne
+    `cw-toast` → `cw-toast-item` → `cw-alert` ne porte aucun `role` ni `aria-live`.
+- **Menu déroulant** : les items suivent le motif documenté de `basic-ui`
+  (`<button cwDropdownItem>` en direct — cf. `basic-ui/docs/components/button.md`). C'est
+  la classe `dropdown-item` posée par la directive sur la **cible du clic** qui permet à
+  `cw-button` de refermer son menu après la sélection. Un `<cw-button>` imbriqué ne la
+  porterait pas au bon endroit.
+- **Le menu entier ne se désactive** que si **toutes** les options sont `disabled`.
+- **Échec** : une erreur de l'observable, **et** une source qui complète sans rien émettre,
+  valent échec. Sans ce second cas, l'export se terminerait en silence — pas de fichier,
+  pas de message, bouton redevenu actif comme si tout allait bien.
+- **Succès sans toast par défaut** : le fichier qui se télécharge *est* le retour. N'ajoutez
+  `successKey` que si l'hôte veut un accusé explicite.
+- **Nommage du fichier** : entièrement à l'hôte. C'est ce qui garde le composant sans
+  métier — le code client, l'horodatage ou le périmètre n'ont pas à traverser la frontière
+  de la lib. `buildFilename` / `todayIsoDate` sont des aides, jamais appelées à votre place.
+- **i18n** : libellés sous `_COMMON._EXPORT.*` dans le bundle **bo-ui**
+  (`@cityway/bo-ui/lib/assets/i18n/common.{fr,en}.json`) — voir `bo-ui/docs/i18n.md`.
+  `_COMMON._ACTION.EXPORT` et les titres de toast (`_COMMON._ACTION_ERROR.LABEL`,
+  `_COMMON._ACTION_SUCCESS.LABEL`) viennent de **basic-ui**.
+- **Limite connue de `ToastService`** : deux messages identiques émis à moins d'une seconde
+  d'intervalle sont dédupliqués — le second est avalé. Le garde-fou anti-double-clic couvre
+  le cas courant.
+
+---
+
+## 6. Prompts-types (génération assistée)
+
+- « Ajoute un bouton d'export CSV sur la page tarifs, avec deux options : tout, et la vue filtrée. »
+- « Branche l'export de la liste utilisateurs sur `cw-export-button`, fichier JSON nommé avec le code client et la date. »
+- « Désactive l'option "tout exporter" quand l'utilisateur n'a pas le droit correspondant. »
+
+**Rappels pour Claude :**
+- `options` est un **tuple non vide**. `label` est une **clé** (`i18nKey(...)`), pas du texte.
+- `fn()` doit renvoyer un `ExportPayload` — **l'hôte sérialise et nomme**. Ne jamais ajouter de dépendance de format dans la lib.
+- Ne **pas** poser `[isLoading]` sur le bouton, ni ajouter un bouton d'annulation d'export.
+- Vérifier que `<cw-toast>` est monté dans le layout de l'application.

package/docs/components/import-button.md

@@ -0,0 +1,134 @@
+# `cw-import-button` — Bouton d'import
+
+> Lib : `@cityway/bo-ui` · Sélecteur : `cw-import-button` · Standalone : oui
+> Import : `import { ImportButtonComponent } from '@cityway/bo-ui';`
+
+---
+
+## 1. Rôle & quand l'utiliser
+
+Bouton *Importer* qui ouvre `cw-import-wizard` dans une modale **sidepanel**. C'est la façon
+standard de déclencher un import — inutile de recâbler `ModalsService` à la main.
+
+Le composant **n'ajoute aucun contrat** : il transporte l'`ImportWizardConfig` de l'hôte
+**tel quel** jusqu'à l'assistant. Pas de type miroir, pas de champ recopié — toute évolution
+de `cw-import-wizard` est disponible ici sans modification symétrique.
+
+Ce qu'il apporte, et qui serait sinon réécrit dans chaque page :
+- le `ng-template` du corps de modale et l'ouverture au bon type ;
+- l'absence de `labelBtnAction1`/`2` (un bouton d'action au pied **fermerait** la modale) ;
+- la **séparation des deux signaux de sortie** que la SFD de l'assistant impose de ne pas
+  confondre (§4).
+
+Pour tout ce qui concerne le parcours lui-même — étapes, modes, analyse, interruption,
+rapport —, la référence est **`import-wizard.md`**.
+
+---
+
+## 2. API
+
+### Inputs
+
+| Input | Type | Défaut | Description |
+|-------|------|--------|-------------|
+| `config` | `ImportWizardConfig` | — (**requis**) | Paramétrage de l'assistant, transmis tel quel. Voir `import-wizard.md` §3. |
+| `modalTitle` | `I18nKey` | — (**requis**) | Clé i18n du titre de la modale. |
+| `label` | `I18nKey` | `_COMMON._ACTION.IMPORT` | Clé i18n du libellé du bouton. |
+| `disabled` | `boolean` | `false` | Désactive le bouton (droit utilisateur). |
+
+### Outputs
+
+| Output | Payload | Description |
+|--------|---------|-------------|
+| `closed` | `void` | Modale fermée, **par n'importe quel chemin**. → l'hôte **recharge** ici. |
+| `completed` | `ImportOutcome` | État terminal de l'assistant. → message, journalisation, action métier. |
+
+---
+
+## 3. Exemple
+
+```html
+<cw-page-header [title]="'DOMAIN.USERS.TITLE'" [actions]="[actionEnum.add]" (action)="onAction($event)">
+  <cw-import-button
+    cwPageHeaderImport
+    [config]="importConfig"
+    [modalTitle]="importTitle"
+    (closed)="reload()"
+    (completed)="onImported($event)" />
+</cw-page-header>
+```
+
+```ts
+import {
+  i18nKey, ImportEventKindEnum, ImportInterruptionEnum, ImportModeEnum, ImportOutcome,
+  ImportButtonComponent, ImportWizardConfig
+} from '@cityway/bo-ui';
+
+readonly importTitle = i18nKey('DOMAIN.USERS.IMPORT_TITLE');
+
+readonly importConfig: ImportWizardConfig = {
+  accept: '.csv,.xlsx',
+  acceptLabel: 'CSV, XLSX',
+  maxSizeBytes: 10 * 1024 * 1024,
+  modes: [
+    { mode: ImportModeEnum.addOnly, keyFieldHint: i18nKey('DOMAIN.USERS.IMPORT_DUPLICATE_HINT') },
+    { mode: ImportModeEnum.upsert, keyFieldHint: i18nKey('DOMAIN.USERS.IMPORT_KEY_HINT') },
+  ],
+  showErrorDetails: true,
+  interruption: { kind: ImportInterruptionEnum.serverCancel, cancel: ctx => this.api.cancel(ctx) },
+  source: {
+    analyze: (file, mode) => this.api.dryRun(file, mode),
+    execute: (file, mode, ctx) => this.api.run(file, mode, ctx),
+  },
+};
+
+// Signal de RÉSULTAT : uniquement ce qui dépend de l'issue. On NE FERME PAS la modale ici,
+// l'utilisateur doit pouvoir lire son rapport.
+onImported(outcome: ImportOutcome): void {
+  if (outcome.kind === ImportEventKindEnum.report && outcome.success) {
+    this.toaster.success('DOMAIN.USERS.IMPORT_DONE');
+  }
+}
+```
+
+---
+
+## 4. Notes d'intégration
+
+- **Rechargez sur `(closed)`, pas sur `(completed)`.** C'est la règle centrale, reprise de
+  `import-wizard.md` §5. `closed` est émis à **tous** les chemins de fermeture — croix,
+  Échap, clic sur le fond, bouton *Fermer* du pied — y compris la fermeture **pendant** un
+  import, cas où `completed` n'a jamais été émis alors que des données ont pu être écrites.
+  Le composant traite les **deux** issues de la promesse de `ModalsService` (résolution
+  comme rejet) : le rejet est ainsi marqué comme géré, et si un chemin de fermeture venait
+  à la résoudre, le rechargement partirait quand même.
+- **`completed` est le signal de RÉSULTAT** : message de confirmation, journalisation,
+  action métier. Émis à tout état terminal — succès, échec, interruption — mais il ne voit
+  pas la fermeture, donc il ne peut pas porter le rechargement.
+- **Ne fermez pas la modale** dans le gestionnaire de `completed` : l'utilisateur doit
+  pouvoir lire son rapport, en particulier un rapport d'interruption en état incertain. Le
+  composant n'expose d'ailleurs aucune sortie de fermeture.
+- **Aucun bouton d'action au pied.** Le composant ne passe pas `labelBtnAction1`/`2` : le
+  pied par défaut rend exactement le *Fermer* attendu, et tout bouton d'action configuré
+  **fermerait** la modale.
+- **Placement** : dans le slot `cwPageHeaderImport` de `cw-page-header`, qui le rend à la
+  position habituelle du bouton *Importer*. Il fonctionne aussi seul, hors en-tête.
+  L'import **n'est pas** une valeur de `PageHeaderActionEnum` : le rendre depuis
+  `cw-page-header` obligerait celui-ci à référencer l'assistant, donc à l'embarquer dans
+  toute page affichant un titre — ng-packagr aplatit la lib en un FESM unique, un `@defer`
+  n'y change rien.
+- **i18n** : `_COMMON._ACTION.IMPORT` vient de **basic-ui** ; les libellés de l'assistant
+  sont sous `_COMMON._IMPORT.*` dans le bundle **bo-ui**.
+
+---
+
+## 5. Prompts-types (génération assistée)
+
+- « Branche le bouton *Importer* de la page utilisateurs sur `cw-import-button`, formats CSV/XLSX, 10 Mo max, modes ajout et mise à jour. »
+- « Ajoute l'import de configuration en écrasement complet dans l'en-tête de la page paramètres. »
+
+**Rappels pour Claude :**
+- Recharger sur `(closed)`, **jamais** sur `(completed)`. Ne jamais fermer la modale depuis `completed`.
+- `config` est un `ImportWizardConfig` **complet** : voir `import-wizard.md` §3 pour ses règles (tuple `modes`, `interruption` requis, `keyFieldHint`).
+- `modalTitle` et `label` sont des **clés** (`i18nKey(...)`), pas du texte.
+- Ne pas rouvrir `ModalsService` à la main pour un import : c'est ce composant qui le fait.