Hapio est une solution « headless ». Nous mettons à votre disposition l'API de réservation et de planification (services, ressources, plannings, créneaux disponibles) et c'est vous qui concevez l'expérience que vos clients verront. Cela fonctionne bien pour le processus de réservation en lui-même, mais tôt ou tard, la plupart des projets ont besoin d'un véritable calendrier : une vue hebdomadaire dans laquelle le personnel peut déplacer les réservations, une vue journalière indiquant les créneaux disponibles, et une vue mensuelle pour avoir une vue d'ensemble.

Jusqu'à présent, cela impliquait soit de recourir à une bibliothèque de calendriers disponible dans le commerce, soit d'en créer une de toutes pièces. Aucune de ces deux options n'est idéale lorsque votre modèle de données est déjà hébergé sur Hapio.

Nous lançons aujourd’hui Hapio Calendar, un composant de calendrier open source complet pour React 19 et shadcn/ui. Il propose des vues hebdomadaire, journalière, mensuelle et sous forme de liste, ainsi que des fonctionnalités de glisser-déposer et de redimensionnement. Il prend également en charge les fuseaux horaires spécifiques à chaque calendrier et les événements récurrents, et est conçu pour s’intégrer directement à l’API Hapio dès son installation. Il est distribué sous licence MIT et ne propose pas de formule premium.

La vue hebdomadaire. Les horaires d'ouverture sont surlignés, les réservations apparaissent sur la grille et la ligne rouge indique l'heure actuelle.

Fonctionnalités

Hapio Calendar est un calendrier complet, et non un sélecteur de date. Dès son installation, il vous offre :

• Quatre modes d'affichage : semaine, jour, mois et liste. Le mode d'affichage et la date peuvent être inclus dans l'URL (facultatif) afin de permettre le partage des liens.
• Glisser-déposer, redimensionnement et modification au clavier. Les événements peuvent être déplacés et redimensionnés à l'aide de la souris ou du clavier, via un menu d'actions accessible depuis chaque événement. Vous pouvez également faire glisser des éléments depuis l'extérieur du calendrier, par exemple depuis une liste de réservations non attribuées.
• Les fuseaux horaires sont gérés correctement. Chaque calendrier dispose de son propre fuseau horaire, et vous pouvez le modifier sans avoir à le remonter. Les jours comptant 23 ou 25 heures s'affichent correctement, ce qui évite que les changements d'heure d'été ne perturbent la mise en page.
• Règles de réservation. Horaires d'ouverture, vérifications des chevauchements et vérifications personnalisées. Lorsqu'une réservation est refusée, le calendrier indique à l'utilisateur la raison du refus.
• Enregistrements optimistes. Une modification s'affiche immédiatement, reste en attente pendant que votre API la sauvegarde, et est annulée si la sauvegarde échoue.
• Événements récurrents. Traitement des séries selon la norme RFC 5545, y compris l'expansion côté serveur lorsque celui-ci connaît la zone et la date.
• Accessibilité intégrée. Déplacement à l'aide du clavier, annonces en temps réel et vérification de la sélection à chaque exemple.
• Localisation. Plusieurs langues, dont le suédois, et des mises en page de droite à gauche.
• Rendu côté serveur. Compatible avec le SSR et les composants serveur React, et accompagné d'un guide sur la politique de sécurité du contenu (CSP).

La vue mensuelle, avec les numéros de semaine ISO, les événements s'étalant sur plusieurs jours et une mention « +N autres » pour les jours chargés.

Conçu pour Hapio

Le calendrier est un composant générique, mais il a été conçu en tenant compte du fonctionnement réel d'un projet Hapio. L'intégration repose sur trois callbacks :

1. Chargement. Une source d'événements récupère les réservations pour chaque plage de dates visible à partir d'un itinéraire hébergé sur votre serveur.
2. Réservation. Les créneaux disponibles proposés par Hapio s'affichent comme des plages horaires libres. Lorsqu'un client ou un membre du personnel en sélectionne un, votre application crée la réservation.
3. Reprogrammer. Appel des actions de glisser-déposer et des mouvements au clavier onEventChange. Si Hapio refuse la modification (la ressource n'est pas disponible, le créneau se situe en dehors des horaires d'ouverture), le calendrier annule la modification et affiche le motif.

Modifier la date d'une réservation en la faisant glisser. Le créneau initial reste grisé jusqu'à ce que votre serveur confirme la modification.

Tout comme pour notre panneau d'administration, votre jeton API n'est jamais transmis au navigateur. Votre serveur communique avec Hapio via le hapio-sdk , et le calendrier communique uniquement avec votre serveur. Les autorisations associées au jeton sont gérées par Hapio, comme d'habitude.

Vous êtes propriétaire du code

Nous ne voulions pas proposer un énième calendrier « boîte noire ». Hapio Calendar est divisé en trois niveaux, et c'est vous qui décidez jusqu'où vous souhaitez aller :

• @hapio/calendar-core — la logique sans framework : mise en page, calculs liés au fuseau horaire, règles, récurrence. Pas de React.
• @hapio/calendar-react — des hooks « headless » au-dessus du noyau. Apportez votre propre balisage et vos propres styles.
• Le @hapio registre shadcn — le composant stylisé et prêt à l'emploi. Il est installé à l'aide de l'interface de ligne de commande shadcn et copié dans votre projet ; vous pouvez donc modifier ces fichiers comme n'importe quel autre composant ShadCN.

La plupart des projets commenceront par le composant « registry » et n'auront recours aux « hooks » que s'ils ont besoin d'une fonctionnalité particulière. Quoi qu'il en soit, tout peut être modifié.

Pour commencer

Vous devez disposer de React 19.2 ou d'une version ultérieure, ainsi que d'une application shadcn/ui basée sur Tailwind CSS 4 (avec la base Radix ou Base UI). Pour le rendu côté serveur, Node 22.12 ou une version ultérieure est requise.

Commencez par ajouter le @hapio registre vers votre components.json:

{
  "registries": {
    "@hapio": "https://calendar.hapio.io/r/{name}.json"
  }
}

Ajoutez ensuite le calendrier :

npx shadcn@latest add @hapio/hapio-calendar

Cela copie le composant dans components/hapio-calendar/, attire le shadcn button, popover et scroll-area composants, et les installe @hapio/calendar-react et temporal-polyfill. Chargez le polyfill une seule fois à la racine de votre application, puis affichez le calendrier en lui attribuant une hauteur et un fuseau horaire :

<HapioCalendar
  events={events}
  timeZone="Europe/Stockholm"
  className="h-[36rem]"
/>

Le composant de base est en lecture seule. Ajouter calendar-selection pour permettre aux utilisateurs de choisir des horaires, calendar-editing pour déplacer et redimensionner les événements, et calendar-external-draggable pour y déposer des objets depuis l'extérieur. Le guide d'installation explique chaque étape en détail, et Ton premier calendrier et prend le relais à partir de là.

Hapio Calendar est développé avec React 19, shadcn/ui, TypeScript, Tailwind CSS et le polyfill Temporal, et est distribué sous licence MIT. Chaque exemple est soumis à des contrôles d'accessibilité automatisés, et la suite de tests est fournie avec le code source. Les tickets et les pull requests sont les bienvenus.

Parcourir le exemples, lire le documents, ou exécuter npx shadcn@latest add @hapio/hapio-calendar et essayez-le dès aujourd'hui dans votre propre projet.

Liens : calendar.hapio.io · Dépôt GitHub · Documentation Hapio · Portail Hapio