Installation

Installer le package

npm install srcdev-hair-treatments

Importer les styles

Deux feuilles de styles sont fournies dans dist/ : le CSS propre au composant, et un jeu de tokens de couleur qu'il lit. Importez les deux une seule fois, globalement, dans le point d'entrée de votre application ou votre CSS global :

@import "srcdev-hair-treatments/dist/style.css";
@import "srcdev-hair-treatments/dist/tokens.css";

tokens.css définit les quatre gammes de couleurs sémantiques utilisées par le composant : --brand-00 à --brand-10, ainsi que --success-*, --warning-* et --error-*. Ignorez cet import et fournissez vos propres valeurs si vous voulez que le widget adopte votre identité de marque dès le départ, voir Personnalisation.

Copier les images

Les échantillons de type et de couleur de cheveux peuvent afficher de vraies photos : le package fournit un jeu complet d'images par défaut, mais elles doivent être servies depuis le répertoire public/ de votre propre application, pas lues depuis node_modules. Ajoutez un script à votre package.json et exécutez-le une fois après l'installation :

"setup:assets": "cp -r node_modules/srcdev-hair-treatments/public/images/. public/images/"

Intégrez-le à un hook postinstall pour qu'il reste synchronisé à chaque npm install, récupérant toute image nouvelle ou modifiée lors d'une mise à jour du package :

"postinstall": "npm run setup:assets"

Consultez Personnalisation → Images pour remplacer ces images par vos propres photos pour chaque option.

Enregistrer le plugin

createHairTreatments() est un plugin Vue qui fournit une config par défaut à chaque instance de TreatmentConsultant dans votre application. Passer une configuration ici est optionnel : vous pouvez aussi en passer une directement en tant que prop par instance (voir Configuration). Il peut aussi porter votre clé de licence pour éviter de la répéter à chaque instance, voir Licences.

import { createApp } from "vue"
import { createHairTreatments } from "srcdev-hair-treatments"
import App from "./App.vue"

const app = createApp(App)
app.use(createHairTreatments())
app.mount("#app")

Utiliser le composant

<template>
  <TreatmentConsultant @complete="onComplete" />
</template>

<script setup lang="ts">
import { TreatmentConsultant } from "srcdev-hair-treatments"
import type { ConsultationSelections } from "srcdev-hair-treatments"

function onComplete(selections: ConsultationSelections) {
  console.log(selections)
}
<\/script>

Nuxt

Enregistrez le plugin dans app/plugins/ (pas un répertoire plugins/ à la racine : le srcDir par défaut de Nuxt 4 est app/, et un plugin placé en dehors ne s'enregistrera pas, sans erreur visible) :

// app/plugins/hair-treatments.ts
import { createHairTreatments } from "srcdev-hair-treatments"

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(createHairTreatments())
})

Ajoutez les deux feuilles de styles au tableau css de nuxt.config.ts, et enveloppez le composant lui-même dans <ClientOnly> : TreatmentConsultant n'est pas compatible SSR. Tous les détails dans SSR & ClientOnly.

HTML pur, sans étape de build

Pas d'application Vue, pas de bundler ? Un bundle dist/embed.js séparé fournit tout le nécessaire, Vue inclus, pour qu'une simple page HTML puisse intégrer la consultation avec une <div>, un lien vers la feuille de styles, et une balise <script>. Chargée depuis un CDN comme jsDelivr, l'URL est figée sur une version du package, donc rien à invalider en cache lors d'une nouvelle sortie : il suffit d'augmenter la version dans l'URL quand vous le souhaitez.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/srcdev-hair-treatments@1.1.3/dist/embed-style.css" />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/srcdev-hair-treatments@1.1.3/dist/tokens.css" />

<div data-hair-treatments data-license-key="YOUR_LICENSE_KEY"></div>

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/srcdev-hair-treatments@1.1.3/dist/embed.js"
></script>

Chaque élément de la page correspondant à [data-hair-treatments] est monté automatiquement dès le chargement du script, rien d'autre à écrire. La version ci-dessus, 1.1.3, est lue depuis la dépendance installée sur ce site, elle est donc toujours à jour : copiez-la telle quelle, ou remplacez-la par la version sur laquelle vous êtes vous-même figé. Consultez Licences pour savoir d'où vient la clé de licence.

Passez une configuration par instance avec un attribut data-config encodé en JSON, voir Configuration pour le format accepté :

<div
  data-hair-treatments
  data-license-key="YOUR_LICENSE_KEY"
  data-config="{"text": {"heading": "Find your perfect colour"}}"
></div>

Il n'y a pas d'application Vue ici à laquelle @complete/@change pourrait se rattacher, le bundle d'intégration les redispatch donc comme des CustomEvents natifs sur l'élément monté : écoutez-les avec addEventListener :

document
  .querySelector("[data-hair-treatments]")
  .addEventListener("hair-treatments:complete", (event) => {
    console.log(event.detail) // ConsultationSelections
  })