Hooks SmartCommon

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

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

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.

É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.

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;

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, ... }

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.',
});

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.

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

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;

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;

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.

<note tip>Pour un cache API avec stratégies, préférez useCachedQuery. Pour la synchronisation offline, utilisez useSyncClient.</note>

Cache de données avec stratégies réseau/cache.

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

const { data, isLoading, isFromCache, isStale, error, refetch, invalidate } = useCachedQuery({
  db: dexieInstance,           // instance Dexie
  store: 'items',              // nom du store
  key: 'items-list',           // clé de cache
  fetchFn: () => api.private.get('items').json(),  // fonction de fetch
  strategy: 'network-first',   // 'network-first' | 'cache-first' | 'swr'
  ttl: 3600000,                // durée de vie du cache (1h)
  staleTime: 60000,            // seuil de péremption (1min)
  enabled: true                // activer/désactiver
});

Stratégies disponibles :

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

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,
});

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" />;

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"

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]);

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,...
};

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

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

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

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

Drag and drop pour listes (réordonnancement).

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

const { onDragStart, onDragOver, onDrop } = useListDnD({
  items: myItems,
  onReorder: (newItems) => console.log('Nouvel ordre:', newItems)
});

// Utilisation sur chaque élément de liste
<div
  draggable
  onDragStart={(e) => onDragStart(e, index)}
  onDragOver={onDragOver}
  onDrop={(e) => onDrop(e, index)}
>
  {item.label}
</div>

Informations sur la fenêtre du navigateur.

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

const window = useWindow();

// Dimensions
const { w, h } = window.get('windowDimension');

// Orientation
const orientation = window.get('orientation'); // 'landscape' | 'portrait'

// Scroll
const { x, y } = window.get('scroll');

// Mode sombre du système
const darkMode = window.get('darkMode'); // true | false

Détection responsive desktop/mobile.

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

const isDesktop = useIsDesktop();

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

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');

<note tip>Similaire à useStates mais avec une API plus directe : les valeurs initiales sont passées directement, sans wrapper initialStates.</note>

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.

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