@synapxlab/timeline

Démo interactive

Glissez, lancez, utilisez la molette ou les touches ← → Début. L'item central est toujours la semaine active.

Installation

# npm
npm install @synapxlab/timeline

# pnpm
pnpm add @synapxlab/timeline

# yarn
yarn add @synapxlab/timeline

Démarrage rapide

import { WeekTimeline } from '@synapxlab/timeline';
import '@synapxlab/timeline/style';

const timeline = new WeekTimeline({
  container:      document.getElementById('timeline'),
  theme:          'auto',         // suit le système
  storageKey:     'mon-app-week', // persistance localStorage
  firstDayOfWeek: 1,              // lundi
  onWeekChange(detail) {
    console.log(detail.week.start, '→', detail.week.end);
  },
});

Pour un usage via <script> UMD :

<link   rel="stylesheet" href="week-timeline.css">
<script src="week-timeline.umd.cjs"></script>
<script>
  const tl = new WeekTimeline({ container: document.getElementById('tl') });
</script>

Options

API publique

Événements DOM

La timeline émet des événements natifs CustomEvent sur son nœud conteneur.

// Écoute native
container.addEventListener('weekchange', (e) => {
  const { date, week } = (e as CustomEvent).detail;
  console.log('Semaine :', week.start, '→', week.end);
});

// Via l'API .on()
timeline.on('weekchange', (detail) => {
  console.log(detail.week.start);
});

Adaptateur FullCalendar

Liaison bidirectionnelle : la timeline pilote FullCalendar et vice-versa.

import { WeekTimeline, bindTimelineToCalendar } from '@synapxlab/timeline';
import { Calendar } from '@fullcalendar/core';

const calendar = new Calendar(calendarEl, { /* options FullCalendar */ });
calendar.render();

const timeline = new WeekTimeline({ container: timelineEl });

// Liaison bidirectionnelle
const unbind = bindTimelineToCalendar(timeline, calendar);

// Pour délier plus tard
unbind();

Ou via l'adaptateur bas niveau :

import { createFullCalendarAdapter } from '@synapxlab/timeline';

const adapter = createFullCalendarAdapter(calendar);
timeline.connectAdapter(adapter);

Thème & dark mode

Trois modes disponibles via l'option theme :

• 'light' — thème clair (défaut)
• 'dark' — thème sombre forcé
• 'auto' — suit prefers-color-scheme en temps réel via MediaQueryList

En mode manuel, basculer le thème en toggleant la classe CSS :

// Forcer le dark sur le conteneur
container.querySelector('.wt').classList.toggle('wt--dark', true);

// Ou via attribut data
container.setAttribute('data-theme', 'dark');

Variables CSS

Personnalisez l'apparence via des propriétés CSS sur le conteneur ou globalement :

/* Exemple : couleur d'accent personnalisée */
#mon-conteneur {
  --wt-accent:        #6366f1;
  --wt-item-bg-active: #6366f1;
}

Fonctionnalités

• Drag & flick avec momentum physique et snap au centre
• Animation spring au snap (rebond amorti, 420 ms)
• Effet de profondeur scale + opacité pendant le glissement
• Label de plage de dates avec Intl.DateTimeFormat.formatRange — sans répétition du mois ("18 – 24 août")
• Mois complet sur la semaine sélectionnée, abrégé (3 lettres) aux frontières
• Label d'année aux frontières annuelles
• Point indicateur sur la semaine courante
• Extension proactive de la liste pendant le drag (seuil × 2)
• Navigation molette avec debounce, clavier (← → Début) et tactile
• Feedback haptique sur mobile (navigator.vibrate)
• Thème sombre automatique via prefers-color-scheme
• Persistance localStorage configurable
• Adaptateur FullCalendar bidirectionnel inclus
• Propriétés CSS personnalisables (--wt-accent, --wt-bg…)
• Mode compact via compact: true
• ResizeObserver pour la gestion du redimensionnement
• ESM + UMD — drop-in dans tous les frameworks

Compatibilité