AMSOM Autocomplete

Ce package propose un composant d'autocomplete pour Vue.js

Installation

npm i @amsom-habitat/amsom-autocomplete

Importer les css dans le main.js tel que :

import '@amsom-habitat/amsom-autocomplete/dist/style.css'

Pour utiliser le package:

import { AmsomAutocomplete } from '@amsom-habitat/amsom-autocomplete'

Développement

Après avoir fait vos développements, 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és de manière automatique sur les branches main et dev mais peuvent être faits localement, notamment pour voir l'évolution 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 vérification sera nécessaire.

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

Utilisation

Props

• v-model : La valeur de l'input (doit etre une instance de items)
• items : Les items à afficher
• getInputLibelle : La fonction qui permet de récupérer le libellé de l'item, par defaut récupère item.name ou item.label ou item.libelle
• getInputLibelleFromId : La fonction qui permet de récupérer le libellé de l'item à partir de son id
• getId : La fonction qui permet de récupérer l'identifier de l'item, par defaut récupère item.id
• identifier : L'identifiant de l'input
• maxResultsHeight : La hauteur max des résultats
• placeholder : Placeholder de l'input. Default Recherchez...
• loading : Ajoute un AmsomOverlay pour un chargement. Boolean default false
• zIndex: Permet d'ajuster le z-index de la liste affichée. Default 1045
• required : Si l'input est requis
• allowEmpty : Si l'input peut être vide
• selectOnBlur : Si l'item doit être sélectionné au blur de l'input
• label: Le label de l'input
• floatingLabel: Si le label doit être flottant (A l'avenir penser a intégrer directement le composant AmsomFloatingInput quand il existera)
• emptyValue: La valeur vide de l'input. Par défaut { id: null, libelle: 'Aucune sélection' }
• disabled: Si l'input est désactivé
• multiple: Si l'input est en mode multiple, permet de sélectionner plusieurs items
• hideChoices: Si les choix doivent être cachés
• filteringFunction: La fonction de filtrage des items
• debounceDelay: Le délai de debounce pour la recherche. Default 300ms
• minSearchLength: La longueur minimale de la recherche avant de lancer le filtrage. Default 0
• maxResults: Le nombre maximum de résultats à afficher. Default null (affiche tous les résultats)
• infiniteScroll: Si l'infinite scroll est activé. Default true
• infiniteScrollItemPerPage: Le nombre d'items par page pour l'infinite scroll. Default 50
• inputRounded: Si l'input doit avoir les bords arrondis. Default false
• inputSize: La taille de l'input. Default md. Options possibles : sm

Events

• @search : Déclenché lors de la mise en oeuvre de la recherche
• @onFocus : Emit lorsque l'input est focus

Slots

Le composant expose plusieurs slots pour personnaliser l'affichage et le comportement :

• input : Permet de remplacer complètement l'input (reçoit { search, showList, keepOpen }).
• options : Utilisé pour rendre chaque option de la liste (reçoit l'objet item en binding).
• empty-option : Permet de personnaliser l'option « vide » (valeur par défaut) lorsqu'il n'y a pas de sélection.
• no-options : Contenu affiché quand aucun résultat n'est trouvé.
• additional-option : Contenu collé en bas de la liste (pratique pour un bouton d'ajout ou un message complémentaire). Le slot reçoit { items, search }.

Exemple d'utilisation des slots :

<amsom-autocomplete v-model="selection" :items="items">
  <template #options="{ name, ...item }">
    <div class="d-flex justify-content-between">
      <span class="fw-bold">{{ name || item.label || item.libelle }}</span>
      <small class="text-muted">#{{ item.id }}</small>
    </div>
  </template>

  <template #no-options>
    <div class="text-center text-muted">Aucun résultat, essayez un autre terme.</div>
  </template>

  <template #additional-option="{ items, search }">
    <div class="p-2 text-end">
      <button class="btn btn-sm btn-outline-primary" @click="$emit('add', search)">Ajouter « {{ search }} »</button>
    </div>
  </template>
</amsom-autocomplete>

Exemple complet

<template>
  <amsom-autocomplete
    :items="items"
    v-model="selection"
    :filtering-function="customFilter"
    maxResultsHeight="10vh"
  />
</template>

<script>
import '@amsom-habitat/amsom-autocomplete/dist/style.css'
import { AmsomAutocomplete } from '@amsom-habitat/amsom-autocomplete'

export default {
  name: 'TestPage',
  components: {
    AmsomAutocomplete
  },
  data() {
    return {
      items: [
        { id: 1, name: 'item 1' },
        { id: 2, name: 'item 2' },
        { id: 3, name: 'item 3' },
        { id: 4, name: 'item 4' },
        { id: 5, name: 'item 5' }
      ],
      selection: null
    }
  },
  methods: {
    customFilter({ search, items }) {
      if (!search) return items

      return items.filter((item) => item.name.toLowerCase().includes(search.toLowerCase()))
    }
  }
}
</script>