🔄 Qu'est-ce qu'un composable ?

Un composable est une fonction JavaScript qui utilise la Composition API de Vue pour encapsuler et réutiliser de la logique stateful (avec état) entre plusieurs composants.

La situation sans composable

// ❌ Duplication : même logique dans deux composants
const ComponentA = {
  setup() {
    const x = ref(0);
    const y = ref(0);
    function update(event) { x.value = event.pageX; y.value = event.pageY; }
    window.addEventListener('mousemove', update);
    onUnmounted(() => window.removeEventListener('mousemove', update));
    return { x, y };
  }
};

const ComponentB = {
  setup() {
    // Exactement la même logique copiée-collée...
    const x = ref(0);
    const y = ref(0);
    // ...
  }
};

Avec un composable

// ✅ Logique extraite dans un composable réutilisable
function useMouse() {
  const x = ref(0);
  const y = ref(0);

  function update(event) {
    x.value = event.pageX;
    y.value = event.pageY;
  }

  onMounted(()  => window.addEventListener('mousemove', update));
  onUnmounted(() => window.removeEventListener('mousemove', update));

  return { x, y };  // Retourner les refs pour que l'appelant reste réactif
}

// Utilisation dans n'importe quel composant
const ComponentA = {
  setup() {
    const { x, y } = useMouse();  // Propre, réutilisable
    return { x, y };
  }
};

Composables vs Mixins (Vue 2)

📐 Conventions des composables

Règles à respecter

// ✅ 1. Nommer avec le préfixe "use"
function useToggle() { /* ... */ }
function useLocalStorage() { /* ... */ }
function useFetch() { /* ... */ }

// ✅ 2. Retourner des refs et des fonctions (pas des valeurs brutes)
function useCounter() {
  const count = ref(0);
  function increment() { count.value++; }
  return { count, increment };  // count est une ref — reste réactif après déstructuration
}

// ✅ 3. Accepter des paramètres réactifs (ref ou computed)
function useDouble(n) {
  // Accepter n comme ref ou valeur brute grâce à toValue()
  const { toValue } = Vue;
  return computed(() => toValue(n) * 2);
}

// ❌ 4. Ne PAS appeler dans des if, for, ou setTimeout
function setup() {
  if (condition) {
    const { x } = useMouse(); // ❌ Interdit — doit être au niveau racine
  }

  // ✅ Correct
  const { x } = useMouse();
  // Ensuite utiliser x dans un computed ou watch conditionnel
}

Structure type d'un composable

const { ref, onMounted, onUnmounted, watch } = Vue;

function useXxx(param) {
  // 1. State local au composable
  const data    = ref(null);
  const loading = ref(false);
  const error   = ref(null);

  // 2. Logique (watchers, lifecycle hooks, etc.)
  onMounted(() => {
    // Initialisation
  });

  onUnmounted(() => {
    // Nettoyage — crucial pour éviter les fuites mémoire !
  });

  // 3. Fonctions exposées
  function faire() { /* ... */ }

  // 4. Retourner l'API publique du composable
  return { data, loading, error, faire };
}

💾 useLocalStorage

Synchroniser automatiquement une ref avec localStorage : lecture au démarrage, sauvegarde à chaque changement.

const { ref, watch } = Vue;

function useLocalStorage(key, valeurDefaut) {
  // Initialiser depuis localStorage ou avec la valeur par défaut
  function lire() {
    try {
      const item = localStorage.getItem(key);
      return item !== null ? JSON.parse(item) : valeurDefaut;
    } catch {
      return valeurDefaut;
    }
  }

  const data = ref(lire());

  // Sauvegarder automatiquement à chaque changement
  watch(data, (nouvelleValeur) => {
    try {
      localStorage.setItem(key, JSON.stringify(nouvelleValeur));
    } catch {}
  }, { deep: true }); // deep: true pour les objets/tableaux

  return data;  // Retourner la ref directement (pas un objet)
}

// Utilisation
const compteur = useLocalStorage('compteur', 0);
const prefs    = useLocalStorage('prefs', { theme: 'dark', langue: 'fr' });

// Modifier : synchronisé automatiquement avec localStorage
compteur.value++;
prefs.value.theme = 'light';

🌐 useFetch

Encapsuler une requête HTTP avec gestion automatique de loading et error.

const { ref, watch, toValue, isRef } = Vue;

function useFetch(url) {
  const data    = ref(null);
  const loading = ref(false);
  const error   = ref(null);

  async function fetchData() {
    // Résoudre l'URL (peut être une string, une ref, ou un computed)
    const urlValue = isRef(url) ? url.value : url;
    if (!urlValue) return;

    loading.value = true;
    error.value   = null;
    data.value    = null;

    try {
      const response = await fetch(urlValue);
      if (!response.ok) throw new Error('HTTP ' + response.status);
      data.value = await response.json();
    } catch (err) {
      error.value = err.message;
    } finally {
      loading.value = false;
    }
  }

  // Refetch si l'URL change (utile si url est une ref)
  if (isRef(url)) {
    watch(url, fetchData, { immediate: true });
  } else {
    fetchData();
  }

  return { data, loading, error, refetch: fetchData };
}

// Utilisation
const { data, loading, error } = useFetch('https://jsonplaceholder.typicode.com/todos/1');

// Avec URL réactive
const todoId = ref(1);
const url = computed(() => \`https://jsonplaceholder.typicode.com/todos/\${todoId.value}\`);
const { data: todo } = useFetch(url); // Refetch automatiquement quand todoId change

⏱️ useDebounce

Retarder la propagation d'une valeur pour éviter des appels trop fréquents (saisie dans un champ de recherche, resize...).

const { ref, watch } = Vue;

function useDebounce(source, delai = 300) {
  const debounced = ref(typeof source === 'object' ? source.value : source);
  let timer = null;

  watch(
    () => (source && typeof source === 'object' ? source.value : source),
    (nouvelleValeur) => {
      clearTimeout(timer);
      timer = setTimeout(() => {
        debounced.value = nouvelleValeur;
      }, delai);
    }
  );

  return debounced;
}

// Utilisation classique — champ de recherche
const recherche   = ref('');            // Valeur immédiate (liée à l'input)
const rechercheDB = useDebounce(recherche, 400); // Valeur retardée de 400ms

// rechercheDB ne change qu'après 400ms d'inactivité
watch(rechercheDB, (valeur) => {
  // API appelée seulement quand l'utilisateur s'arrête de taper
  fetchResultats(valeur);
});

🎯 useEventListener

Ajouter et retirer des écouteurs d'événements proprement, avec nettoyage automatique quand le composant est démonté.

const { onMounted, onUnmounted, isRef } = Vue;

function useEventListener(cible, evenement, handler) {
  // cible peut être window, document, un ref d'élément...
  function getCible() {
    return isRef(cible) ? cible.value : cible;
  }

  onMounted(() => {
    getCible()?.addEventListener(evenement, handler);
  });

  onUnmounted(() => {
    // Nettoyage obligatoire pour éviter les fuites mémoire
    getCible()?.removeEventListener(evenement, handler);
  });
}

// ─── Exemples d'utilisation ───

// Détecter la touche Escape
function useKeyPress(touche) {
  const appuyee = ref(false);
  useEventListener(window, 'keydown', (e) => {
    appuyee.value = (e.key === touche);
  });
  useEventListener(window, 'keyup', (e) => {
    if (e.key === touche) appuyee.value = false;
  });
  return appuyee;
}

// Taille de la fenêtre réactive
function useWindowSize() {
  const width  = ref(window.innerWidth);
  const height = ref(window.innerHeight);
  useEventListener(window, 'resize', () => {
    width.value  = window.innerWidth;
    height.value = window.innerHeight;
  });
  return { width, height };
}