timeline-worker

v0.1.0

Published

2 months ago

Lightweight calendar library built for the service and industrial sectors.

0High
0Medium
0Low

mindevl

timeline calendar scheduler planning gantt task javascript ui

timeline-worker

Timeline-worker est une bibliothèque légère d'interface chronologique/calendrier développée en JavaScript natif. Elle affiche une grille de chronologie avec des tâches déplaçables et une vue calendrier mensuelle, avec une configuration minimale.

Installation

npm install timeline-worker

Build

npm run build

Outputs:

dist/index.esm.js (ESM)
dist/index.umd.js (UMD / browser)

Démarrage rapide (ESM)

import { createTimeline } from "timeline-worker";

const container = document.querySelector("#timeline");

const timeline = createTimeline(container, {
  date: new Date(),
  rows: [
    { id: "01", label: "Alice", progress: 20 },
    { id: "02", label: "Bob", progress: 80 }
  ],
  events: [
    {
      id: "task-1",
      rowId: "01",
      title: "Tâche A",
      description: "Préparation",
      start: new Date(2026, 0, 5),
      end: new Date(2026, 0, 8),
      color: "#2563eb"
    }
  ]
});

Exemples avec frameworks

React

import { useEffect, useRef } from "react";
import { createTimeline } from "timeline-worker";

export function TimelineView({ rows, events }) {
  const containerRef = useRef(null);
  const instanceRef = useRef(null);

  useEffect(() => {
    if (!containerRef.current) return;
    instanceRef.current = createTimeline(containerRef.current, { rows, events });
    return () => instanceRef.current?.destroy();
  }, [rows, events]);

  return <div ref={containerRef} />;
}

Vue 3

<template>
  <div ref="container"></div>
</template>

<script setup>
import { onBeforeUnmount, onMounted, ref, watch } from "vue";
import { createTimeline } from "timeline-worker";

const props = defineProps({ rows: Array, events: Array });
const container = ref(null);
let instance = null;

onMounted(() => {
  instance = createTimeline(container.value, { rows: props.rows, events: props.events });
});

watch(
  () => [props.rows, props.events],
  () => {
    instance?.updateRows(props.rows || []);
    instance?.updateEvents(props.events || []);
  }
);

onBeforeUnmount(() => instance?.destroy());
</script>

Démarrage rapide

<div id="timeline"></div>
<script src="./dist/index.umd.js"></script>
<script>
  const container = document.querySelector("#timeline");
  const timeline = TimelineWorker.createTimeline(container, {
    date: new Date(),
    rows: [{ id: "01", label: "Alice", progress: 20 }],
    events: [
      {
        id: "task-1",
        rowId: "01",
        title: "Task A",
        start: new Date(2026, 0, 5),
        end: new Date(2026, 0, 8),
        color: "#2563eb"
      }
    ]
  });
</script>

API

`createTimeline(container, options)`

Crée une timeline dans container.

Required

container (HTMLElement) target element

Options de la chronologie

date (Date) date de départ pour la vue
view ("day" | "week" | "month" | "year" | "custom") vue initiale
daysToShow (number) nombre de jours pour la vue "custom"
rows (Array) lignes de la chronologie
events (Array) événements de la chronologie
columns (Array) colonnes personnalisées (voir Colonnes)
locale (string, par défaut "fr-FR")
startOfWeek (0-6, par défaut 1) index du début de semaine (0=dimanche)
hideWeekends (boolean, par défaut false) masquer samedi/dimanche
maxSpanDays (number, par défaut 366) durée maximale à afficher par événement
injectStyles (boolean, par défaut true) injecter les styles de base dans <head>
classPrefix (string, par défaut "tw") préfixe CSS pour toutes les classes
views (Array, par défaut ["day","week","month","year"]) boutons de vue disponibles
viewLabels (object) mappage des labels, ex : { day: "Jour", week: "Semaine" }

Bascule de colonne (commutateur de mode)

columnToggle (object | null)
- labelOff (string) label quand inactif
- labelOn (string) label quand actif
- isActive (boolean) état initial
- valueOff (string) value used for parameters when inactive
- valueOn (string) value used for parameters when active

Synchronisation des paramètres (persistance d'état)

timelineParameters (object) état initial depuis votre application :
- display_mode (string) valeur utilisée pour columnToggle
- display_view ("Day" | "Week" | "Month" | "Year" | "Custom")
- hide_weekends (boolean)
onParametersChange (function) appelée lors des changements UI :
- Signature : (params) => void
- Exemple d'objet retourné :
  - { display_mode: "Chantier", display_view: "Month", hide_weekends: true }

Callbacks

onEventChange(updatedEvent) lorsqu'un événement est déplacé/redimensionné
onEventDoubleClick(event)
onEventContextMenu({ event, contextEvent })
onDayClick(payload)
onDayDoubleClick(payload)
onToggleColumns(isActive) lors du changement de la bascule de colonne

Valeur de retour

Une instance avec :

updateEvents(events)
updateRows(rows)
updateColumns(columns)
setDate(date)
setView(view)
setDaysToShow(days)
refresh()
destroy()

`createCalendar(container, options)`

Vue calendrier mensuelle.

Options du calendrier

date (Date)
events (Array) voir Événements calendrier
locale (string, par défaut "fr-FR")
startOfWeek (0-6, par défaut 1)
maxSpanDays (number)
injectStyles (boolean, par défaut true)
classPrefix (string, par défaut "tw")

Valeur de retour

updateEvents(events)
setDate(date)
refresh()
destroy()

Formats de données

Lignes

{
  id: string,
  label?: string,
  progress?: number,
  // Custom fields are allowed for custom columns
  [key: string]: unknown
}

Événements (chronologie)

{
  id: string,
  rowId: string,
  title: string,
  description?: string,
  start: Date,
  end: Date,
  color?: string,
  avatarUrl?: string,
  meta?: { striped?: boolean }
}

Événements (calendrier)

{
  id: string,
  title: string,
  start: Date,
  end: Date
}

Colonnes

{
  key: string,
  label: string,
  width?: number | string,
  className?: string,
  format?: (value, row) => string
}

Personnalisation du style

La bibliothèque injecte des styles de base par défaut. Pour fournir vos propres styles :

createTimeline(container, { injectStyles: false, classPrefix: "my" });

Puis surchargez les classes comme :

.my-timeline
.my-timeline-row
.my-timeline-event

Packaging pour npm

Ce dépôt expose déjà :

main : dist/index.umd.js
module : dist/index.esm.js
exports : ESM + UMD

Avant de publier, exécutez :

npm run build

FAQ / Dépannage

Rien ne s'affiche
Vérifiez que votre container existe et a une taille non nulle. Vérifiez aussi les erreurs dans la console.

J'ai mis à jour les données mais l'UI n'a pas changé
Utilisez updateRows / updateEvents pour rafraîchir la chronologie, ou refresh() après modification des options.

Le menu contextuel se ferme immédiatement au clic droit
Utilisez la logique du fichier démo par défaut ou empêchez la propagation de l'événement clic droit.

Puis-je désactiver les styles intégrés ?
Oui : mettez injectStyles: false et fournissez vos propres styles.

Licence

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

timeline-worker

Installation

Build

Démarrage rapide (ESM)

Exemples avec frameworks

React

Vue 3

Démarrage rapide

API

createTimeline(container, options)

Required

Options de la chronologie

Bascule de colonne (commutateur de mode)

Synchronisation des paramètres (persistance d'état)

Callbacks

Valeur de retour

createCalendar(container, options)

Options du calendrier

Valeur de retour

Formats de données

Lignes

Événements (chronologie)

Événements (calendrier)

Colonnes

Personnalisation du style

Packaging pour npm

FAQ / Dépannage

Licence

`createTimeline(container, options)`

`createCalendar(container, options)`