@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)
• ContratHistorique - Composant modal pour afficher l'historique des événements d'un contrat avec formatage automatique
• AmsomDropdown - Composant dropdown (voir documentation)

Installation

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

Prérequis (peerDependencies)

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

{
  "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

<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 :

: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 :

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

3. Ajouter des champs avec addFields

Conserve les champs par défaut et en ajoute :

: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 :

;[
  {
    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

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

Voir la documentation.

Développment

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

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 :

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 :

make publish

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