@cityway/bo-ui 1.1.0-beta003 → 1.1.0-beta005

package/docs/components/page-header.md

@@ -32,12 +32,16 @@ En-tête de page transverse du back-office. Couvre :
 | `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`. |
 
 ### Contenu projeté
 
@@ -134,6 +138,47 @@ onAction(action: PageHeaderActionEnum): void {
 
 ---
 
+## 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).

package/docs/components/progress-bar.md

@@ -0,0 +1,140 @@
+# `cw-progress-bar` — Progress bar
+
+> Lib : `@cityway/bo-ui` · Sélecteur : `cw-progress-bar` · Standalone : oui
+> Import : `import { ProgressBarComponent } from '@cityway/bo-ui';`
+
+---
+
+## 1. Rôle & quand l'utiliser
+
+Barre de progression **déterministe** : visualise l'avancement d'une valeur connue sur une échelle (`value` / `max`), de 0 à 100 %.
+
+Couvre :
+
+- deux **tailles** : `md` (16px, libellé de pourcentage possible) et `sm` (8px, barre fine) ;
+- quatre **types** de couleur issus du DS : `information` (défaut), `success`, `warning`, `danger` ;
+- l'affichage optionnel du **pourcentage** dans la barre (`showValue`, taille `md` uniquement) ;
+- une échelle **personnalisée** via `max` (ex. 320 / 500).
+
+À ne PAS utiliser pour :
+
+- un état de chargement **indéterminé** (durée inconnue) → utiliser `cw-loader` ;
+- un curseur de saisie d'une valeur → utiliser `cw-form-field` (`type=slider` / `range`).
+
+---
+
+## 2. API
+
+### Inputs
+
+| Input | Type | Défaut | Description |
+|-------|------|--------|-------------|
+| `value` | `number` | — (**requis**) | Valeur courante d'avancement. Bornée à `[0, max]` pour le calcul du pourcentage (`input.required`). |
+| `max` | `number` | `100` | Valeur correspondant à 100 % de la barre. |
+| `size` | `ProgressBarSizeEnum` | `md` | Hauteur de la barre (`md` = 16px / `sm` = 8px). |
+| `type` | `ProgressBarTypeEnum` | `information` | Couleur de remplissage. |
+| `showValue` | `boolean` | `false` | Affiche le pourcentage arrondi dans la barre. **Ignoré en taille `sm`** (le DS ne fournit pas de couleur de texte `on-*` en `sm`). |
+| `label` | `string` | `undefined` | Libellé accessible (`aria-label`). À fournir si la barre n'est pas déjà décrite par un texte voisin. |
+| `dataTest` | `string` | `undefined` | Pose l'attribut `data-test-ctw` pour le ciblage E2E. |
+
+### Outputs
+
+Aucun. Le composant est purement présentiel (« controlled ») : il affiche la valeur qu'on lui passe.
+
+### Comportement de rendu
+
+- Le pourcentage affiché et la largeur du remplissage valent `round(clamp(value / max) * 100)`, borné à `0..100`.
+- `role="progressbar"` avec `aria-valuenow` (= `value`), `aria-valuemin="0"` et `aria-valuemax` (= `max`).
+- Le host porte la classe `cw-progressbar` : les tokens DS `component/progressbar/*` y sont scopés (résolution dark-aware automatique).
+
+---
+
+## 3. Types
+
+```ts
+enum ProgressBarSizeEnum {
+  md = 'md',
+  sm = 'sm',
+}
+
+enum ProgressBarTypeEnum {
+  information = 'information',
+  success = 'success',
+  warning = 'warning',
+  danger = 'danger',
+}
+```
+
+---
+
+## 4. Exemples
+
+### Barre simple
+
+```html
+<cw-progress-bar [value]="60" label="Avancement de l'import"></cw-progress-bar>
+```
+
+### Avec pourcentage et type
+
+```html
+<cw-progress-bar [value]="75" type="success" [showValue]="true"></cw-progress-bar>
+```
+
+### Échelle personnalisée
+
+```html
+<!-- 320 / 500 = 64 % -->
+<cw-progress-bar [value]="320" [max]="500" [showValue]="true" label="320 sur 500"></cw-progress-bar>
+```
+
+### Liaison à un signal
+
+```ts
+import { ProgressBarComponent, ProgressBarTypeEnum } from '@cityway/bo-ui';
+
+@Component({
+  selector: 'app-import',
+  standalone: true,
+  imports: [ProgressBarComponent],
+  template: `
+    <cw-progress-bar
+      [value]="progress()"
+      [type]="progressType"
+      [showValue]="true"
+      label="Progression de l'import">
+    </cw-progress-bar>
+  `,
+})
+export class ImportComponent {
+  progress = signal(0);
+  readonly progressType = ProgressBarTypeEnum.information;
+}
+```
+
+---
+
+## 5. Notes d'intégration
+
+- **Composant déterministe** : à réserver aux avancements dont la valeur est connue. Pour un chargement de durée inconnue, préférer `cw-loader`.
+- **`showValue` + `sm`** : le libellé inline n'est rendu qu'en taille `md`. Une barre `sm` reste muette même si `showValue` est à `true`.
+- **Accessibilité** : fournir `label` quand aucun texte visible adjacent ne décrit la barre, sinon le lecteur d'écran annonce une progression sans contexte.
+- **Dark mode** : aucune action requise. Les couleurs (`information`/`success`/`warning`/`danger`, piste `neutral`, texte `on-*`) proviennent des tokens DS scopés sur `.cw-progressbar` et basculent automatiquement en thème sombre.
+- **En cellule de tableau** : le DS prévoit un usage `Table / Column / Progressbar` (barre `sm`). Insérer le `cw-progress-bar` directement dans le template de cellule de `cw-table`.
+
+---
+
+## 6. Prompts-types (génération assistée)
+
+> Exemples de formulation pour demander à Claude de générer du code consommant ce composant.
+
+- « Ajoute une `cw-progress-bar` `success` avec le pourcentage affiché, pilotée par un signal `progress`. »
+- « Mets une barre de progression fine (`sm`) de type `information` dans la colonne "Avancement" de ma `cw-table`. »
+- « Affiche une progression 320/500 avec `max` et le pourcentage dans la barre. »
+
+**Rappels pour Claude :**
+- Importer `ProgressBarComponent` (standalone) dans les `imports` du composant hôte.
+- `value` est **requis** (`input.required`).
+- `showValue` n'a d'effet qu'en taille `md`.
+- Toujours fournir un `label` accessible si la barre n'a pas de texte descriptif adjacent.
+- Pour un chargement indéterminé, utiliser `cw-loader` et non ce composant.

package/docs/components/table.md

@@ -36,6 +36,9 @@ Dépend de `@cityway/basic-ui` (badge, button, icon, image, loader, modale de su
 | `pagination` | `Pagination` | `undefined` | Config de pagination (intègre `cw-pagination`). |
 | `bulkActions` | `BulkAction[]` | `[]` | Actions groupées (nécessite `checkbox`). |
 | `rowActions` | `RowActionsConfig` | `undefined` | Actions par ligne (API déclarative). |
+| `emptyStateNoData` | `TableEmptyStateConfig` | `undefined` | État vide quand `data` est vide **et** table non filtrée (`cw-empty-state`). |
+| `emptyStateNoResult` | `TableEmptyStateConfig` | `undefined` | État vide quand un filtrage ne renvoie rien (`isFiltered=true`). |
+| `isFiltered` | `boolean` | `false` | Des filtres sont actifs → pilote le choix noData vs noResult. |
 
 ### Outputs
 
@@ -74,6 +77,8 @@ interface TableColumn {
   defaultSort?: 'asc' | 'desc';      // tri initial
   hidden?: boolean;
   clickable?: boolean;               // rend la cellule cliquable (-> cellClick)
+  translate?: boolean;               // traduit la VALEUR (text/link). Défaut false. Voir ci-dessous.
+  hideable?: boolean;                // proposée au masquage dans le menu « Colonnes ». Défaut true.
 }
 
 interface BadgeConfig {
@@ -189,6 +194,9 @@ rowActions: RowActionsConfig = {
 ## 5. Notes d'intégration
 
 - **i18n** : tous les `label` (colonnes, actions) sont des **clés** traduites en interne.
+- **Visibilité des colonnes** : le menu « Colonnes » (afficher/masquer + persistance localStorage) est porté par **`cw-page-header`** (lui passer `[columns]` + `storageKey`, relier `(columnsChange)`). La `cw-table` ne fait que rendre les colonnes non `hidden` ; côté colonne, `hideable: false` exclut du menu et `type='actions'` est exclu d'office. Voir la doc `cw-page-header` §4 bis.
+- **État vide** : fournir `emptyStateNoData` et/ou `emptyStateNoResult` (+ `isFiltered`) pour afficher un `cw-empty-state` (illustration + titre + description + 2 boutons avec `click`). Sans config, la table garde le texte `NO_RESULT`. Voir la doc `cw-empty-state`.
+- **Traduction des VALEURS de cellule** : les colonnes `text` / `link` affichent la donnée **brute par défaut**. Mettre `translate: true` **uniquement** quand la valeur est elle-même une clé i18n (enum / statut affiché en texte). Sinon une donnée qui coïncide avec une clé serait traduite à tort — typiquement un code applicatif `"NEWS"` rendu en `[object Object]` car la clé pointe sur une branche d'objet. (Les `badge` traduisent déjà leur `label` ; les en-têtes `label` sont toujours traduits.)
 - **OnPush** : `data`/`columns` sont des signals → fournir des références à jour (set/update du signal).
 - **`rowActions` vs `#actionsTemplate`** : ne fournir qu'un seul. `rowActions` est l'API recommandée ; le template custom reste pour les cas hors standard.
 - **Suppression** : `type='delete'` ouvre la modale de confirmation de `basic-ui` ; n'émet `bulkDelete`/`bulkAction` qu'après confirmation.