@cityway/bo-ui 1.1.0-beta016 → 1.1.0-beta018

package/docs/components/drag-n-drop-nested-list.md

@@ -45,6 +45,7 @@ Liste hiérarchique réordonnable par glisser-déposer (CDK drag-drop), pilotée
 | `delete` | `DragItem` | Clic sur l'action « supprimer » (corbeille) — sur une carte **non** `pendingDelete`. |
 | `restore` | `DragItem` | Clic sur « Restaurer » — sur une carte `pendingDelete` (la corbeille bascule en restauration). |
 | `add` | `DragAddEvent` | Clic sur un lien « Ajouter » (racine ou pied de carte). Payload : `{ parent?: DragItem; depth: number }` (`parent` = `undefined` à la racine). |
+| `expandedChange` | `{ item: DragItem; expanded: boolean }` | L'utilisateur a plié / déplié une carte (chevron). À refléter dans `DragItem.expanded` pour que l'état survive au prochain `items`. **Jamais émis** pour un état posé par l'hôte (`expanded`, `expandSelected`). |
 
 ### Contenu projeté (corps de carte custom)
 
@@ -72,7 +73,9 @@ interface DragItem {
   label: string;                  // libellé (fallback de title dans l'en-tête)
   code?: string;                  // affiché seul dans le corps quand il n'y a pas d'itemTemplate
   order?: number;                 // position 1..n (renumérotée si reorderOnDrop)
-  disabled?: boolean;             // verrouille le drag de CETTE carte (poignée inactive)
+  disabled?: boolean;             // verrouille le drag de CETTE carte (poignée affichée, inactive)
+  sortable?: boolean;             // false : ordre non manipulable, AUCUNE poignée (défaut column.sortable → true)
+  expanded?: boolean;             // état déplié voulu par l'hôte, réappliqué à chaque nouvel `items` (undefined : replié au départ)
   children?: DragItem[];          // sous-arbre
 
   title?: string;                 // titre de la carte (fallback sur label)
@@ -108,6 +111,8 @@ interface DragListColumn {
   cssClass?: string;              // classe sur chaque <ul> de niveau
 
   collapsible?: boolean;          // cartes pliables (défaut true) ; false désactive globalement
+  sortable?: boolean;             // défaut de DragItem.sortable ; false = liste à ordre fixe (aucune poignée)
+  expandSelected?: boolean;       // déplie les ancêtres de la carte selectedId (prime sur DragItem.expanded)
   showView?: boolean;             // visibilité par défaut des actions (surchargée par DragItem.actions)
   showEdit?: boolean;
   showDelete?: boolean;
@@ -132,6 +137,8 @@ interface DragAddEvent {
 
 - **Ajout** (`canAdd`) : `item.actions.add` → `column.showAdd` → `depth < maxDepth` (si `maxDepth` défini) → `true`. Indépendant de la présence d'enfants (une carte vide reste addable).
 - **Actions view/edit/delete** (`showAction`) : `item.actions[action]` → `column.show{View|Edit|Delete}` → `true`.
+- **Triable** (`isSortable`) : `item.sortable` → `column.sortable` → `true`. Non triable : poignée **non rendue** et drag désactivé. Distinct de `disabled` (poignée affichée mais inerte) ; `disabled` et `pendingDelete` n'ont pas d'effet supplémentaire sur une carte non triable.
+- **Déplié** (`isCollapsedCard`) : dernier état connu de la carte, mis à jour par le chevron (utilisateur), par `item.expanded` à chaque nouvelle valeur de `items`, puis par `column.expandSelected` (ancêtres de `selectedId` dépliés, à chaque changement de sélection ou d'`items`) ; à défaut, une carte pliable démarre repliée. L'état est indexé par `id` : une carte dont l'`id` change (id définitif après enregistrement) repart de zéro, d'où l'intérêt de lui passer `expanded`.
 - **Pliable** (`isCollapsible`) : faux si `pendingDelete` ou `column.collapsible === false` ; sinon vrai si la carte a des enfants OU peut en recevoir.
 - **Niveau plein** (`isLevelFull`) : vrai si `maxItemsByDepth[depth]` défini et atteint (`excludePendingDeleteFromMax` exclut les marqués du décompte).
 
@@ -200,6 +207,43 @@ items: DragItem[] = [
 ];
 ```
 
+### Liste à ordre fixe (`sortable: false`)
+
+```ts
+// L'ordre n'est pas manuel (ex. trié côté API) : aucune poignée rendue, aucun drag.
+// Le reste fonctionne (sélection, édition, suppression différée, ajout, sous-niveaux).
+column: DragListColumn = { title: 'Seuils de zoom', sortable: false };
+
+// Ou carte par carte (l'item prime sur la colonne) :
+items: DragItem[] = [
+  { id: 1, label: 'Racine', sortable: false, children: [
+    { id: 11, label: 'Enfant réordonnable' },  // hérite de la colonne → triable
+  ] },
+];
+```
+
+> `disabled` ≠ `sortable: false` : `disabled` = « déplaçable en principe, verrouillé pour l'instant » (poignée affichée, inerte) ; `sortable: false` = « cet ordre ne se manipule pas » (pas de poignée).
+
+### Dépliage piloté par l'hôte (`expanded`, `expandSelected`)
+
+```html
+<cw-drag-n-drop-nested-list [items]="items" [column]="column" [selectedId]="selectedId"
+  (expandedChange)="onExpandedChange($event)" />
+```
+
+```ts
+// La sélection (ex. un enfant désigné par une erreur d'enregistrement) est toujours visible.
+column: DragListColumn = { title: 'Seuils', expandSelected: true };
+
+// Tout déplier : nouvel `items` avec `expanded` (réappliqué à chaque nouvelle valeur).
+expandAll() { this.items = this.items.map(i => ({ ...i, expanded: true })); }
+
+// Refléter les choix de l'utilisateur, pour qu'ils survivent au prochain rechargement.
+onExpandedChange({ item, expanded }: { item: DragItem; expanded: boolean }) {
+  this.items = this.items.map(i => i.id === item.id ? { ...i, expanded } : i);
+}
+```
+
 ### Nombre max par niveau (`maxItemsByDepth`)
 
 ```ts
@@ -296,6 +340,8 @@ onReorder(items: DragItem[]) { this.items = items; }
 - « Limite les rubriques à 3 par thème (`maxItemsByDepth: { 1: 3 }`) avec un message d'alerte i18n quand le max est atteint. »
 - « Ajoute un soft-delete : *Supprimer* marque la carte (`pendingDelete`), *Restaurer* l'annule ; sélection exclusive de la carte en cours d'édition via `selectedId`. »
 - « Affiche un corps de carte custom (titre + niveau) via `itemTemplate`, en gardant l'en-tête data-driven. »
+- « Garde mes sections dépliées après enregistrement et ouvre automatiquement le parent de la carte en erreur (`expanded` + `expandSelected`). »
+- « Ma liste de seuils est triée par l'API : retire les poignées de drag (`column.sortable: false`) en gardant édition et suppression. »
 - « Rends la *Section A* non déplaçable (`disabled`) et masque l'action *supprimer* sur les feuilles via `DragItem.actions`. »
 
 **Rappels pour Claude :**

package/docs/components/filter-bar.md

@@ -151,7 +151,7 @@ filters: FilterFieldConfig[] = [
 
 ## 5. Notes d'intégration
 
-- **i18n** : `label`, `placeholder`, `applyLabel`, `resetLabel` passent par `translate` → fournir des **clés**, pas du texte en dur.
+- **i18n** : `label`, `placeholder`, `applyLabel`, `resetLabel` passent par `translate` → fournir des **clés**, pas du texte en dur. La traduction est faite **une seule fois**, par `cw-form-field` et `cw-button` : la filter-bar leur transmet les clés telles quelles (jusqu'à la beta016 elle les traduisait aussi, d'où une double traduction, fausse quand un libellé traduit coïncidait avec une clé).
 - **`key`** sert à la fois de nom de `FormControl`, de clé dans `FilterValues` et de nom de query param. Pour une plage, l'URL utilise `key.start` / `key.end`.
 - **Mode auto vs manuel** : en auto, `filtersApplied` est émis à chaque frappe (anti-rebond 300 ms). En manuel, seuls *Appliquer* (et le *reset*) déclenchent l'émission.
 - **`syncUrl`** : nécessite que l'app fournisse le `Router` (sinon dégradation silencieuse) ; écriture en `replaceUrl: true` (l'historique n'est pas pollué) et `queryParamsHandling: 'merge'` (préserve les autres params, ex. pagination). Les valeurs vides sont retirées de l'URL.

package/docs/components/page-header.md

@@ -1,238 +1,238 @@
-# `cw-page-header` — En-tête de page
-
-> Lib : `@cityway/bo-ui` · Sélecteur : `cw-page-header` · Standalone : oui
-> Import : `import { PageHeaderComponent } from '@cityway/bo-ui';`
-
----
-
-## 1. Rôle & quand l'utiliser
-
-En-tête de page transverse du back-office. Couvre :
-
-- **titre** de page (`<h1>`) + **description** optionnelle ;
-- **bouton retour** (navigue via `Location.back()`) ;
-- une barre d'**actions normalisées** (Ajouter, Enregistrer, Réinitialiser) déclarées par configuration ;
-- deux **slots dédiés** pour l'import et l'export, aux positions attendues (§2 bis) ;
-- états **loading** et **disabled** par action ;
-- un emplacement de **contenu projeté** pour des actions personnalisées.
-
-À ne PAS utiliser pour : un titre de section interne (utiliser un simple `<h2>`), une barre d'outils de tableau (filtres, pagination — composants dédiés).
-
----
-
-## 2. API
-
-### Inputs
-
-| Input | Type | Défaut | Description |
-|-------|------|--------|-------------|
-| `title` | `string` | — (**requis**) | Titre de la page. Passé au pipe `translate` (fournir une **clé i18n**). |
-| `description` | `string` | — | Description sous le titre. Passée au pipe `translate`, rendue en `[innerHTML]` (HTML autorisé). |
-| `showBack` | `boolean` | `true` | Affiche le bouton retour (libellé `_COMMON._FORM.BACK`, icône `left1`). |
-| `actions` | `PageHeaderActionEnum[]` | `[]` | Liste des actions à afficher. Voir enum §3. L'ordre d'affichage est imposé par le template (cf. §5). |
-| `isLoading` | `PageHeaderActionState` | `{}` | Map action → `boolean` ; passe l'action en état chargement. |
-| `isDisabled` | `PageHeaderActionState` | `{}` | Map action → `boolean` ; désactive l'action. |
-| `columns` | `TableColumn[]` | `[]` | Colonnes du tableau associé. **Fourni → un menu déroulant « Colonnes » apparaît** (cases à cocher afficher/masquer). Voir §6 bis. |
-| `storageKey` | `string` | — | Identifiant **stable** du tableau pour persister l'état en localStorage (ex. `'users/list'`). Sans clé : le menu fonctionne mais l'état n'est pas mémorisé. |
-| `columnsLabel` | `string` | `_COMMON._TABLE.COLUMNS` | Clé i18n du libellé du bouton « Colonnes ». |
-
-### Outputs
-
-| Output | Payload | Description |
-|--------|---------|-------------|
-| `action` | `PageHeaderActionEnum` | Émis au clic sur une action de la barre. Le bouton retour n'émet pas (géré en interne). |
-| `columnsChange` | `TableColumn[]` | Émis quand la visibilité des colonnes change (colonnes avec `hidden` à jour). À renvoyer dans le `signal`/state lié à la `cw-table`. |
-
----
-
-## 2 bis. Slots de projection
-
-Trois emplacements, dans l'ordre du template :
-
-| Slot | Sélecteur | Position dans la barre | Usage |
-|------|-----------|------------------------|-------|
-| Import | `cwPageHeaderImport` | après *Colonnes*, avant *Réinitialiser* | `<cw-import-button>` |
-| Export | `cwPageHeaderExport` | après *Réinitialiser*, avant le slot libre | `<cw-export-button>` |
-| Libre | *(aucun)* | après l'export, avant *Ajouter* / *Enregistrer* | tout le reste |
-
-```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-export-button cwPageHeaderExport [options]="exportOptions" />
-  <!-- Slot libre : action personnalisée, ou bouton d'export entièrement piloté par l'hôte. -->
-  <cw-button [type]="boButtonType.secondary" [label]="'DOMAIN.USERS.INVITE'" (btnAction)="invite()" />
-</cw-page-header>
-```
-
-**Pourquoi des slots et pas des inputs de configuration ?** Rendre l'import depuis
-`cw-page-header` l'obligerait à référencer `cw-import-wizard`, donc à embarquer l'assistant
-complet (avec `file-drop`, `accordion`, `card`, `progress-bar`) dans **toute** page affichant
-un titre. Un `@defer` n'y change rien : ng-packagr aplatit la lib en un **FESM unique**, la
-dépendance différée y est réécrite en `Promise.resolve()` sur un objet du même bundle — il
-n'y a aucun `import()` sur lequel un bundler pourrait découper. Par projection, une page qui
-n'importe ni n'exporte ne charge **rien** des deux composants, et une page qui exporte
-seulement ne charge rien de l'assistant d'import.
-
-**Le slot libre est l'échappatoire** : un hôte qui veut piloter lui-même son bouton
-d'export — sans passer par le contrat `ExportPayload` — y pose son propre `cw-button`.
-
----
-
-## 3. Enums & Types
-
-```ts
-enum PageHeaderActionEnum {
-  add   = 'add',
-  save  = 'save',
-  reset = 'reset'
-}
-
-// Map partielle action → booléen, pour piloter loading / disabled par action
-type PageHeaderActionState = Partial<Record<PageHeaderActionEnum, boolean>>;
-```
-
-> ⚠️ **Migration** — `import`, `exportCurrent` et `exportAll` **ont été retirés** de l'enum.
-> Ils ne rendaient qu'un bouton émettant un événement, tout le travail restant à l'hôte.
-> Remplacez-les par les composants dédiés, projetés dans les slots (§2 bis) :
->
-> | Avant | Après |
-> |-------|-------|
-> | `actions: [actionEnum.import]` + `case import:` | `<cw-import-button cwPageHeaderImport …>` |
-> | `actions: [actionEnum.exportCurrent, actionEnum.exportAll]` + `case export…:` | `<cw-export-button cwPageHeaderExport [options]="…">` |
-> | un bouton d'export entièrement piloté par l'hôte | votre `cw-button` dans le slot libre |
->
-> Il n'y a **pas** de règle de précédence : les deux chemins n'ont jamais coexisté, le retrait
-> est net et le compilateur signale chaque usage restant.
-
----
-
-## 4. Exemples
-
-### Page liste (Ajouter + Import + Export)
-
-```html
-<cw-page-header
-  [title]="'DOMAIN.USERS.TITLE'"
-  [description]="'DOMAIN.USERS.SUBTITLE'"
-  [actions]="[actionEnum.add]"
-  (action)="onAction($event)">
-  <cw-import-button cwPageHeaderImport [config]="importConfig" [modalTitle]="importTitle"
-    (closed)="reload()" (completed)="onImported($event)" />
-  <cw-export-button cwPageHeaderExport [options]="exportOptions" />
-</cw-page-header>
-```
-
-```ts
-import {
-  ExportButtonComponent, ImportButtonComponent, PageHeaderActionEnum, PageHeaderComponent
-} from '@cityway/bo-ui';
-
-// dans le composant hôte
-actionEnum = PageHeaderActionEnum;
-
-onAction(action: PageHeaderActionEnum): void {
-  switch (action) {
-    case PageHeaderActionEnum.add: this.create(); break;
-  }
-}
-```
-
-Configuration de `importConfig` / `exportOptions` : voir `import-button.md` et
-`export-button.md`.
-
-### Page édition (Enregistrer + Réinitialiser) avec états
-
-```html
-<cw-page-header
-  [title]="'DOMAIN.USERS.EDIT_TITLE'"
-  [description]="'DOMAIN.USERS.EDIT_SUBTITLE'"
-  [actions]="[actionEnum.reset, actionEnum.save]"
-  [isLoading]="{ save: saving() }"
-  [isDisabled]="{ reset: form.pristine }"
-  (action)="onAction($event)">
-</cw-page-header>
-```
-
-### Titre seul (sans retour, sans action)
-
-```html
-<cw-page-header [title]="'DOMAIN.DASHBOARD.TITLE'" [showBack]="false" />
-```
-
-### Action personnalisée projetée
-
-```html
-<cw-page-header [title]="'DOMAIN.REPORTS.TITLE'" [actions]="[]">
-  <cw-button [type]="boButtonType.secondary" [label]="'DOMAIN.REPORTS.SCHEDULE'" (btnAction)="schedule()" />
-</cw-page-header>
-```
-
----
-
-## 4 bis. Menu « Colonnes » (visibilité + persistance)
-
-Quand on passe `columns` au page-header, un bouton **Colonnes** apparaît : un dropdown de cases à cocher pour afficher/masquer chaque colonne du tableau associé. L'état (colonnes masquées) est **persisté en localStorage** par tableau.
-
-```ts
-import { PageHeaderComponent, TableComponent, TableColumn } from '@cityway/bo-ui';
-
-@Component({
-  standalone: true,
-  imports: [PageHeaderComponent, TableComponent],
-  template: `
-    <cw-page-header
-      [title]="'DOMAIN.USERS.TITLE'"
-      [columns]="columns()"
-      storageKey="users/list"
-      (columnsChange)="columns.set($event)">
-    </cw-page-header>
-
-    <cw-table [columns]="columns()" [data]="rows()"></cw-table>
-  `,
-})
-export class UsersPage {
-  // Source de vérité unique, liée au header (contrôle) ET à la table (rendu).
-  columns = signal<TableColumn[]>([
-    { key: 'name',  label: 'DOMAIN.USERS.NAME' },
-    { key: 'email', label: 'DOMAIN.USERS.EMAIL' },
-    { key: 'createdAt', label: 'DOMAIN.USERS.CREATED', hidden: true }, // masquée par défaut
-    { key: 'actions', label: '', type: 'actions' },                    // jamais masquable
-  ]);
-}
-```
-
-Règles :
-- **Activation** : le menu n'apparaît que si `columns` contient au moins une colonne masquable. Sans `columns`, pas de menu.
-- **Colonnes exclues** : `type='actions'` (jamais masquable) et toute colonne `hideable: false`.
-- **Garde-fou** : impossible de masquer la **dernière** colonne masquable visible (sa case est désactivée).
-- **Persistance** : une seule clé localStorage `cw-table-columns` → `{ [storageKey]: string[] }`, **on ne stocke que les clés des colonnes masquées**. Au chargement, l'état mémorisé prime sur les `hidden` du config ; **sans `storageKey`**, le menu fonctionne mais rien n'est mémorisé.
-- **Helpers** : `loadHiddenColumns(storageKey)` / `saveHiddenColumns(storageKey, keys)` exportés par `@cityway/bo-ui` (le page-header les utilise en interne).
-
----
-
-## 5. Notes d'intégration
-
-- **i18n** : `title` et `description` passent par `translate` → fournir des **clés**, pas du texte en dur. `description` est rendue en `[innerHTML]` (peut contenir du HTML/markup traduit).
-- **Libellés des actions** : non paramétrables. Ils sont câblés sur les clés `_COMMON._ACTION.*` (`ADD`, `SAVE`, `RESET`) et `_COMMON._FORM.BACK` pour le retour. Ces clés doivent exister dans les bundles i18n de l'app.
-- **Ordre d'affichage** : imposé par le template, indépendant de l'ordre du tableau `actions` et de l'ordre d'écriture du contenu projeté → Colonnes, *slot import*, Réinitialiser, *slot export*, *slot libre*, Ajouter, Enregistrer.
-- **Bouton retour** : navigue via `Location.back()` (historique du navigateur). Aucune sortie ni cible configurable ; masquer avec `[showBack]="false"` si non pertinent.
-- **États par action** : `isLoading` / `isDisabled` sont des maps partielles ; une action absente de la map vaut `false`.
-- **Dépendance** : le composant projette des `cw-button` (`@cityway/basic-ui`) en interne — `basic-ui` doit être disponible.
-
----
-
-## 6. Prompts-types (génération assistée)
-
-> Exemples de formulation pour demander à Claude de générer du code consommant ce composant.
-
-- « Ajoute un `cw-page-header` titre *Utilisateurs* (clé i18n) avec bouton retour et action Ajouter, qui route vers `onAction()`. »
-- « Sur ma page d'édition, mets un en-tête avec Enregistrer + Réinitialiser, où Enregistrer affiche un spinner pendant la sauvegarde et Réinitialiser est désactivé tant que le formulaire est vierge. »
-- « Ajoute un menu Export (tout + vue filtrée) dans l'en-tête de la page liste. »
-
-**Rappels pour Claude :**
-- Importer `PageHeaderComponent` (standalone) dans les `imports` du composant hôte.
-- Exposer `PageHeaderActionEnum` comme propriété du composant pour la binder dans le template (`actionEnum = PageHeaderActionEnum`).
-- Utiliser des clés i18n pour `title` et `description` ; les libellés des actions sont fixes (clés `_COMMON._ACTION.*`).
-- Piloter `isLoading` / `isDisabled` via des objets `{ [action]: boolean }` plutôt que des flags séparés.
-- **L'import et l'export ne sont pas des `actions`** : projeter `<cw-import-button cwPageHeaderImport>` et `<cw-export-button cwPageHeaderExport>` (cf. `import-button.md`, `export-button.md`). Ne jamais réintroduire ces valeurs dans `PageHeaderActionEnum`.
+# `cw-page-header` — En-tête de page
+
+> Lib : `@cityway/bo-ui` · Sélecteur : `cw-page-header` · Standalone : oui
+> Import : `import { PageHeaderComponent } from '@cityway/bo-ui';`
+
+---
+
+## 1. Rôle & quand l'utiliser
+
+En-tête de page transverse du back-office. Couvre :
+
+- **titre** de page (`<h1>`) + **description** optionnelle ;
+- **bouton retour** (navigue via `Location.back()`) ;
+- une barre d'**actions normalisées** (Ajouter, Enregistrer, Réinitialiser) déclarées par configuration ;
+- deux **slots dédiés** pour l'import et l'export, aux positions attendues (§2 bis) ;
+- états **loading** et **disabled** par action ;
+- un emplacement de **contenu projeté** pour des actions personnalisées.
+
+À ne PAS utiliser pour : un titre de section interne (utiliser un simple `<h2>`), une barre d'outils de tableau (filtres, pagination — composants dédiés).
+
+---
+
+## 2. API
+
+### Inputs
+
+| Input | Type | Défaut | Description |
+|-------|------|--------|-------------|
+| `title` | `string` | — (**requis**) | Titre de la page. Passé au pipe `translate` (fournir une **clé i18n**). |
+| `description` | `string` | — | Description sous le titre. Passée au pipe `translate`, rendue en `[innerHTML]` (HTML autorisé). |
+| `showBack` | `boolean` | `true` | Affiche le bouton retour (libellé `_COMMON._FORM.BACK`, icône `left1`). |
+| `actions` | `PageHeaderActionEnum[]` | `[]` | Liste des actions à afficher. Voir enum §3. L'ordre d'affichage est imposé par le template (cf. §5). |
+| `isLoading` | `PageHeaderActionState` | `{}` | Map action → `boolean` ; passe l'action en état chargement. |
+| `isDisabled` | `PageHeaderActionState` | `{}` | Map action → `boolean` ; désactive l'action. |
+| `columns` | `TableColumn[]` | `[]` | Colonnes du tableau associé. **Fourni → un menu déroulant « Colonnes » apparaît** (cases à cocher afficher/masquer). Voir §6 bis. |
+| `storageKey` | `string` | — | Identifiant **stable** du tableau pour persister l'état en localStorage (ex. `'users/list'`). Sans clé : le menu fonctionne mais l'état n'est pas mémorisé. |
+| `columnsLabel` | `string` | `_COMMON._TABLE.COLUMNS` | Clé i18n du libellé du bouton « Colonnes ». |
+
+### Outputs
+
+| Output | Payload | Description |
+|--------|---------|-------------|
+| `action` | `PageHeaderActionEnum` | Émis au clic sur une action de la barre. Le bouton retour n'émet pas (géré en interne). |
+| `columnsChange` | `TableColumn[]` | Émis quand la visibilité des colonnes change (colonnes avec `hidden` à jour). À renvoyer dans le `signal`/state lié à la `cw-table`. |
+
+---
+
+## 2 bis. Slots de projection
+
+Trois emplacements, dans l'ordre du template :
+
+| Slot | Sélecteur | Position dans la barre | Usage |
+|------|-----------|------------------------|-------|
+| Import | `cwPageHeaderImport` | après *Colonnes*, avant l'export | `<cw-import-button>` |
+| Export | `cwPageHeaderExport` | après l'import, avant le slot libre | `<cw-export-button>` |
+| Libre | *(aucun)* | après l'export, avant *Réinitialiser* | tout le reste |
+
+```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-export-button cwPageHeaderExport [options]="exportOptions" />
+  <!-- Slot libre : action personnalisée, ou bouton d'export entièrement piloté par l'hôte. -->
+  <cw-button [type]="boButtonType.secondary" [label]="'DOMAIN.USERS.INVITE'" (btnAction)="invite()" />
+</cw-page-header>
+```
+
+**Pourquoi des slots et pas des inputs de configuration ?** Rendre l'import depuis
+`cw-page-header` l'obligerait à référencer `cw-import-wizard`, donc à embarquer l'assistant
+complet (avec `file-drop`, `accordion`, `card`, `progress-bar`) dans **toute** page affichant
+un titre. Un `@defer` n'y change rien : ng-packagr aplatit la lib en un **FESM unique**, la
+dépendance différée y est réécrite en `Promise.resolve()` sur un objet du même bundle — il
+n'y a aucun `import()` sur lequel un bundler pourrait découper. Par projection, une page qui
+n'importe ni n'exporte ne charge **rien** des deux composants, et une page qui exporte
+seulement ne charge rien de l'assistant d'import.
+
+**Le slot libre est l'échappatoire** : un hôte qui veut piloter lui-même son bouton
+d'export — sans passer par le contrat `ExportPayload` — y pose son propre `cw-button`.
+
+---
+
+## 3. Enums & Types
+
+```ts
+enum PageHeaderActionEnum {
+  add   = 'add',
+  save  = 'save',
+  reset = 'reset'
+}
+
+// Map partielle action → booléen, pour piloter loading / disabled par action
+type PageHeaderActionState = Partial<Record<PageHeaderActionEnum, boolean>>;
+```
+
+> ⚠️ **Migration** — `import`, `exportCurrent` et `exportAll` **ont été retirés** de l'enum.
+> Ils ne rendaient qu'un bouton émettant un événement, tout le travail restant à l'hôte.
+> Remplacez-les par les composants dédiés, projetés dans les slots (§2 bis) :
+>
+> | Avant | Après |
+> |-------|-------|
+> | `actions: [actionEnum.import]` + `case import:` | `<cw-import-button cwPageHeaderImport …>` |
+> | `actions: [actionEnum.exportCurrent, actionEnum.exportAll]` + `case export…:` | `<cw-export-button cwPageHeaderExport [options]="…">` |
+> | un bouton d'export entièrement piloté par l'hôte | votre `cw-button` dans le slot libre |
+>
+> Il n'y a **pas** de règle de précédence : les deux chemins n'ont jamais coexisté, le retrait
+> est net et le compilateur signale chaque usage restant.
+
+---
+
+## 4. Exemples
+
+### Page liste (Ajouter + Import + Export)
+
+```html
+<cw-page-header
+  [title]="'DOMAIN.USERS.TITLE'"
+  [description]="'DOMAIN.USERS.SUBTITLE'"
+  [actions]="[actionEnum.add]"
+  (action)="onAction($event)">
+  <cw-import-button cwPageHeaderImport [config]="importConfig" [modalTitle]="importTitle"
+    (closed)="reload()" (completed)="onImported($event)" />
+  <cw-export-button cwPageHeaderExport [options]="exportOptions" />
+</cw-page-header>
+```
+
+```ts
+import {
+  ExportButtonComponent, ImportButtonComponent, PageHeaderActionEnum, PageHeaderComponent
+} from '@cityway/bo-ui';
+
+// dans le composant hôte
+actionEnum = PageHeaderActionEnum;
+
+onAction(action: PageHeaderActionEnum): void {
+  switch (action) {
+    case PageHeaderActionEnum.add: this.create(); break;
+  }
+}
+```
+
+Configuration de `importConfig` / `exportOptions` : voir `import-button.md` et
+`export-button.md`.
+
+### Page édition (Enregistrer + Réinitialiser) avec états
+
+```html
+<cw-page-header
+  [title]="'DOMAIN.USERS.EDIT_TITLE'"
+  [description]="'DOMAIN.USERS.EDIT_SUBTITLE'"
+  [actions]="[actionEnum.reset, actionEnum.save]"
+  [isLoading]="{ save: saving() }"
+  [isDisabled]="{ reset: form.pristine }"
+  (action)="onAction($event)">
+</cw-page-header>
+```
+
+### Titre seul (sans retour, sans action)
+
+```html
+<cw-page-header [title]="'DOMAIN.DASHBOARD.TITLE'" [showBack]="false" />
+```
+
+### Action personnalisée projetée
+
+```html
+<cw-page-header [title]="'DOMAIN.REPORTS.TITLE'" [actions]="[]">
+  <cw-button [type]="boButtonType.secondary" [label]="'DOMAIN.REPORTS.SCHEDULE'" (btnAction)="schedule()" />
+</cw-page-header>
+```
+
+---
+
+## 4 bis. Menu « Colonnes » (visibilité + persistance)
+
+Quand on passe `columns` au page-header, un bouton **Colonnes** apparaît : un dropdown de cases à cocher pour afficher/masquer chaque colonne du tableau associé. L'état (colonnes masquées) est **persisté en localStorage** par tableau.
+
+```ts
+import { PageHeaderComponent, TableComponent, TableColumn } from '@cityway/bo-ui';
+
+@Component({
+  standalone: true,
+  imports: [PageHeaderComponent, TableComponent],
+  template: `
+    <cw-page-header
+      [title]="'DOMAIN.USERS.TITLE'"
+      [columns]="columns()"
+      storageKey="users/list"
+      (columnsChange)="columns.set($event)">
+    </cw-page-header>
+
+    <cw-table [columns]="columns()" [data]="rows()"></cw-table>
+  `,
+})
+export class UsersPage {
+  // Source de vérité unique, liée au header (contrôle) ET à la table (rendu).
+  columns = signal<TableColumn[]>([
+    { key: 'name',  label: 'DOMAIN.USERS.NAME' },
+    { key: 'email', label: 'DOMAIN.USERS.EMAIL' },
+    { key: 'createdAt', label: 'DOMAIN.USERS.CREATED', hidden: true }, // masquée par défaut
+    { key: 'actions', label: '', type: 'actions' },                    // jamais masquable
+  ]);
+}
+```
+
+Règles :
+- **Activation** : le menu n'apparaît que si `columns` contient au moins une colonne masquable. Sans `columns`, pas de menu.
+- **Colonnes exclues** : `type='actions'` (jamais masquable) et toute colonne `hideable: false`.
+- **Garde-fou** : impossible de masquer la **dernière** colonne masquable visible (sa case est désactivée).
+- **Persistance** : une seule clé localStorage `cw-table-columns` → `{ [storageKey]: string[] }`, **on ne stocke que les clés des colonnes masquées**. Au chargement, l'état mémorisé prime sur les `hidden` du config ; **sans `storageKey`**, le menu fonctionne mais rien n'est mémorisé.
+- **Helpers** : `loadHiddenColumns(storageKey)` / `saveHiddenColumns(storageKey, keys)` exportés par `@cityway/bo-ui` (le page-header les utilise en interne).
+
+---
+
+## 5. Notes d'intégration
+
+- **i18n** : `title` et `description` passent par `translate` → fournir des **clés**, pas du texte en dur. `description` est rendue en `[innerHTML]` (peut contenir du HTML/markup traduit).
+- **Libellés des actions** : non paramétrables. Ils sont câblés sur les clés `_COMMON._ACTION.*` (`ADD`, `SAVE`, `RESET`) et `_COMMON._FORM.BACK` pour le retour. Ces clés doivent exister dans les bundles i18n de l'app.
+- **Ordre d'affichage** : imposé par le template, indépendant de l'ordre du tableau `actions` et de l'ordre d'écriture du contenu projeté → Colonnes, *slot import*, *slot export*, *slot libre*, Réinitialiser, Ajouter, Enregistrer. Lu de droite à gauche : Enregistrer, Réinitialiser, zone custom, Exporter, Importer — les actions sur le formulaire au plus près de l'action principale, les échanges de données à l'extérieur.
+- **Bouton retour** : navigue via `Location.back()` (historique du navigateur). Aucune sortie ni cible configurable ; masquer avec `[showBack]="false"` si non pertinent.
+- **États par action** : `isLoading` / `isDisabled` sont des maps partielles ; une action absente de la map vaut `false`.
+- **Dépendance** : le composant projette des `cw-button` (`@cityway/basic-ui`) en interne — `basic-ui` doit être disponible.
+
+---
+
+## 6. Prompts-types (génération assistée)
+
+> Exemples de formulation pour demander à Claude de générer du code consommant ce composant.
+
+- « Ajoute un `cw-page-header` titre *Utilisateurs* (clé i18n) avec bouton retour et action Ajouter, qui route vers `onAction()`. »
+- « Sur ma page d'édition, mets un en-tête avec Enregistrer + Réinitialiser, où Enregistrer affiche un spinner pendant la sauvegarde et Réinitialiser est désactivé tant que le formulaire est vierge. »
+- « Ajoute un menu Export (tout + vue filtrée) dans l'en-tête de la page liste. »
+
+**Rappels pour Claude :**
+- Importer `PageHeaderComponent` (standalone) dans les `imports` du composant hôte.
+- Exposer `PageHeaderActionEnum` comme propriété du composant pour la binder dans le template (`actionEnum = PageHeaderActionEnum`).
+- Utiliser des clés i18n pour `title` et `description` ; les libellés des actions sont fixes (clés `_COMMON._ACTION.*`).
+- Piloter `isLoading` / `isDisabled` via des objets `{ [action]: boolean }` plutôt que des flags séparés.
+- **L'import et l'export ne sont pas des `actions`** : projeter `<cw-import-button cwPageHeaderImport>` et `<cw-export-button cwPageHeaderExport>` (cf. `import-button.md`, `export-button.md`). Ne jamais réintroduire ces valeurs dans `PageHeaderActionEnum`.