# @amsom-habitat/locataire-contrat-details

Ce package contient des composants pour gérer les détails de locataires et leurs contrats.

## Composants

- **ListingLocataires** - Composant principal pour afficher et gérer les locataires (voir [documentation détaillée](ListingLocataires.md))
- **ContratHistorique** - Composant modal pour afficher l'historique des événements d'un contrat avec formatage automatique
- **AmsomDropdown** - Composant dropdown (voir [documentation](AmsomDropdown.md))

## Installation

```bash
npm i @amsom-habitat/locataire-contrat-details
```

## Prérequis (peerDependencies)

Ce package nécessite les dépendances suivantes dans votre projet :

```json
{
  "vue": "^3.4.0",
  "@amsom-habitat/ui": "^2.0.0",
  "@amsom-habitat/vertical-stepper": "^1.0.0",
  "@fortawesome/fontawesome-svg-core": "^6.0.0 || ^7.0.0",
  "@fortawesome/free-solid-svg-icons": "^6.0.0 || ^7.0.0",
  "@fortawesome/vue-fontawesome": "^3.0.0"
}
```

## Utilisation rapide

### ListingLocataires

```vue
<template>
  <listing-locataires
    :list="locatairesList"
    :loading="isLoading"
    :get-historique-contrat="loadHistorique"
    :fields="customFields"
    enable-edit
    enable-history
    @save-edit="handleSaveEdit"
  />
</template>

<script>
import ListingLocataires from '@amsom-habitat/locataire-contrat-details'

export default {
  components: { ListingLocataires },
  data() {
    return {
      // Personnalisation des champs affichés (optionnel)
      customFields: [
        {
          key: 'mobile',
          label: 'Mobile',
          icon: 'fa-solid fa-mobile-alt',
          type: 'tel',
          editable: true,
          required: true,
          pattern: '[0-9]{10}',
          maxlength: 10,
          placeholder: 'Mobile',
          formatter: (value) => value?.toString().replace(/(\d{2})(?=\d)/g, '$1 '),
          link: (value) => `tel:${value}`
        },
        {
          key: 'mail',
          label: 'Email',
          icon: 'fa-solid fa-envelope',
          type: 'email',
          editable: true,
          required: true,
          placeholder: 'Email',
          link: (value) => `mailto:${value}`
        }
        // Ajouter vos propres champs personnalisés
      ]
    }
  },
  methods: {
    async loadHistorique(locataire) {
      // Retourner directement les données brutes du suivi
      // ContratHistorique formatera automatiquement les données
      const response = await api.getSuiviContrat(locataire.typeContrat, locataire.idContrat)
      return response.data
    },
    handleSaveEdit({ original, edited }) {
      // Gérer la sauvegarde des modifications
      console.log('Modifications:', edited)
    }
  }
}
</script>
```

**Configuration des champs** :

Par défaut, le composant affiche : mobile, telephone, telPro, mail, loginExtranet.

### Trois façons de configurer les champs :

#### 1. Override complet avec `fields`

Remplace complètement les champs par défaut :

```javascript
:fields="[
  { key: 'mobile', label: 'Mobile', icon: 'fa-mobile-alt', type: 'tel', editable: true },
  { key: 'mail', label: 'Email', icon: 'fa-envelope', type: 'email', editable: true }
]"
```

#### 2. Retirer des champs avec `removeFields`

Filtre les champs par défaut :

```javascript
:remove-fields="['telPro', 'loginExtranet']"
// Affichera seulement : mobile, telephone, mail
```

#### 3. Ajouter des champs avec `addFields`

Conserve les champs par défaut et en ajoute :

````javascript
:add-fields="[
  {
    key: 'adresse',
    label: 'Adresse',
    icon: 'fa-map-marker-alt',
    type: 'text',
    editable: false
  }
### ContratHistorique

Composant de présentation pour afficher l'historique des événements. **Ne gère pas la modal** - le parent doit l'encapsuler dans une modal si nécessaire.

```vue
<template>
  <amsom-modal :is-open="isOpen" @close="isOpen = false">
    <template #modal-header>
      <h5>Historique du contrat</h5>
    </template>
    <template #modal-body>
      <contrat-historique
        :historique="historiqueData"
        :loading="isLoading"
      >
        <template #empty-message>
          <p>Aucun événement trouvé.</p>
        </template>
      </contrat-historique>
    </template>
  </amsom-modal>
</template>

<script>
import { ContratHistorique } from '@amsom-habitat/locataire-contrat-details'
import { AmsomModal } from '@amsom-habitat/ui'

export default {
  components: { ContratHistorique, AmsomModal }
  // Le composant formate automatiquement les données brutes pour le vertical stepper
}
</script>
````

**Format des données attendu** :

Le composant accepte des données brutes de l'API et les formate automatiquement :

```javascript
;[
  {
    codeEvenement: 'RDV', // ou evenement
    codeAction: 'VIS', // ou action
    dateSuivi: 1234567890, // timestamp Unix
    description: "Détails de l'événement",
    auteur: "Nom de l'auteur"
  }
]
```

**Icônes automatiques** :

- RDV → calendrier
- CON/LOCA → maison
- Autres → utilisateur

### AmsomDropdown

minlength: 5,
min: 0,
max: 100,
step: 1,
placeholder: 'Texte',
readonly: false,
disabled: false,
autocomplete: 'tel',
// Personnalisation avancée :
formatter: (value) => value, // Fonction de formatage pour l'affichage
link: (value) => `tel:${value}`, // Fonction pour créer un lien cliquable
inputStyle: 'width: 200px', // Style CSS personnalisé
inputProps: { // Props HTML additionnelles
'aria-label': 'Description',
'data-custom': 'value'
}
}

````

Voir la [documentation complète](ListingLocataires.md) pour tous les détails.

### ContratHistorique

```vue
<template>
  <contrat-historique
    :is-open="isOpen"
    :locataire="locataire"
    :historique="historiqueData"
    :loading="isLoading"
    @close="isOpen = false"
  />
</template>

<script>
import { ContratHistorique } from '@amsom-habitat/locataire-contrat-details'

export default {
  components: { ContratHistorique }
  // Le composant formate automatiquement les données brutes pour le vertical stepper
}
</script>
````

**Note** : ContratHistorique accepte des données brutes de suivi et les formate automatiquement pour AmsomVerticalStepper.

### AmsomDropdown

```javascript
import { AmsomDropdown } from '@amsom-habitat/locataire-contrat-details'
```

Voir la [documentation](AmsomDropdown.md).

## Développment

Après avoir fait vos dev, veillez à bien tenir à jour le [changelog.md](changelog.md) ainsi que la version du package.json puis faites :

```bash
git add .
git commit -m '<commentaire>'
git push origin <branch>
```

## Tests

Les tests sont réalisé de manière automatique sur les branches main et dev mais peuvent être fait localement, notemment pour voir l'evolution du développement via la commande :

```bash
npm run storybook
```

Le valideur devra, si des changements sont observés, aller sur la pipeline pour valider les différences à l'aide de chromatic, sans cela aucun merge-request ne sera possible. Si un merge est effectué, une double verification sera necessaire.

## Déploiement

Après avoir merge les dev sur la branche main, exécutez :

```bash
make publish
```

Cette commande vérifie la version, le changelog et publie le tout
