@innosolutions/inno-calendar 1.0.61 → 1.0.63

package/README.md

@@ -1,279 +1,305 @@
-# @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) |
-
-## 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}
-  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} />
-    </>
-  );
-}
-```
-
-## 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)
+# @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 Views
+
+The resource views (`resource-day`, `resource-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="resource-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 resource view immediately.
+
+This prop is scoped to the resource views only — it is ignored in `timeline-*` and all other 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)