@innosolutions/inno-calendar 1.0.72 → 2.0.1

package/README.md

@@ -1,305 +1,333 @@
-# @inno/calendar
-
-A headless-first, fully customizable React calendar for enterprise applications.
-
-[![npm version](https://img.shields.io/npm/v/@innosolutions/inno-calendar.svg)](https://www.npmjs.com/package/@innosolutions/inno-calendar)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
-[![React](https://img.shields.io/badge/React-18+-61DAFB.svg)](https://reactjs.org/)
-
-> **🤖 AI Agents:** For comprehensive implementation details, copy the contents of [AGENT.md](./AGENT.md) into your context.
-
-## Installation
-
-```bash
-npm install @innosolutions/inno-calendar
-```
-
-```bash
-# Optional: Radix UI for enhanced popovers/tooltips
-npm install @radix-ui/react-popover @radix-ui/react-tooltip @radix-ui/react-dropdown-menu
-```
-
-## Quick Start
-
-```tsx
-import { InnoCalendar, type CalendarEvent } from "@innosolutions/inno-calendar";
-import "@innosolutions/inno-calendar/styles";
-
-const events: CalendarEvent[] = [
-  {
-    id: "1",
-    title: "Team Meeting",
-    startDate: new Date("2026-02-04T09:00:00"),
-    endDate: new Date("2026-02-04T10:00:00"),
-    color: "blue",
-  },
-];
-
-function MyCalendar() {
-  return (
-    <InnoCalendar
-      events={events}
-      initialView="week"
-      onEventClick={(event) => console.log(event)}
-      onSlotSelect={(selection) =>
-        console.log(selection.startDate, selection.endDate)
-      }
-    />
-  );
-}
-```
-
-## Features
-
-- **8 View Modes** — Day, Week, Month, Year, Agenda, Timeline (1/3/7 day)
-- **Headless Architecture** — Use hooks directly or pre-built components
-- **Drag & Drop** — Drag to select time ranges, drag events to reschedule
-- **TypeScript** — Fully typed with generic event data support
-- **Customizable** — Custom popovers, settings panels, filters
-- **No External Dependencies** — Native Date API, minimal footprint
-
-## Views
-
-| View            | Description                |
-| --------------- | -------------------------- |
-| `day`           | Single day hourly grid     |
-| `week`          | 7-day grid with time slots |
-| `month`         | Monthly calendar           |
-| `year`          | 12-month overview          |
-| `agenda`        | Scrollable event list      |
-| `timeline-day`  | Resource timeline (1 day)  |
-| `timeline-3day` | Resource timeline (3 days) |
-| `timeline-week` | Resource timeline (7 days) |
-| `resource-day`  | Resource view (1 day)      |
-| `resource-week` | Resource view (7 days)     |
-
-## Event Structure
-
-```tsx
-interface CalendarEvent<TData = Record<string, unknown>> {
-  // Required
-  id: string;
-  title: ReactNode; // String or JSX
-  startDate: Date;
-  endDate: Date;
-
-  // Optional display fields
-  color?:
-    | "blue"
-    | "green"
-    | "red"
-    | "yellow"
-    | "purple"
-    | "orange"
-    | "pink"
-    | "teal"
-    | "gray"
-    | "indigo";
-  hexColor?: string; // Hex override (takes precedence over color)
-  description?: ReactNode; // String or JSX
-  isCanceled?: boolean;
-  isAllDay?: boolean;
-  isMultiDay?: boolean;
-  isRecurring?: boolean;
-  resourceId?: string; // For resource/timeline views
-
-  // Built-in filtering (optional — skip if you filter server-side)
-  scheduleTypeId?: number;
-  scheduleTypeName?: ReactNode; // String or JSX
-  participants?: ICalendarUser[];
-
-  // @deprecated — still functional, but migrate to `data` bag.
-  // Will be removed in the next major version.
-  meetingTookPlace?: boolean; // → data.meetingTookPlace
-  isAccepted?: boolean; // → data.isAccepted
-  companyId?: number; // → data.companyId
-  cancelReason?: string | null; // → data.cancelReason
-  user?: ICalendarUser; // → data.user
-  // ... and others (see types.ts for full list)
-
-  data?: TData; // Your custom domain-specific fields (RECOMMENDED)
-}
-```
-
-### ReactNode Props
-
-`title`, `description`, and `scheduleTypeName` accept `ReactNode` — you can pass plain strings (fully backwards compatible) or custom JSX:
-
-```tsx
-const event: CalendarEvent = {
-  id: "1",
-  title: <span><UserIcon className="h-3 w-3 inline" /> John Doe</span>,
-  description: <p className="italic">VIP client meeting</p>,
-  startDate: new Date(),
-  endDate: new Date(),
-};
-```
-
-The built-in search and `aria-label` automatically extract plain text from JSX nodes via the `reactNodeToText` utility.
-
-### Extended Props (data.extendedProps)
-
-For rendering an arbitrary number of custom lines on EventCard/EventBlock, use the `extendedProps` array in the `data` bag:
-
-```tsx
-const event: CalendarEvent = {
-  id: "1",
-  title: "Practical Course",
-  startDate: new Date(),
-  endDate: new Date(),
-  data: {
-    extendedProps: [
-      <p key="student" className="font-medium">Student: Jane Doe</p>,
-      <p key="phone">Phone: +32 123 456 789</p>,
-      <div key="info" className="flex items-center gap-1">
-        <CarIcon className="h-3 w-3" />
-        <span>Automatic transmission</span>
-      </div>,
-    ],
-  },
-};
-```
-
-Each entry renders as its own row. Visible on EventCard (full variant) and EventBlock (events >= 45min). Also shown in tooltips.
-
-## Props
-
-```tsx
-<InnoCalendar
-  // Data
-  events={events}
-  users={users}
-  alwaysShowResources={alwaysShowResources}
-  scheduleTypes={scheduleTypes}
-  // Initial State
-  initialView="week"
-  initialDate={new Date()}
-  // Callbacks
-  onEventClick={(event) => {}}
-  onSlotSelect={(selection) => {}}
-  onSlotClick={(date, hour) => {}}
-  onAddEvent={() => {}}
-  onEventDrop={(result) => {}}
-  onDateChange={(date, view) => {}}
-  onViewChange={(view) => {}}
-  // Customization
-  renderPopover={({ event, onClose }) => <CustomPopover />}
-  settingsContent={<SettingsPanel />}
-  filterContent={<FiltersRow />}
-  showHeader={true}
-/>
-```
-
-## Provider Pattern
-
-For shared state across components:
-
-```tsx
-import {
-  InnoCalendarProvider,
-  useInnoCalendar,
-  CalendarHeader,
-  WeekView,
-} from "@innosolutions/inno-calendar";
-
-function App() {
-  return (
-    <InnoCalendarProvider initialEvents={events} initialView="week">
-      <CalendarContent />
-    </InnoCalendarProvider>
-  );
-}
-
-function CalendarContent() {
-  const { view, filteredEvents, selectedDate } = useInnoCalendar();
-  return (
-    <>
-      <CalendarHeader />
-      <WeekView events={filteredEvents} date={selectedDate} />
-    </>
-  );
-}
-```
-
-## Resource & Timeline Views
-
-The resource-based views (`resource-day`, `resource-week`, `timeline-day`, `timeline-3day`, `timeline-week`) group events by resource and render one row per resource.
-
-**Default flow** — resource rows are derived from the events: each unique resource referenced by an event (via `event.resourceId`, `event.data.user`, `event.user`, or `event.participants`) gets its own row. Resources without events are not shown.
-
-**Always-show resources** — pass `alwaysShowResources` to guarantee a row for a resource even when it has no events in the current data. Rows without events appear at the bottom so event-containing rows keep visual priority. If a resource listed here also has events, its row is positioned naturally among the event rows and the events are still attached to it.
-
-```tsx
-<InnoCalendar
-  events={events}
-  initialView="timeline-week"
-  alwaysShowResources={[
-    { id: "room-1", name: "Meeting Room A", avatar: "/rooms/a.jpg" },
-    { id: "room-2", name: "Meeting Room B" },
-  ]}
-/>
-```
-
-Each entry accepts the full `ICalendarUser` shape — at minimum `id` and `name` are needed to render the row header; `avatar` and `email` are optional. Updating the array re-renders the view immediately.
-
-This prop applies to all resource-based views (`resource-day`, `resource-week`, `timeline-day`, `timeline-3day`, `timeline-week`) and is ignored in `day`, `week`, `month`, `year`, and `agenda` views.
-
-## Working Hours
-
-```tsx
-const workingHours = {
-  0: { enabled: false, from: 8, to: 17 }, // Sunday
-  1: { enabled: true, from: 9, to: 18 }, // Monday
-  2: { enabled: true, from: 9, to: 18 }, // Tuesday
-  3: { enabled: true, from: 9, to: 18 }, // Wednesday
-  4: { enabled: true, from: 9, to: 18 }, // Thursday
-  5: { enabled: true, from: 9, to: 17 }, // Friday
-  6: { enabled: false, from: 8, to: 12 }, // Saturday
-};
-
-<InnoCalendar
-  events={events}
-  preferencesConfig={{
-    defaults: { workingHours },
-  }}
-/>;
-```
-
-## Styles
-
-Import the bundled styles for proper rendering:
-
-```tsx
-import "@innosolutions/inno-calendar/styles";
-```
-
-Or include CSS custom properties for theming:
-
-```css
-:root {
-  --inno-border-color: #e5e7eb;
-  --inno-primary: #3b82f6;
-  --inno-hour-height: 96px;
-}
-```
-
-## TypeScript
-
-```tsx
-import type {
-  CalendarEvent,
-  TCalendarView,
-  TEventColor,
-  ICalendarUser,
-  IScheduleType,
-  ISelectionResult,
-  TWorkingHours,
-} from "@innosolutions/inno-calendar";
-
-// Utility: extract plain text from any ReactNode (for search, labels, etc.)
-import { reactNodeToText } from "@innosolutions/inno-calendar";
-```
-
-## License
-
-MIT © [InnoSolutions](https://github.com/innosolutions)
+# @innosolutions/inno-calendar
+
+A React calendar that behaves like Google Calendar and lets your application
+own everything domain-specific.
+
+[![npm version](https://img.shields.io/npm/v/@innosolutions/inno-calendar.svg)](https://www.npmjs.com/package/@innosolutions/inno-calendar)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![React](https://img.shields.io/badge/React-18+-61DAFB.svg)](https://reactjs.org/)
+
+> Upgrading from 1.x? See [CHANGELOG.md](./CHANGELOG.md) — 2.0.0 removes
+> `slots`, `classNames` and the `/presets` entry point.
+
+## What it owns, and what it doesn't
+
+The package owns the parts that are the same in every calendar: the grid, the
+header, the floating card a drag opens, the detail popover, the filter rail,
+the drag-and-drop, the placement maths.
+
+Your application owns the parts that differ: what an event *is*, what a form
+asks for, what a detail card shows, what you can filter by. You pass those in
+as components. There is one extension mechanism — render props — not three.
+
+```tsx
+<InnoCalendar
+  events={events}
+  eventCard={(event, { compact }) => <MyCard event={event} compact={compact} />}
+  eventDetail={(event, { close, edit }) => <MyDetail … />}
+  eventForm={({ selection, event }, { close, expand }) => <MyForm … />}
+  filters={({ close }) => <MyFilters onDone={close} />}
+/>
+```
+
+## Installation
+
+```bash
+npm install @innosolutions/inno-calendar
+```
+
+`react` and `react-dom` (18 or 19) are the only peer dependencies. Everything
+else the calendar needs — Radix popover, dropdown, tooltip and dialog, plus
+`lucide-react` — comes with it.
+
+## Quick start
+
+```tsx
+import { InnoCalendar, type CalendarEvent } from "@innosolutions/inno-calendar";
+import "@innosolutions/inno-calendar/styles";
+
+const events: CalendarEvent[] = [
+  {
+    id: "1",
+    title: "Team meeting",
+    startDate: new Date("2026-02-04T09:00:00"),
+    endDate: new Date("2026-02-04T10:00:00"),
+    color: "blue",
+  },
+];
+
+function MyCalendar() {
+  return (
+    <InnoCalendar
+      events={events}
+      initialView="week"
+      onEventClick={(event) => console.log(event)}
+      onSlotSelect={({ startDate, endDate }) => console.log(startDate, endDate)}
+    />
+  );
+}
+```
+
+That renders a working calendar. Everything below is opt-in.
+
+## Views
+
+| View | Description |
+| --- | --- |
+| `day` | Single day, hourly grid |
+| `4day` | Four days |
+| `week` | Seven days with time slots |
+| `month` | Monthly grid |
+| `year` | Twelve-month overview |
+| `agenda` | Scrollable list |
+| `resource-day` / `resource-week` | One column per resource |
+| `timeline-day` / `timeline-3day` / `timeline-week` | One row per resource |
+
+## The event
+
+```tsx
+interface CalendarEvent<TData = Record<string, unknown>> {
+  id: string;
+  title: ReactNode;
+  startDate: Date;
+  endDate: Date;
+
+  color?: "blue" | "green" | "red" | "yellow" | "purple"
+        | "orange" | "pink" | "teal" | "gray" | "indigo";
+  hexColor?: string;          // overrides `color`
+  description?: ReactNode;
+  isCanceled?: boolean;
+  isAllDay?: boolean;
+  isRecurring?: boolean;
+  resourceId?: string;        // resource and timeline views
+
+  // Client-side filtering. Skip it if you filter server-side.
+  scheduleTypeId?: number;
+  participants?: ICalendarUser[];
+
+  data?: TData;               // your domain fields live here
+}
+```
+
+Put your own fields on `data`. The calendar never reads it — it hands the whole
+event back to your `eventCard`, `eventDetail` and `eventForm`, which are the
+only things that know what a "property" or an "opportunity" is.
+
+```tsx
+type MyData = { raw: AgendaRow };
+
+<InnoCalendar<MyData>
+  events={rows.map((row) => ({ …, data: { raw: row } }))}
+  eventCard={(event) => <MyCard row={event.data.raw} />}
+/>
+```
+
+A handful of domain-shaped fields (`meetingTookPlace`, `companyId`, `user`, …)
+still exist at the top level and are marked `@deprecated`. They will go in 3.0.
+
+## Extension points
+
+Each is a function returning JSX. Pass one to take that surface over; leave it
+out and the calendar handles it.
+
+### `eventCard` — the block in the grid
+
+```tsx
+eventCard={(event, { compact }) => (
+  <MyCard event={event} compact={compact} />
+)}
+```
+
+`compact` is true in the month view and other tight rows.
+
+### `eventDetail` — what a click opens
+
+```tsx
+eventDetail={(event, { close, edit }) => (
+  <MyDetail event={event} onClose={close} onEdit={edit} />
+)}
+```
+
+`edit` is present only when an `eventForm` is there to open. The calendar
+supplies the container: a popover beside the event, or a bottom sheet on a
+narrow screen, capped to the room available and scrolling inside.
+
+### `eventForm` — create and edit
+
+```tsx
+eventForm={({ selection, event }, { close, expand }) => (
+  <MyForm
+    start={selection.startDate}
+    end={selection.endDate}
+    event={event}          // present when editing
+    onDone={close}
+    onExpand={expand}      // ask for the wider card
+  />
+)}
+```
+
+The calendar owns the card — placement, dragging it by its handle, Escape,
+click-outside, the height cap, the phone sheet. You own what is inside it.
+Pair it with the exported `WhenRow` and `RecurrenceField` so your form's time
+row behaves like the built-in one.
+
+A drag on the grid opens it on that range. So does the Add button, on the slot
+happening now. `ref.current.openForm()` does the same from anywhere.
+
+### `filters` — the rail
+
+```tsx
+filters={({ close }) => <MyFilters onDone={close} />}
+```
+
+The calendar supplies the rail on wide screens and a sheet on narrow ones;
+`close` puts the sheet away after a filter that applies on tap.
+
+## Props
+
+```tsx
+<InnoCalendar
+  // Data
+  events={events}
+  users={users}                       // resource rows
+  isLoading={isFetching}
+
+  // Extension points
+  eventCard={…}
+  eventDetail={…}
+  eventForm={…}
+  filters={…}
+
+  // Initial state
+  initialView="week"
+  initialDate={new Date()}
+  locale="fr"
+
+  // Callbacks
+  onEventClick={(event) => {}}
+  onSlotSelect={(selection) => {}}
+  onSlotClick={(date, hour) => {}}
+  onAddEvent={() => {}}
+  onEventDrop={(result) => {}}
+  onDateChange={(date, view) => {}}
+  onViewChange={(view) => {}}
+
+  // Chrome
+  showHeader
+  showSidebar
+  createLabel="Add"
+  labels={{ header: {…}, agenda: {…}, filters: "Filters" }}
+  headerActions={<MyActions />}
+  settingsContent={<MySettings />}
+  sidebarContent={<MyRail />}
+
+  // Behaviour
+  minSelectionMinutes={30}
+  preferencesConfig={{ defaults: {…} }}
+  resourceColumnConfig={{…}}
+  alwaysShowResources={resources}
+/>
+```
+
+`onEventDrop` is worth a note: without it, a drag or resize **opens the form**
+on the new times rather than writing them, because a reschedule that mails the
+participants should be confirmed. Pass a handler to take that over and get the
+optimistic save with undo instead.
+
+## The ref
+
+```tsx
+const calendar = useRef<ICalendarRefHandle>(null);
+
+calendar.current?.openForm();                       // new, on the slot happening now
+calendar.current?.openForm({ start, end });         // new, on a range
+calendar.current?.openForm({ event });              // edit, on its own times
+calendar.current?.scrollToToday();
+calendar.current?.focusEvent(id);
+```
+
+## Working hours and preferences
+
+```tsx
+preferencesConfig={{
+  defaults: {
+    slotDuration: 30,
+    visibleHours: { from: 7, to: 20 },
+    showWorkingHoursOnly: true,
+    workingHours: { 1: { from: 9, to: 17 }, /* 0 = Sunday */ },
+    badgeVariant: "colored",
+  },
+}}
+```
+
+Preferences persist per user in `localStorage`; `defaults` is what a user who
+has never changed anything sees.
+
+## Styling
+
+```tsx
+import "@innosolutions/inno-calendar/styles";
+```
+
+Theme and dimensions are CSS custom properties:
+
+```css
+:root {
+  --inno-border-color: #e5e7eb;
+  --inno-background: #ffffff;
+  --inno-foreground: #111827;
+  --inno-muted: #f3f4f6;
+  --inno-primary: #3b82f6;
+
+  --inno-hour-height: 96px;
+  --inno-header-height: 56px;
+  --inno-sidebar-width: 200px;
+
+  --inno-event-blue: #3b82f6;   /* …and green, red, yellow, purple,
+                                   orange, pink, teal, gray, indigo */
+}
+```
+
+Dark mode reads the same names under `.dark`.
+
+Anything more specific than those is CSS against the package's class names,
+which is not yet a stable contract — see the note in the changelog.
+
+### Stacking
+
+Anything you portal from inside a calendar surface has to sit above it, and
+guessing a number that works today is how that breaks later:
+
+```tsx
+import { IC_Z_LAYER } from "@innosolutions/inno-calendar";
+
+<SelectContent style={{ zIndex: IC_Z_LAYER }}>
+```
+
+`IC_Z_CARD` (1000) is the floating card, `IC_Z_LAYER` (1100) menus and pickers
+opened from one, `IC_Z_MODAL` (1200) a dialog on top of that.
+
+## TypeScript
+
+```tsx
+import type {
+  CalendarEvent,
+  ICalendarRefHandle,
+  ICalendarUser,
+  IEventFormActions,
+  IEventFormArgs,
+  IRecurrence,
+  ISelectionResult,
+  TCalendarView,
+  TEventColor,
+  TWorkingHours,
+} from "@innosolutions/inno-calendar";
+```
+
+Exported components worth knowing: `WhenRow`, `RecurrenceField`, `FieldLayer`
+and `QuickCreate` for building a form body, and `formatClockRange` /
+`reactNodeToText` for labels.
+
+## License
+
+MIT © [InnoSolutions](https://github.com/innosolutions)