Hooks SmartCommon

SmartCommon fournit un ensemble de hooks React pour faciliter le développement d'applications.

Hooks globaux

Ces hooks utilisent le contexte de l'application et doivent être utilisés à l'intérieur du Provider.

useApi

Gestion des appels API avec authentification JWT automatique.

import { useApi } from '@cap-rel/smartcommon';

const api = useApi();

// Connexion
await api.login({ login, password, rememberMe: true });

// Déconnexion
await api.logout();

// Requête authentifiée
const data = await api.private.get('items').json();

// Requête publique
const info = await api.public.get('public/info').json();

Voir Requêtes API pour plus de détails.

useGlobalStates

État global avec persistance automatique (localStorage/sessionStorage).

import { useGlobalStates } from '@cap-rel/smartcommon';

const gst = useGlobalStates();

// Lire
const user = gst.get('user');
const theme = gst.get('settings.theme');

// Écrire (persistant)
gst.local.set('user', userData);

// Écrire (session uniquement)
gst.session.set('tempData', data);

// Supprimer
gst.unset('user');

// Accès direct aux valeurs
const { user, settings } = gst.values;

Voir Stockage de données pour plus de détails.

useNavigation

Utilitaires de navigation pour react-router-dom.

import { useNavigation } from '@cap-rel/smartcommon';

const nav = useNavigation();

// Navigation programmatique
nav.navigate('/dashboard');
nav.navigate(-1); // Retour arrière

// Informations de route
const { pathname, search, hash } = nav.location;

// Paramètres d'URL
const { id } = nav.params;

useLibConfig

Accès à la configuration de l'application.

import { useLibConfig } from '@cap-rel/smartcommon';

const config = useLibConfig();

console.log(config.debug);     // true/false
console.log(config.api);       // { prefixUrl, timeout, ... }

useConfirm

Dialogues de confirmation et d'alerte (nécessite ConfirmProvider).

import { useConfirm } from '@cap-rel/smartcommon';

const { confirm, alert } = useConfirm();

// Confirmation (retourne true/false)
const handleDelete = async () => {
  const ok = await confirm({
    type: 'delete',        // 'danger' | 'delete' | 'warning' | 'info'
    title: 'Supprimer ?',
    message: 'Cette action est irréversible.',
    detail: item.label,    // détail optionnel
    confirmText: 'Supprimer',
    cancelText: 'Annuler',
  });

  if (ok) {
    await api.del(`items/${item.id}`);
  }
};

// Alerte (un seul bouton OK)
await alert({
  type: 'info',
  title: 'Information',
  message: 'Opération terminée avec succès.',
});

usePWAUpdate

Gestion des mises à jour PWA via Service Worker.

import { usePWAUpdate } from '@cap-rel/smartcommon';

const { updateAvailable, checkForUpdates, applyUpdate } = usePWAUpdate({
  autoReload: false,
  checkInterval: 60000,
});

Voir PWA pour plus de détails.

Hooks locaux

Ces hooks gèrent un état local au composant.

useStates

Gestion d'état local avec path notation.

import { useStates } from '@cap-rel/smartcommon';

const st = useStates({
  initialStates: {
    count: 0,
    user: { name: '', email: '' },
    items: []
  },
  debug: true
});

// Lire
st.get('count');           // 0
st.get('user.name');       // ''
st.get('items[0]');        // undefined

// Écrire
st.set('count', 1);
st.set('user.name', 'John');
st.set('items[]', { id: 1 });  // Push dans le tableau

// Écrire avec fonction
st.set('count', prev => prev + 1);

// Supprimer
st.unset('user.email');
st.unset('items[0]');

// Accès direct
const { count, user, items } = st.values;

useForm

Gestion de formulaires avec état et erreurs.

import { useForm } from '@cap-rel/smartcommon';

const form = useForm({
  defaultValues: {
    name: '',
    email: ''
  },
  debug: true
});

// Lire les valeurs
const name = form.get('values.name');

// Définir un champ avec validation
form.setField({
  name: 'email',
  value: 'test@example.com',
  errors: {
    required: { condition: !value },
    format: { condition: !isValidEmail(value) }
  }
});

// Vérifier les erreurs
const hasEmailError = form.get('errors.email.required');

// Accès direct
const { values, errors, isFormSubmitting, isFormSubmitted } = form;

useDb

Base de données IndexedDB via Dexie avec logging automatique.

import { useDb } from '@cap-rel/smartcommon';

const db = useDb({
  name: 'myApp',
  version: 1,
  stores: {
    items: 'id++, name, category, createdAt',
    categories: 'id++, name'
  },
  debug: true
});

// CRUD via Dexie
await db.items.add({ name: 'Item 1' });
const all = await db.items.toArray();
await db.items.update(id, { name: 'Updated' });
await db.items.delete(id);

Ajoute automatiquement createdAt, updatedAt et une table logs.

Voir Stockage de données pour plus de détails.

useCachedQuery

Cache de requêtes avec stratégies réseau/cache. C'est le hook à utiliser pour une donnée lue depuis l'API et relue souvent : dictionnaires, configuration, listes de référence.

Déclarer le store de cache

Le hook stocke ses entrées dans un store Dexie que vous devez déclarer, indexé sur key :

// src/db/index.js
export const db = new Db({
  name: "myapp",
  version: 1,
  stores: {
    queryCache: 'key',
    // ... vos autres stores
  },
}).db;

Utilisation

import { useCachedQuery, CACHE_STRATEGIES } from '@cap-rel/smartcommon';
import { db } from 'src/db';

const {
  data,         // donnee, du reseau ou du cache
  isLoading,    // true pendant la recuperation
  isFromCache,  // true si la donnee vient du cache
  isStale,      // true si la donnee cachee est perimee
  error,        // erreur eventuelle
  lastFetch,    // timestamp de la derniere recuperation reussie
  refetch,      // relance la requete
  invalidate,   // vide le cache et relance
} = useCachedQuery({
  db: db.instance,             // instance Dexie (db.instance, pas db)
  store: 'queryCache',         // nom du store declare ci-dessus
  key: 'countries',            // cle de cache, unique par requete
  fetchFn: () => api.private.get('dictionaries/countries').json(),
  strategy: CACHE_STRATEGIES.CACHE_FIRST,
  ttl: 86400000,               // duree de vie du cache, defaut 1h
  staleTime: 60000,            // seuil de peremption, defaut 1min
  enabled: true,               // desactive la requete si false
});

Choisir la stratégie

ttl et staleTime, à ne pas confondre

staleTime est donc toujours inférieur à ttl. Un dictionnaire type se règle sur un ttl de 24 h.

Invalider

// Apres une ecriture qui rend le cache obsolete
await api.private.post('items', { json: payload });
await invalidate();     // vide l'entree et relance la requete

refetch() relance la requête sans vider le cache : la valeur cachée reste disponible si le réseau échoue.

Comportement hors ligne

Le hook s'appuie sur useOnlineStatus. Hors ligne, il sert le cache s'il existe et n'émet aucune requête. Testez isFromCache pour signaler à l'utilisateur qu'il consulte une donnée stockée localement.

{isFromCache && isStale && (
  <span className="text-xs italic">Données enregistrées le {formatDate(lastFetch)}</span>
)}

Voir Stockage de données et Synchronisation offline.

useOnlineStatus

Détection de la connexion réseau avec health check optionnel.

import { useOnlineStatus } from '@cap-rel/smartcommon';

const { isOnline, isServerReachable, lastOnline, checkNow } = useOnlineStatus({
  healthCheckUrl: '/api/health',
  healthCheckInterval: 30000,
  stabilityDelay: 2000,
  timeout: 5000,
});

useAuthenticatedImage

Chargement d'images authentifiées avec cache IndexedDB.

import { useAuthenticatedImage } from '@cap-rel/smartcommon';

const { src, isLoading, isFromCache, error } = useAuthenticatedImage({
  db: db.instance,              // instance Dexie
  url: `/api/users/${id}/photo`,
  token: accessToken,
  ttl: 86400000,                // durée de cache: 24h
  staleTime: 3600000,           // stale après 1h (refresh en arrière-plan)
  placeholder: '/images/default.png',
});

return <img src={src} alt="Photo" />;

Hooks utilitaires

useIntl

Formatage de dates et nombres avec l'API Intl.

import { useIntl } from '@cap-rel/smartcommon';

const intl = useIntl();

// Formater une date
const formatted = intl.DateTimeFormat(Date.now());
// "11/01/2025, 14:30:00"

// Avec options personnalisées
const dateOnly = intl.DateTimeFormat(Date.now(), 'fr-FR', {
  year: 'numeric',
  month: 'long',
  day: 'numeric'
});
// "11 janvier 2025"

useAnimation

Gestion d'animations avec Framer Motion.

import { useAnimation } from '@cap-rel/smartcommon';

const { start, animations, setAnimations } = useAnimation({
  fadeIn: { value: false, state: null },
  slideIn: { value: false, state: null }
});

// start devient true après le premier rendu
// Utilisez-le pour déclencher des animations d'entrée

useEffect(() => {
  if (start) {
    setAnimations(prev => ({
      ...prev,
      fadeIn: { ...prev.fadeIn, state: 'visible' }
    }));
  }
}, [start]);

useFile

Utilitaires pour la gestion de fichiers.

import { useFile } from '@cap-rel/smartcommon';

const { resizeImage } = useFile();

// Redimensionner une image
const handleFileChange = async (e) => {
  const file = e.target.files[0];

  const base64 = await resizeImage(file, {
    maxWidth: 1920,
    maxHeight: 1080,
    quality: 85
  });

  console.log(base64); // data:image/jpeg;base64,...
};

useVariantMerger

Fusion de props avec variants de composants (usage interne principalement).

import { useVariantMerger } from '@cap-rel/smartcommon';

const MyComponent = (props) => {
  const { variantProps, mergeProps, mergeQuickProps, setParams } = useVariantMerger('MyComponent', props);

  return (
    <div {...mergeProps('container', p => ({
      ...p,
      className: `base-class ${p.className || ''}`
    }))}>
      {variantProps.children}
    </div>
  );
};

useListDnD

Drag and drop pour listes (réordonnancement). Prend en paramètre la fonction set de useStates.

import { useStates, useListDnD } from '@cap-rel/smartcommon';

const st = useStates({
  initialStates: {
    items: [{ id: 1, label: 'A' }, { id: 2, label: 'B' }],
    dragIndex: null,
  }
});

const { onDragStart, onDragOver, onDrop } = useListDnD(st.set);

// Utilisation sur chaque élément de liste
{st.get('items').map((item, index) => (
  <div
    key={item.id}
    draggable
    onDragStart={(e) => onDragStart(e, 'dragIndex', 'items')}
    onDragOver={(e) => onDragOver(e, 'dragIndex', index, 'items', st.get('items'))}
    onDrop={() => onDrop('dragIndex')}
  >
    {item.label}
  </div>
))}

Paramètres des callbacks :

useCalculator

Contrôle programmatique du composant Calculator (nécessite un Calculator dans l'arbre de composants).

import { useCalculator, Calculator } from '@cap-rel/smartcommon';

const MyComponent = () => {
  const { isOpen, open, close, toggle } = useCalculator();

  return (
    <>
      <button onClick={() => open((result) => console.log('Résultat:', result))}>
        Ouvrir la calculatrice
      </button>
      <Calculator />
    </>
  );
};

useWindow

Informations sur la fenêtre du navigateur.

import { useWindow } from '@cap-rel/smartcommon';

const { orientation, windowDimension, scroll, darkMode } = useWindow();

// Dimensions
const { w, h } = windowDimension;

// Orientation : 'landscape' | 'portrait'
console.log(orientation);

// Position de scroll
const { x, y } = scroll;

// Mode sombre du système : true | false
console.log(darkMode);

useIsDesktop

Détection responsive desktop/mobile.

import { useIsDesktop } from '@cap-rel/smartcommon';

const isDesktop = useIsDesktop();

if (isDesktop) {
  return <DesktopLayout />;
}
return <MobileLayout />;

useStatesWorking

Gestion d'état local simplifiée avec paths imbriqués.

import { useStatesWorking } from '@cap-rel/smartcommon';

const { states, set, get, unset } = useStatesWorking({
  count: 0,
  user: { name: '', email: '' }
});

// Lire
get('user.name');

// Écrire (path notation)
set('user.name', 'John');
set('items[0]', { id: 1 });
set('items.[]', newItem);  // Push dans le tableau

// Supprimer
unset('user.email');

useSyncClient

Synchronisation offline/online avec gestion de conflits.

import { useSyncClient } from '@cap-rel/smartcommon';

const sync = useSyncClient({
  apiUrl: import.meta.env.VITE_API_URL,
  getAccessToken: () => api.accessToken,
  scope: ['items', 'categories']
});

// État de connexion
const { isOnline, isServerReachable } = sync;

// État de synchronisation
const { isInitialized, isSyncing, pendingCount, conflictsCount, lastSyncTime, syncError } = sync;

// Opérations CRUD locales (fonctionnent hors-ligne)
await sync.create('items', { ref: 'IT-001', label: 'Item 1' });
await sync.update('items', id, { label: 'Item modifié' });
await sync.remove('items', id);
await sync.upsert('items', { id, label: 'Créer ou modifier' });

// Lecture locale
const item = await sync.getEntity('items', id);
const items = await sync.queryEntities('items', { category: 'A' });

// Synchronisation manuelle
await sync.sync();      // Push + Pull
await sync.push();      // Envoyer les changements locaux
await sync.pull();      // Récupérer les changements serveur

// Gestion des conflits
const conflicts = await sync.getConflicts();
await sync.resolveConflict(conflictId, 'client'); // 'client' | 'server' | mergedData

// Enregistrement de l'appareil
await sync.register({ deviceName: 'Mon téléphone' });

// Réinitialisation
await sync.reset();

Voir Synchronisation pour plus de détails.

Tableau récapitulatif

Voir aussi

• SmartCommon - Liste des composants
• Requêtes API - Documentation détaillée useApi
• Stockage de données - Documentation détaillée stockage