@cityway/bo-ui 1.0.10-beta027 → 1.1.0-beta002

package/docs/components/custom-list.md

@@ -0,0 +1,151 @@
+# `cw-custom-list` — Liste descriptive
+
+> Lib : `@cityway/bo-ui` · Sélecteur : `cw-custom-list` · Standalone : oui
+> Import : `import { CustomListComponent } from '@cityway/bo-ui';`
+
+---
+
+## 1. Rôle & quand l'utiliser
+
+Liste descriptive en lecture seule : affiche une suite de couples **libellé / valeur**, organisés en **groupes** optionnellement titrés, dans une carte. Couvre :
+
+- l'affichage d'une fiche de **détail** (récapitulatif d'une entité) ;
+- le rendu **typé** des valeurs : texte, date, booléen (Oui/Non), HTML ;
+- le **masquage automatique** des champs vides (`hideIfEmpty`) ;
+- la **traduction** des libellés, et optionnellement des valeurs (`translateValue`).
+
+À ne PAS utiliser pour : un tableau de données paginé/triable (utiliser `cw-table`), un formulaire éditable (utiliser `cw-form-field`).
+
+---
+
+## 2. API
+
+### Inputs
+
+| Input | Type | Défaut | Description |
+|-------|------|--------|-------------|
+| `customListData` | `DataCustomListGroup[]` | `[]` | Signal input (`input()`). Liste des groupes à afficher. Chaque groupe contient un titre optionnel et un tableau de champs. Voir types §3. |
+
+> Composant en lecture seule : **aucun Output**.
+
+### Méthode interne
+
+| Méthode | Signature | Description |
+|---------|-----------|-------------|
+| `hasValue` | `(value: any): boolean` | Utilisée par le template pour `hideIfEmpty`. Renvoie `false` pour `null`/`undefined`, chaîne vide (après `trim`), tableau vide, objet sans clés. |
+
+### Contenu projeté
+
+Aucun (`ng-content`). Tout le rendu est piloté par `customListData`.
+
+### Rendu par type de champ (`field.type`)
+
+| `type` | Rendu |
+|--------|-------|
+| `'date'` | `field.value` via le pipe `date: 'short'`. |
+| `'boolean'` | clé i18n `_COMMON._PRO_SENTENCE.YES` / `.NO` selon la valeur, via `translate`. |
+| `'html'` | `field.value` injecté tel quel via `[innerHTML]`. |
+| `'text'` / absent (défaut) | `field.value` brut ; traduit via `translate` si `translateValue` est `true`. |
+
+> Le **libellé** de chaque champ est rendu via la clé i18n `_LABEL.COLON` (interpolation `{ label }`), le `label` lui-même étant d'abord passé au pipe `translate`.
+
+---
+
+## 3. Types
+
+```ts
+interface DataCustomListGroup {
+  title?: string;            // clé i18n du titre de groupe (passée à translate) ; titre masqué si absent
+  fields: DataCustomList[];
+}
+
+interface DataCustomList {
+  label: string;             // clé i18n du libellé (passée à translate)
+  value: any;                // valeur affichée (string, Date, boolean, HTML…)
+  type?: 'date' | 'boolean' | 'text' | 'html'; // mode de rendu ; défaut = texte brut
+  translateValue?: boolean;  // si true et type texte : value est une clé i18n (passée à translate)
+  context?: any;             // champ libre (non utilisé par le rendu actuel)
+  hideIfEmpty?: boolean;     // si true : champ masqué quand hasValue(value) est false
+}
+```
+
+> ℹ️ `context` est présent dans le modèle mais **non consommé** par le template actuel.
+
+---
+
+## 4. Exemples
+
+### Fiche de détail (groupes titrés, types variés)
+
+```html
+<cw-custom-list [customListData]="details"></cw-custom-list>
+```
+
+```ts
+import { CustomListComponent, DataCustomListGroup } from '@cityway/bo-ui';
+
+// imports: [CustomListComponent]
+
+details: DataCustomListGroup[] = [
+  {
+    title: '_SECTION.IDENTITY',
+    fields: [
+      { label: '_LABEL.LAST_NAME', value: 'Dupont', type: 'text' },
+      { label: '_LABEL.BIRTHDATE', value: new Date('1985-06-15'), type: 'date' },
+      { label: '_LABEL.STATUS', value: true, type: 'boolean' },
+    ],
+  },
+];
+```
+
+### Champs masqués si vides
+
+```ts
+details: DataCustomListGroup[] = [
+  {
+    title: '_SECTION.IDENTITY',
+    fields: [
+      { label: '_LABEL.LAST_NAME', value: 'Martin', type: 'text' },
+      { label: '_LABEL.FIRST_NAME', value: '', type: 'text', hideIfEmpty: true },   // masqué
+      { label: '_LABEL.EMAIL', value: null, type: 'text', hideIfEmpty: true },      // masqué
+    ],
+  },
+];
+```
+
+### Valeur traduite (clé i18n en valeur)
+
+```ts
+{ label: '_LABEL.ROLE', value: '_ROLE.ADMIN', type: 'text', translateValue: true }
+```
+
+### Valeur HTML
+
+```ts
+{ label: '_LABEL.NOTES', value: '<strong>Note</strong> : à rappeler.', type: 'html' }
+```
+
+---
+
+## 5. Notes d'intégration
+
+- **i18n** : `group.title` et `field.label` passent par `translate` → fournir des **clés**, pas du texte en dur. Idem `field.value` quand `translateValue` est `true`.
+- **Clés requises** : le template s'appuie sur `_LABEL.COLON` (format « libellé : ») et, pour les booléens, sur `_COMMON._PRO_SENTENCE.YES` / `_COMMON._PRO_SENTENCE.NO` — ces clés doivent exister dans les fichiers de traduction de l'app.
+- **Sécurité HTML** : `type: 'html'` injecte la valeur via `[innerHTML]` → ne jamais y mettre de contenu utilisateur non assaini.
+- **Titre de groupe** : un groupe sans `title` n'affiche pas de `<h3>` mais rend bien ses champs.
+- **Signal input** : `customListData` est un `input()` (Angular signals) → binder via `[customListData]="..."`.
+
+---
+
+## 6. Prompts-types (génération assistée)
+
+> Exemples de formulation pour demander à Claude de générer du code consommant ce composant.
+
+- « Affiche une fiche de détail *Identité* (nom, prénom, date de naissance, statut actif/inactif) avec `cw-custom-list`, libellés en clés i18n. »
+- « Ajoute un groupe *Contact* avec email et téléphone, en masquant les champs vides. »
+- « Rends une valeur de rôle traduite (clé i18n) et une note en HTML dans la liste descriptive. »
+
+**Rappels pour Claude :**
+- Importer `CustomListComponent` (standalone) dans les `imports` du composant hôte.
+- Typer les données avec `DataCustomListGroup[]` ; binder via `[customListData]`.
+- Utiliser des clés i18n pour `title`, `label` (et `value` si `translateValue: true`) ; vérifier la présence des clés `_LABEL.COLON` et `_COMMON._PRO_SENTENCE.YES/NO`.

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

@@ -0,0 +1,229 @@
+# `cw-drag-n-drop-list` — Liste à glisser-déposer (deux colonnes)
+
+> Lib : `@cityway/bo-ui` · Sélecteur : `cw-drag-n-drop-list` · Standalone : oui
+> Import : `import { DragNDropListComponent } from '@cityway/bo-ui';`
+
+---
+
+## 1. Rôle & quand l'utiliser
+
+Composant de répartition d'items entre **deux colonnes** (« Disponibles » / « Activés ») par glisser-déposer, avec réordonnancement intra-colonne et transfert inter-colonnes. Couvre :
+
+- déplacer un item d'une colonne à l'autre (transfert) ;
+- réordonner les items au sein d'une même colonne ;
+- **renumérotation automatique** de l'ordre au drop (`reorderOnDrop`) ;
+- items **non-draggables** (`disabled` par item) ;
+- **rendu personnalisé** de chaque carte via un `ng-template` projeté ;
+- branchement sur une source `DragItem[]` brute **ou** sur un `FormArray` réactif, via un **adaptateur**.
+
+À ne PAS utiliser pour : une arborescence à plusieurs niveaux avec actions/badges par carte (utiliser `cw-drag-n-drop-nested-list`) ; un simple tri d'une seule liste (un `cdkDropList` direct suffit).
+
+---
+
+## 2. API
+
+### Inputs (signal inputs)
+
+| Input | Type | Défaut | Description |
+|-------|------|--------|-------------|
+| `availableItems` | `any` (source colonne gauche) | `undefined` | Source de la colonne « Disponibles ». Type libre : `DragItem[]` avec `ArrayAdapter`, `FormArray` avec `FormArrayAdapter`. |
+| `activeItems` | `any` (source colonne droite) | `undefined` | Source de la colonne « Activés ». Même typage que `availableItems`. |
+| `adapter` | `DragDropAdapter` | `new ArrayAdapter()` | Convertit la source ↔ `DragItem[]` interne. Voir §3. |
+| `itemTemplate` | `TemplateRef<any> \| undefined` | `undefined` | Gabarit de rendu d'une carte. Contexte `$implicit` = le `DragItem`. Si absent, gabarit par défaut (label + code + #ordre). |
+| `availableColumn` | `DragListColumn` | `{ title: 'Disponibles' }` | Configuration de la colonne gauche (titre, descriptions, classe CSS). |
+| `activeColumn` | `DragListColumn` | `{ title: 'Activés' }` | Configuration de la colonne droite. |
+| `reorderOnDrop` | `boolean` | `false` | Si `true`, recalcule `order = index + 1` sur les deux colonnes à chaque drop. |
+
+### Outputs
+
+| Output | Payload | Description |
+|--------|---------|-------------|
+| `availableItemsChange` | `any` (la source `availableItems`) | Émis après un drop, avec la source gauche mise à jour par l'adaptateur. |
+| `activeItemsChange` | `any` (la source `activeItems`) | Émis après un drop, avec la source droite mise à jour par l'adaptateur. |
+
+> Le composant ne fait pas de `two-way binding` automatique : les sorties émettent la **même référence** de source mutée en place par l'adaptateur. Brancher `(availableItemsChange)` / `(activeItemsChange)` pour réagir (persistance, recalcul).
+
+### Contenu projeté (gabarit de carte)
+
+Le rendu d'une carte est délégué à `itemTemplate`. Chaque carte est enveloppée dans un `cw-card` (`@cityway/basic-ui`). Le template reçoit le `DragItem` courant en `$implicit` :
+
+```html
+<cw-drag-n-drop-list [itemTemplate]="tpl" ...>
+</cw-drag-n-drop-list>
+
+<ng-template #tpl let-item>
+  <div class="d-flex justify-content-between w-100">
+    <span>{{ item.label }} <span class="text-muted">({{ item.code }})</span></span>
+    <span class="fw-bold">#{{ item.order }}</span>
+  </div>
+</ng-template>
+```
+
+Gabarit par défaut (si `itemTemplate` non fourni) : affiche `item.label`, `(item.code)` si présent, et `#item.order` si `order != null`.
+
+### Configuration de colonne (`DragListColumn`)
+
+Les champs effectivement consommés par ce composant :
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `title` | `string` | Titre de la colonne. Passé au pipe `translate` → **clé i18n**. |
+| `description` | `string` | Paragraphe sous le titre. Passé au pipe `translate`. |
+| `descriptionRwd` | `string` | Variante affichée uniquement en mobile (`d-sm-none`), rendue via `[innerHTML]`. Passé au pipe `translate`. |
+| `cssClass` | `string` | Classe(s) CSS appliquée(s) à la `<ul>` de la colonne (`ngClass`). |
+
+> `DragListColumn` déclare d'autres champs (`collapsible`, `showView/Edit/Delete/Add`, `maxItemsByDepth`, etc.) destinés à la variante **nested-list** ; ils ne sont **pas** lus par `cw-drag-n-drop-list`.
+
+### Modèle d'item (`DragItem`) — champs utilisés ici
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `id` | `number \| string` | Identité (clé `track` du `@for`). Obligatoire. |
+| `label` | `string` | Libellé (gabarit par défaut). |
+| `code` | `string` | Code optionnel affiché entre parenthèses (gabarit par défaut). |
+| `order` | `number` | Ordre affiché `#N` ; recalculé si `reorderOnDrop`. |
+| `disabled` | `boolean` | Si `true`, carte non-draggable (`cdkDragDisabled`). |
+
+> `DragItem` porte beaucoup d'autres champs (`title`, `subtitle`, `badge`, `children`, `actions`, `selected`, `pendingDelete`…) exploités par la variante **nested-list**, ignorés ici.
+
+---
+
+## 3. Adaptateurs (`DragDropAdapter`)
+
+L'adaptateur découple la source du consommateur de la représentation interne `DragItem[]`.
+
+```ts
+interface DragDropAdapter<T = any> {
+  toDragItems(source: T): DragItem[];
+  fromDragItems(items: DragItem[], source: T, peers?: T[]): void;
+}
+```
+
+- **`ArrayAdapter`** (défaut) — la source EST déjà un `DragItem[]`. Mutation in-place via `splice`.
+- **`FormArrayAdapter`** — la source est un `FormArray`. Construit au moyen de :
+  - `mapper: (ctrl, index) => DragItem` — projette chaque `AbstractControl` en `DragItem` ;
+  - `reorderFn?: (ctrl, newOrder) => void` — applique le nouvel ordre sur le control (appelé si présent, à chaque repositionnement). Gère le transfert inter-`FormArray` (déplacement réel du control entre tableaux, sans `emitEvent`).
+
+---
+
+## 4. Exemples
+
+### Cas simple (`DragItem[]` + `ArrayAdapter`)
+
+```html
+<cw-drag-n-drop-list
+  [availableItems]="available"
+  [activeItems]="active"
+  [reorderOnDrop]="true"
+  [availableColumn]="{ title: 'TRANSPORT.AVAILABLE_MODES' }"
+  [activeColumn]="{ title: 'TRANSPORT.ACTIVE_MODES' }"
+  (availableItemsChange)="onAvailableChange($event)"
+  (activeItemsChange)="onActiveChange($event)">
+</cw-drag-n-drop-list>
+```
+
+```ts
+import { DragNDropListComponent, DragItem } from '@cityway/bo-ui';
+
+available: DragItem[] = [
+  { id: 1, label: 'Vélo', code: 'BIKE', order: 1 },
+  { id: 2, label: 'Bus',  code: 'BUS',  order: 2 },
+];
+active: DragItem[] = [
+  { id: 3, label: 'Tramway', code: 'TRAM', order: 1 },
+];
+
+onAvailableChange(items: DragItem[]) { /* persister */ }
+onActiveChange(items: DragItem[]) { /* persister */ }
+```
+
+### Items non-draggables
+
+```ts
+available: DragItem[] = [
+  { id: 1, label: 'Vélo', code: 'BIKE', order: 1 },
+  { id: 2, label: 'Bus',  code: 'BUS',  order: 2, disabled: true },
+];
+```
+
+### Gabarit de carte personnalisé
+
+```html
+<cw-drag-n-drop-list
+  [availableItems]="available"
+  [activeItems]="active"
+  [itemTemplate]="tpl"
+  (activeItemsChange)="onActiveChange($event)">
+</cw-drag-n-drop-list>
+
+<ng-template #tpl let-item>
+  <div class="d-flex justify-content-between w-100">
+    <span><strong>{{ item.label }}</strong></span>
+    <span class="text-muted">({{ item.code }}) — #{{ item.order }}</span>
+  </div>
+</ng-template>
+```
+
+### Source `FormArray` (adaptateur dédié)
+
+```ts
+import { FormArray, FormControl, FormGroup, AbstractControl } from '@angular/forms';
+import { FormArrayAdapter, DragItem } from '@cityway/bo-ui';
+
+available = new FormArray([
+  new FormGroup({ mode: new FormControl('BIKE'), order: new FormControl(1) }),
+  new FormGroup({ mode: new FormControl('BUS'),  order: new FormControl(2) }),
+]);
+active = new FormArray([
+  new FormGroup({ mode: new FormControl('TRAM'), order: new FormControl(1) }),
+]);
+
+adapter = new FormArrayAdapter(
+  (ctrl: AbstractControl): DragItem => ({
+    id:    ctrl.get('mode')!.value,
+    label: ctrl.get('mode')!.value,
+    code:  ctrl.get('mode')!.value,
+    order: ctrl.get('order')!.value,
+  }),
+  (ctrl, newOrder) => ctrl.get('order')!.setValue(newOrder, { emitEvent: false }),
+);
+```
+
+```html
+<cw-drag-n-drop-list
+  [availableItems]="available"
+  [activeItems]="active"
+  [adapter]="adapter"
+  [reorderOnDrop]="true"
+  (activeItemsChange)="onActiveChange($event)">
+</cw-drag-n-drop-list>
+```
+
+---
+
+## 5. Notes d'intégration
+
+- **Dépendance `@angular/cdk/drag-drop`** : le composant importe `DragDropModule` (standalone) et utilise `cdkDropList` connectés (`cdkDropListConnectedTo`), `moveItemInArray`, `transferArrayItem`. Aucune configuration côté hôte requise — l'import du composant suffit.
+- **Source mutée en place** : l'adaptateur modifie la source d'origine (`splice` pour `ArrayAdapter`, `push/removeAt` pour `FormArrayAdapter`). Les outputs ré-émettent cette même référence. Ne pas se reposer sur l'immuabilité.
+- **`effect` de synchro** : les copies internes (`_available` / `_active`) sont reconstruites via un `effect` quand les inputs `availableItems` / `activeItems` ou `adapter` changent. Remplacer la référence source pour forcer une resynchro.
+- **i18n** : `title`, `description`, `descriptionRwd` des colonnes passent par `translate` → fournir des **clés**, pas du texte en dur. Les libellés d'items (`label`, `code`) du gabarit par défaut ne sont **pas** traduits (texte brut) — gérer la traduction dans un gabarit custom si besoin.
+- **`descriptionRwd`** est injectée via `[innerHTML]` (mobile uniquement) : n'y mettre que du contenu de confiance.
+- **`track`** repose sur `item.id` : garantir l'unicité des `id` au sein des deux colonnes réunies.
+- **`reorderOnDrop`** ne renumérote que la propriété `order` du `DragItem` ; avec `FormArrayAdapter`, fournir `reorderFn` pour répercuter sur le control.
+
+---
+
+## 6. Prompts-types (génération assistée)
+
+> Exemples de formulation pour demander à Claude de générer du code consommant ce composant.
+
+- « Crée une répartition de modes de transport en deux colonnes *Disponibles* / *Activés* (clés i18n `TRANSPORT.AVAILABLE_MODES` / `TRANSPORT.ACTIVE_MODES`), avec renumérotation automatique au drop, branchée sur deux `DragItem[]`. »
+- « Branche ce drag-n-drop-list sur un `FormArray` réactif via `FormArrayAdapter` : mappe chaque `FormGroup` (champs `mode`, `order`) en `DragItem` et répercute le nouvel ordre dans le control. »
+- « Ajoute un gabarit de carte personnalisé affichant le libellé en gras à gauche et le code + l'ordre à droite. »
+
+**Rappels pour Claude :**
+- Importer `DragNDropListComponent` (standalone) dans les `imports` du composant hôte.
+- Importer les types `DragItem`, `DragListColumn` et l'adaptateur (`ArrayAdapter` ou `FormArrayAdapter`) depuis `@cityway/bo-ui`.
+- Garantir des `id` uniques entre les deux colonnes (clé de `track`).
+- Brancher `(availableItemsChange)` / `(activeItemsChange)` pour la persistance ; ne pas supposer l'immuabilité des sources.
+- Pour une arborescence multi-niveaux avec actions/badges, utiliser plutôt `cw-drag-n-drop-nested-list`.