@marco.colia/react-fast-scheduler 2.1.1 → 2.2.1

package/README.md

@@ -1,22 +1,52 @@
 # react-fast-scheduler
 
-A lightweight React scheduling library scaffold with CI/CD publishing.
+A lightweight React day scheduler for resource-based booking UIs.
 
-![img.png](https://bg-so-1.zippyimage.com/2026/03/20/9f3bd8a7a76d94f6e110aa0a0bef11d3.png)
+`react-fast-scheduler` gives you a controlled day view with:
+
+- resource columns for staff, rooms, or assets
+- drag and resize interactions
+- date navigation with a built-in toolbar and date picker
+- customizable appointment rendering
+- a simple adapter layer for your backend data
+
+![Scheduler demo](https://res.cloudinary.com/dt74zb1rv/image/upload/v1774457086/Video_del_2026-03-25_17-35-51_kuflee.gif)
 
 ## Install
 
 ```bash
-npm i @marco.colia/react-fast-scheduler
+npm install @marco.colia/react-fast-scheduler
 ```
 
-## Usage
+Peer dependencies:
+
+- `react` `^18 || ^19`
+- `react-dom` `^18 || ^19`
+
+Import the packaged styles once in your app:
 
 ```tsx
-import { useState } from "react";
-import { Scheduler } from "@marco.colia/react-fast-scheduler";
 import "@marco.colia/react-fast-scheduler/styles.css";
-import type { BaseSchedulerResource } from "@marco.colia/react-fast-scheduler";
+```
+
+## Quick Start
+
+The scheduler is a controlled component:
+
+- your app owns `selectedDate`
+- your app fetches appointments for that date
+- the scheduler calls `onSelectedDateChange` when the user navigates
+- your app updates `appointments` and passes the new data back in
+
+```tsx
+import { useEffect, useState } from "react";
+import {
+  Scheduler,
+  applySchedulerAppointmentChange,
+  type BaseSchedulerResource,
+  type SchedulerAppointmentChangeArgs,
+} from "@marco.colia/react-fast-scheduler";
+import "@marco.colia/react-fast-scheduler/styles.css";
 
 type Staff = BaseSchedulerResource<number> & {
   firstName: string;
@@ -26,104 +56,251 @@ type Staff = BaseSchedulerResource<number> & {
 type Appointment = {
   id: number;
   staffId: number;
-  description?: string;
   customerName: string;
   title: string;
-  start: string; // ISO string
-  end: string; // ISO string
+  description?: string;
+  start: string;
+  end: string;
+};
+
+const formatLocalDate = (date: Date) => {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
 };
 
-const initialStaff: Staff[] = [
-  { id: 1, label: "Room A", firstName: "Anna", lastName: "Rossi" },
-  { id: 2, label: "Room B", firstName: "Luca", lastName: "Bianchi" }
-];
-
-const initialAppointments: Appointment[] = [
-  {
-    id: 100,
-    staffId: 1,
-    description: "First consultation",
-    customerName: "Mario Rossi",
-    title: "Consultation",
-    start: "2026-03-20T09:00:00.000Z",
-    end: "2026-03-20T09:30:00.000Z"
-  }
-];
-
-export function SchedulerExample() {
-  const [selectedDate, setSelectedDate] = useState(new Date("2026-03-20T00:00:00.000Z"));
-  const [appointments, setAppointments] = useState<Appointment[]>(initialAppointments);
+export const SchedulerExample = () => {
+  const [staff, setStaff] = useState<Staff[]>([]);
+  const [appointments, setAppointments] = useState<Appointment[]>([]);
+  const [selectedDate, setSelectedDate] = useState(() => new Date());
+
+  const loadStaff = async () => {
+    const response = await fetch("/api/staff");
+    const data = (await response.json()) as Staff[];
+    setStaff(data);
+  };
+
+  const loadAppointments = async (date: Date) => {
+    const response = await fetch(`/api/appointments?date=${formatLocalDate(date)}`);
+    const data = (await response.json()) as Appointment[];
+    setAppointments(data);
+  };
+
+  const persistAppointment = async (
+    appointmentId: number,
+    nextAppointment: Appointment
+  ) => {
+    await fetch(`/api/appointments/${appointmentId}`, {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(nextAppointment),
+    });
+  };
+
+  const handleAppointmentChange = async (
+    change: SchedulerAppointmentChangeArgs<Appointment, number>
+  ) => {
+    const optimisticAppointments = applySchedulerAppointmentChange(appointments, change, {
+      getId: (item) => item.id,
+      setResourceId: (item, resourceId) => ({ ...item, staffId: resourceId }),
+      setStart: (item, start) => ({ ...item, start: start.toISOString() }),
+      setEnd: (item, end) => ({ ...item, end: end.toISOString() }),
+    });
+
+    setAppointments(optimisticAppointments);
+
+    const nextAppointment = optimisticAppointments.find(
+      (item) => item.id === change.appointment.id
+    );
+
+    if (!nextAppointment) {
+      return;
+    }
+
+    try {
+      await persistAppointment(change.appointment.id, nextAppointment);
+    } catch {
+      await loadAppointments(selectedDate);
+    }
+  };
+
+  useEffect(() => {
+    void loadStaff();
+  }, []);
+
+  useEffect(() => {
+    void loadAppointments(selectedDate);
+  }, [selectedDate]);
 
   return (
     <Scheduler<Appointment, Staff, number>
-      resources={initialStaff}
+      resources={staff}
       appointments={appointments}
       selectedDate={selectedDate}
       onSelectedDateChange={setSelectedDate}
-      prevButtonLabel="Previous day"
-      nextButtonLabel="Next day"
       adapter={{
-        getId: (a) => a.id,
-        getResourceId: (a) => a.staffId,
-        getStart: (a) => a.start,
-        getEnd: (a) => a.end,
-        getTitle: (a) => `${a.customerName} - ${a.title}`
-      }}
-      onAppointmentChange={async ({ appointment, next }) => {
-        setAppointments((prev) =>
-          prev.map((a) =>
-            a.id === appointment.id
-              ? { ...a, staffId: next.resourceId, start: next.start.toISOString(), end: next.end.toISOString() }
-              : a
-          )
-        );
-      }}
-      resourceAppointmentClassMap={{
-        "1": "bg-amber-100 dark:bg-amber-950/40",
-        "2": "bg-blue-100 dark:bg-blue-950/40"
+        getId: (item) => item.id,
+        getResourceId: (item) => item.staffId,
+        getStart: (item) => item.start,
+        getEnd: (item) => item.end,
+        getTitle: (item) => `${item.customerName} - ${item.title}`,
       }}
+      onAppointmentChange={handleAppointmentChange}
       dayStart="09:00"
       dayEnd="18:00"
     />
   );
+};
+```
+
+## How Data Flow Works
+
+When the user changes the day from the built-in toolbar or date picker:
+
+1. the scheduler calls `onSelectedDateChange(nextDate)`
+2. your state updates `selectedDate`
+3. your `useEffect` runs again
+4. your app fetches appointments for the new date
+5. you pass the fetched appointments back into `appointments`
+
+This is the intended integration pattern:
+
+```tsx
+useEffect(() => {
+  void loadAppointments(selectedDate);
+}, [selectedDate]);
+
+<Scheduler
+  selectedDate={selectedDate}
+  onSelectedDateChange={setSelectedDate}
+  appointments={appointments}
+  resources={resources}
+  adapter={adapter}
+/>
+```
+
+## Core Concepts
+
+### `resources`
+
+Each column in the scheduler is a resource. A resource must have at least:
+
+```ts
+type BaseSchedulerResource<TId> = {
+  id: TId;
+  label: string;
+};
+```
+
+Typical resources:
+
+- staff members
+- rooms
+- desks
+- service stations
+
+### `appointments`
+
+Appointments stay in your own shape. The scheduler reads them through the `adapter`.
+
+### `adapter`
+
+The adapter maps your appointment structure into scheduler fields:
+
+```tsx
+adapter={{
+  getId: (item) => item.id,
+  getResourceId: (item) => item.staffId,
+  getStart: (item) => item.start,
+  getEnd: (item) => item.end,
+  getTitle: (item) => item.title,
+}}
+```
+
+`getStart` and `getEnd` can return either a `Date` or a date string.
+
+## Drag, Resize, and Persistence
+
+Use `onAppointmentChange` as the main integration point for move and resize operations.
+
+It receives:
+
+- `appointment`: the original raw appointment
+- `previous`: the previous resource and time range
+- `next`: the new resource and time range after drop
+- `kind`: `"move"` or `"resize"`
+
+Example:
+
+```tsx
+<Scheduler
+  // ...other props
+  onAppointmentChange={async ({ appointment, next }) => {
+    const nextAppointment = {
+      ...appointment,
+      staffId: next.resourceId,
+      start: next.start.toISOString(),
+      end: next.end.toISOString(),
+    };
+
+    await fetch(`/api/appointments/${appointment.id}`, {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(nextAppointment),
+    });
+  }}
+/>
+```
+
+If you want a small helper for optimistic local state updates, use `applySchedulerAppointmentChange`:
+
+```tsx
+const nextAppointments = applySchedulerAppointmentChange(appointments, change, {
+  getId: (item) => item.id,
+  setResourceId: (item, resourceId) => ({ ...item, staffId: resourceId }),
+  setStart: (item, start) => ({ ...item, start: start.toISOString() }),
+  setEnd: (item, end) => ({ ...item, end: end.toISOString() }),
+});
+```
+
+`onPersistMoveResize` is still available as a legacy callback, but `onAppointmentChange` is the recommended API.
+
+## Styling
+
+The package ships precompiled CSS:
+
+```tsx
+import "@marco.colia/react-fast-scheduler/styles.css";
+```
+
+You can override the exposed CSS variables in your app:
+
+```css
+:root {
+  --rfs-bg: #f8fafc;
+  --rfs-surface: #ffffff;
+  --rfs-border: #e2e8f0;
+  --rfs-text: #0f172a;
+  --rfs-muted: #64748b;
 }
 ```
 
-`renderAppointment` is optional. If you omit it, the scheduler uses the built-in appointment card with light/dark mode support.
-`renderToolbar` is optional. If you omit it, the scheduler uses a built-in shadcn-style toolbar with prev/next buttons and a calendar popover date picker.
-`renderDatePicker` is optional. If you omit it, the default toolbar uses the built-in calendar popover date picker.
-`onAppointmentChange` is a simple callback: use it to update your state and run your own side effects.
-
-Main props you need to pass:
-- `resources`: your columns (staff, rooms, etc), each with at least `{ id, label }`.
-- `appointments`: raw items from your backend.
-- `adapter`: functions that map your raw appointment shape to scheduler fields.
-- `onAppointmentChange`: optional generic callback fired after move/resize drop.
-- `onPersistMoveResize`: optional legacy persistence callback (used if `onAppointmentChange` is not provided).
-- `resourceAppointmentClassMap`: optional map of `resourceId -> className` for per-resource appointment colors/styles.
-- `getResourceAppointmentColorToken`: optional function to provide a semantic color token per resource (for example `"amber"`).
-- `appointmentColorTokenClassMap`: optional map to override token -> class resolution.
-- `getResourceAppointmentAppearance`: optional low-level function to provide appointment `className` per resource.
-- `getResourceAppointmentBackground`: legacy optional function to provide appointment background as a string.
-- `renderToolbar`: optional render hook to replace the entire scheduler toolbar/header controls.
-- `prevButtonLabel` and `nextButtonLabel`: custom labels for toolbar navigation buttons.
-- `renderDatePicker`: optional render hook for the date picker slot used by the default toolbar.
-- `renderResourceHeader`: optional render hook for resource column headers.
-- `renderAppointment`: optional render hook to fully customize appointment cards.
-
-### Resource classes by id (recommended)
+### Resource-based colors
+
+The simplest option is `resourceAppointmentClassMap`:
 
 ```tsx
 <Scheduler
   // ...other props
   resourceAppointmentClassMap={{
-    "room-a": "bg-yellow-100 dark:bg-yellow-950/40",
-    "room-b": "bg-rose-100 dark:bg-rose-950/40"
+    "1": "bg-amber-100 dark:bg-amber-950/40",
+    "2": "bg-blue-100 dark:bg-blue-950/40",
   }}
 />
 ```
 
-### Resource color tokens (optional)
+If you want semantic mapping, use `getResourceAppointmentColorToken` plus `appointmentColorTokenClassMap`:
 
 ```tsx
 <Scheduler
@@ -131,33 +308,72 @@ Main props you need to pass:
   getResourceAppointmentColorToken={(resource) => resource.category}
   appointmentColorTokenClassMap={{
     vip: "bg-yellow-100 dark:bg-yellow-950/40",
-    urgent: "bg-rose-100 dark:bg-rose-950/40"
+    urgent: "bg-rose-100 dark:bg-rose-950/40",
   }}
 />
 ```
 
-### Custom appointment renderer (optional)
+For full control, use `getResourceAppointmentAppearance`.
+
+## Custom Rendering
+
+### Custom appointment card
+
+`renderAppointment` lets you fully replace the built-in card.
+
+The appointment passed to your renderer also includes:
+
+- `visualState`: `"normal" | "ghost" | "dragging"`
+- `renderKey`: an internal render key
+
+The renderer also receives:
+
+- `isDropInvalid`: `true` when the current drag position overlaps another appointment
+- `onPointerDown`: attach this to your appointment root for move interactions
+- `onResizePointerDown`: attach this to your resize handle
 
 ```tsx
 <Scheduler
   // ...other props
-  renderAppointment={({ appointment, onPointerDown, onResizePointerDown, appointmentAppearance, appointmentBackgroundColor }) => (
+  renderAppointment={({
+    appointment,
+    isDropInvalid,
+    onPointerDown,
+    onResizePointerDown,
+    appointmentAppearance,
+    appointmentBackgroundColor,
+  }) => (
     <div
       onPointerDown={onPointerDown}
-      className={`relative h-full cursor-grab overflow-hidden rounded-md border border-slate-300 p-2 pb-5 ${
-        appointmentAppearance?.className ?? appointmentBackgroundColor ?? "bg-slate-100"
+      className={`relative h-full overflow-hidden rounded-md border p-2 pb-5 ${
+        appointment.visualState === "ghost"
+          ? "cursor-grab border-dashed opacity-55"
+          : appointment.visualState === "dragging"
+            ? "cursor-grabbing opacity-55"
+            : "cursor-grab"
+      } ${
+        isDropInvalid
+          ? "border-red-500 bg-red-100/80 text-red-950 ring-1 ring-red-500/60"
+          : `border-slate-300 ${
+              appointmentAppearance?.className ?? appointmentBackgroundColor ?? "bg-slate-100"
+            }`
       }`}
     >
       <div className="text-xs font-semibold">{appointment.title}</div>
       {appointment.raw.description ? (
-        <div className="mt-1 text-[10px] font-medium text-slate-500">{appointment.raw.description}</div>
+        <div className="mt-1 text-[10px] font-medium text-slate-500">
+          {appointment.raw.description}
+        </div>
       ) : null}
       <div
         role="button"
         aria-label="Resize appointment"
-        onPointerDown={(e) => {
-          e.stopPropagation();
-          onResizePointerDown(e);
+        onPointerDown={(event) => {
+          if (appointment.visualState === "ghost") {
+            return;
+          }
+          event.stopPropagation();
+          onResizePointerDown(event);
         }}
         className="absolute inset-x-1 bottom-1 h-2 cursor-ns-resize rounded-full bg-slate-300/90 hover:bg-slate-400"
       />
@@ -168,6 +384,10 @@ Main props you need to pass:
 
 ### Custom toolbar
 
+If you omit `renderToolbar`, the scheduler renders a built-in toolbar with previous/next navigation and a date picker.
+
+Use `renderToolbar` when you want to replace the whole header:
+
 ```tsx
 <Scheduler
   // ...other props
@@ -178,11 +398,11 @@ Main props you need to pass:
         <div className="text-xs text-muted-foreground">Team schedule</div>
       </div>
       <div className="flex items-center gap-2">
-        <button className="rounded-md border px-3 py-2 text-sm" type="button" onClick={goToPreviousDay}>
+        <button type="button" className="rounded-md border px-3 py-2 text-sm" onClick={goToPreviousDay}>
           Previous
         </button>
         {defaultDatePicker}
-        <button className="rounded-md border px-3 py-2 text-sm" type="button" onClick={goToNextDay}>
+        <button type="button" className="rounded-md border px-3 py-2 text-sm" onClick={goToNextDay}>
           Next
         </button>
       </div>
@@ -193,87 +413,53 @@ Main props you need to pass:
 
 ### Custom date picker slot
 
-```tsx
-import { Button } from "@/components/ui/button";
-import { Calendar } from "@/components/ui/calendar";
-import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
+If you want to keep the default toolbar but swap the date picker UI, use `renderDatePicker`.
 
+```tsx
 <Scheduler
   // ...other props
   renderDatePicker={({ selectedDate, onSelectedDateChange }) => (
-    <Popover>
-      <PopoverTrigger asChild>
-        <Button variant="outline">{selectedDate.toDateString()}</Button>
-      </PopoverTrigger>
-      <PopoverContent className="w-auto p-0">
-        <Calendar
-          mode="single"
-          selected={selectedDate}
-          onSelect={(date) => date && onSelectedDateChange(date)}
-          initialFocus
-        />
-      </PopoverContent>
-    </Popover>
+    <button type="button" onClick={() => onSelectedDateChange(new Date())}>
+      {selectedDate.toDateString()}
+    </button>
   )}
-/>;
+/>
 ```
 
-## Styles
+## Props Reference
 
-The package ships a precompiled CSS file generated from Tailwind:
+### Required props
 
-```tsx
-import "@marco.colia/react-fast-scheduler/styles.css";
-```
+- `resources`: array of resource objects
+- `appointments`: array of raw appointment objects
+- `selectedDate`: currently visible day
+- `onSelectedDateChange`: controlled date change handler
+- `adapter`: mapper between your appointment shape and scheduler fields
 
-Minimal app entry example:
+### Common optional props
 
-```tsx
-import React from "react";
-import ReactDOM from "react-dom/client";
-import { SchedulerExample } from "./SchedulerExample";
-import "@marco.colia/react-fast-scheduler/styles.css";
+- `onAppointmentChange`: async or sync handler for move and resize persistence
+- `renderToolbar`: replace the full toolbar
+- `renderDatePicker`: replace only the date picker slot used by the default toolbar
+- `renderResourceHeader`: custom resource header renderer
+- `renderAppointment`: custom appointment renderer
+- `resourceAppointmentClassMap`: per-resource class names
+- `getResourceAppointmentColorToken`: semantic color token selector
+- `appointmentColorTokenClassMap`: token-to-class map
+- `getResourceAppointmentAppearance`: low-level class name appearance mapping
+- `getResourceAppointmentBackground`: legacy background string hook
+- `prevButtonLabel`: custom previous button label
+- `nextButtonLabel`: custom next button label
+- `dayStart`: visible schedule start time, for example `"09:00"`
+- `dayEnd`: visible schedule end time, for example `"18:00"`
 
-ReactDOM.createRoot(document.getElementById("root")!).render(<SchedulerExample />);
-```
-
-If you work inside this library repo (local demo), import the Tailwind v4 source entry:
+## Production Notes
 
-```tsx
-import "../src/global.css";
-```
-
-You can override tokens in your app:
-
-```css
-:root {
-  --rfs-bg: #f8fafc;
-  --rfs-surface: #ffffff;
-  --rfs-border: #e2e8f0;
-  --rfs-text: #0f172a;
-  --rfs-muted: #64748b;
-}
-```
+- Keep `selectedDate` in application state and fetch data when it changes.
+- Prefer formatting dates in local time for day-based API queries. `toISOString().slice(0, 10)` can shift the day around midnight because it uses UTC.
+- If persistence fails after a drag or resize, either roll back local state or refetch the visible day.
+- Import the package CSS once at app startup.
 
 ## Development
 
-```bash
-npm install
-npm run dev:demo
-npm run lint
-npm run test
-npm run build
-```
-
-`dev/main.tsx` contains a minimal runnable scheduler demo used by `npm run dev:demo`.
-Tailwind v4 source styles are in `src/global.css`, and the demo imports them from `dev/main.tsx`.
-
-## Releasing
-
-This repo uses [Changesets](https://github.com/changesets/changesets) and GitHub Actions.
-
-1. Create a changeset: `npx changeset`
-2. Merge to `main`
-3. The `Release` workflow opens/updates a release PR
-4. Merging that PR publishes to npm via npm Trusted Publishing and GitHub OIDC
-4. Merging that PR publishes to npm via npm Trusted Publishing and GitHub OIDC
+Repo-specific development notes, local demo usage, and release workflow are in [DEVELOPMENT.md](./DEVELOPMENT.md).