npm package: @rsuci/shared-form-components
Description: Composants partagés de rendu de formulaires RSU v2 - Package local pour frontend Admin et Public
Author: RSU v2 Architecture Team
Latest version: 1.0.143

# @rsuci/shared-form-components

Composants React partagés pour le rendu des formulaires d'enquête RSU v2.

## Installation

```bash
npm install @rsuci/shared-form-components
```

## Objectif

Ce package centralise tous les composants de rendu de formulaires pour :

- **Frontend Admin** (`rsu_app_frontend_v2`) : Gestion interne des enquêtes
- **Frontend Public** (`rsu_public_frontend_v2`) : Collecte de données par le public
- **App Mobile** (`rsu_app_mobile_react`) : Collecte terrain (types réutilisés, rendu natif séparé)

## Utilisation

### Exemple basique

```typescript
import { FormRenderer } from '@rsuci/shared-form-components';

function EnquetePage() {
  const [enquete, setEnquete] = useState<EnqueteInstance>({...});

  return (
    <FormRenderer
      enquete={enquete}
      formulaire={formulaire}
      disabled={false}
      onSave={handleSave}
      onComplete={handleComplete}
      onCancel={handleCancel}
    />
  );
}
```

### Avec injection de dépendances (Frontend Admin)

```typescript
import { FormRenderer, FormRendererServices } from '@rsuci/shared-form-components';
import { menagesService, enquetesService } from '@/lib/api';
import DistrictSelector from '@/components/selectors/geographic/DistrictSelector';

const services: FormRendererServices = {
  fetchMenages: () => menagesService.getAll(),
  fetchEnquetes: (filter) => enquetesService.getFiltered(filter),
};

const geographicComponents = {
  DistrictSelectorComponent: DistrictSelector,
  RegionSelectorComponent: RegionSelector,
  // ... autres composants
};

<FormRenderer
  enquete={enquete}
  formulaire={formulaire}
  services={services}
  geographicComponents={geographicComponents}
  onSave={handleSave}
/>
```

## Types supportés (42 types)

### Types de saisie texte

| Type          | Description                      |
| ------------- | -------------------------------- |
| `STRING`      | Champ texte court (une ligne)    |
| `TEXTE`       | Champ texte long (textarea)      |
| `EMAIL`       | Champ email avec validation      |
| `PHONE`       | Numéro de téléphone              |
| `MOBILEPHONE` | Numéro de téléphone mobile       |

### Types numériques et temporels

| Type        | Description                |
| ----------- | -------------------------- |
| `NUMERIQUE` | Champ numérique            |
| `DATE`      | Sélecteur de date          |
| `DATEHEURE` | Sélecteur de date et heure |
| `HOUR`      | Sélecteur d'heure          |

### Types de sélection

| Type        | Description                          |
| ----------- | ------------------------------------ |
| `CHECKBOX`  | Cases à cocher (sélection multiple)  |
| `RADIO`     | Boutons radio (sélection unique)     |
| `LISTE`     | Liste déroulante (select)            |
| `COMBOBOX`  | Liste déroulante avec recherche      |
| `LISTRADIO` | Liste avec affichage radio           |

### Types médias et localisation

| Type    | Description                  |
| ------- | ---------------------------- |
| `GPS`   | Capture de coordonnées GPS   |
| `PHOTO` | Capture photo (caméra)       |
| `IMAGE` | Sélection d'image (galerie)  |

### Types d'affichage (lecture seule)

| Type       | Description                                              |
| ---------- | -------------------------------------------------------- |
| `LABEL`    | Texte statique avec interpolation `${VARIABLE}`          |
| `PANEL`    | Panneau de regroupement visuel                           |
| `RICHTEXT` | Contenu HTML riche avec interpolation `${VARIABLE}`      |

### Types géographiques

| Type              | Description                    |
| ----------------- | ------------------------------ |
| `DEPARTEMENT`     | Sélecteur de département       |
| `DISTRICT`        | Sélecteur de district          |
| `REGION`          | Sélecteur de région            |
| `QUARTIER`        | Sélecteur de quartier          |
| `VILLAGE`         | Sélecteur de village           |
| `SOUSPREFECTURE`  | Sélecteur de sous-préfecture   |
| `RSU`             | Sélecteur RSU                  |
| `PAYS`            | Sélecteur de pays              |

### Types de référence

| Type                  | Description                              |
| --------------------- | ---------------------------------------- |
| `MENAGE`              | Sélecteur de ménage                      |
| `ENQUETE`             | Sélecteur d'enquête                      |
| `ENQUETEUR`           | Nom de l'enquêteur (auto-rempli)         |
| `EMAIL_ENQUETEUR`     | Email de l'enquêteur (auto-rempli)       |
| `TELEPHONE_ENQUETEUR` | Téléphone de l'enquêteur (auto-rempli)   |

### Types documents d'identité

| Type         | Description                             |
| ------------ | --------------------------------------- |
| `IDDOC`      | Document d'identité générique           |
| `CNI`        | Carte Nationale d'Identité              |
| `NNI`        | Numéro National d'Identité              |
| `CMU`        | Carte de Couverture Maladie Universelle |
| `PASSEPORT`  | Passeport                               |
| `CC`         | Certificat de Conformité                |
| `EXTRAIT`    | Extrait de naissance                    |

### Types rosters (groupes multiples)

| Type          | Description                                              |
| ------------- | -------------------------------------------------------- |
| `ROSTERCHECK` | Roster avec checkbox (sélection + masquage conditionnel) |
| `ROSTERLIST`  | Roster avec liste déroulante                             |

### Types collections

| Type               | Description                                        |
| ------------------ | -------------------------------------------------- |
| `COLLECTION`       | Collection de sous-formulaires                     |
| `COLLECTIONEXTEND` | Collection étendue avec fonctionnalités avancées   |

## Architecture

### Injection de dépendances

Le package utilise le pattern d'injection de dépendances pour :

- **Services API** : `FormRendererServices` (optionnel)
- **Composants géographiques** : `GeographicComponents` (optionnel)

### Peer Dependencies

Le package déclare ses dépendances framework en `peerDependencies` :

- `react` (^18 ou ^19)
- `react-dom` (optionnel)
- `next` (optionnel, ^14 ou ^15)
- `lucide-react` (optionnel)

Seuls `clsx` et `tailwind-merge` sont embarqués comme dépendances directes.

### Support des rosters

Les rosters (ROSTERCHECK et ROSTERLIST) sont automatiquement supportés avec :

- Rendu des variables selon leur type natif (RADIO, COMBOBOX, etc.)
- Indépendance des variables entre panels
- Comportement conditionnel pour ROSTERCHECK (checkbox + masquage)

## Changelog

### v1.0.109 (2026-03-01)

- Ajout du type `RICHTEXT` : affichage de contenu HTML riche avec interpolation de variables
- Nouveau composant `RichTextDisplay` pour le rendu HTML (`dangerouslySetInnerHTML`)
- Retrait de `lucide-react` des `dependencies` (reste en `peerDependencies` optionnel)

### v1.0.100+ (2026-01 - 2026-02)

- Ajout des types `COLLECTION` et `COLLECTIONEXTEND` pour les sous-formulaires
- Ajout du type `MOBILEPHONE`
- Ajout du type `LISTRADIO`

### v1.0.50+ (2025-12)

- Ajout des types documents d'identité : `CNI`, `NNI`, `CMU`, `PASSEPORT`, `CC`, `EXTRAIT`
- Ajout des types enquêteur : `ENQUETEUR`, `EMAIL_ENQUETEUR`, `TELEPHONE_ENQUETEUR`

### v1.0.0 (2025-11-25)

- Extraction depuis `rsu_app_frontend_v2`
- Support rosters avec `RosterPanel`
- Indépendance des variables entre panels
- Comportement conditionnel ROSTERCHECK
- Injection de dépendances pour services et composants géographiques
- 27 types de variables initiaux

## Développement

### Build

```bash
npm run build
```

### Watch mode

```bash
npm run watch
```

### Tests

```bash
npm test
npm run test:coverage
```

## Auteurs

RSU v2 Architecture Team

## License

MIT