@innosolutions/inno-calendar 1.0.60 → 1.0.61

package/AGENT.md

@@ -1,1756 +1,1783 @@
-# @innosolutions/inno-calendar — AI Agent Reference
-
-> **Version 1.0.58** | React 18+/19 | TypeScript 5.9 | Vite 7 library-mode  
-> Headless-first, fully customizable React calendar for enterprise applications.
-
----
-
-## Table of Contents
-
-1. [What This Package Is](#1-what-this-package-is)
-2. [npm Scripts](#2-npm-scripts)
-3. [Package Exports](#3-package-exports)
-4. [Core Types](#4-core-types)
-5. [InnoCalendar Props](#5-innocalendar-props)
-6. [Slots System](#6-slots-system)
-7. [ClassNames API](#7-classnames-api)
-8. [EventCard & EventBlock](#8-eventcard--eventblock)
-9. [EventPopover Component](#9-eventpopover-component)
-10. [Preferences System](#10-preferences-system)
-11. [Widget Components](#11-widget-components)
-12. [Filter Components](#12-filter-components)
-13. [Settings Components](#13-settings-components)
-14. [Context & Hooks](#14-context--hooks)
-15. [Drag & Drop](#15-drag--drop)
-16. [Core Utilities](#16-core-utilities)
-17. [Presets](#17-presets)
-18. [CSS & Theming](#18-css--theming)
-19. [Constants](#19-constants)
-20. [Integration Guide](#20-integration-guide)
-21. [Full Export Catalog](#21-full-export-catalog)
-22. [File Naming Conventions](#22-file-naming-conventions)
-23. [Styling Patterns](#23-styling-patterns)
-24. [Biome Configuration](#24-biome-configuration)
-25. [State Synchronization Guide](#25-state-synchronization-guide)
-26. [Critical Rules](#26-critical-rules)
-
----
-
-## 1. What This Package Is
-
-A **headless-first** React calendar component library — all view logic lives in hooks and contexts; every UI element is an optional, replaceable component.
-
-### Feature Set
-
-| Category | Features |
-|---|---|
-| **Views** | Day, Week, Month, Year, Agenda, Resource-Day, Resource-Week, Timeline-Day, Timeline-3Day, Timeline-Week |
-| **Interaction** | Drag-to-select (time & day mode), event click, slot click, drag-and-drop reposition, event resize |
-| **Customization** | 25+ component slots, 30+ classNames keys, render props, custom popover |
-| **Data** | Generic `CalendarEvent<TData>`, adapter pattern, BYO data fetching |
-| **Preferences** | localStorage persistence, locking, session mode, per-instance storage keys |
-| **Filtering** | Built-in schedule type filter, user/participant filter, text search |
-| **UI Extras** | Loading overlay, focus-event deep-linking, imperative ref API, settings panel, filter sidebar |
-| **Embeddable** | AgendaWidget (standalone card), AgendaDropdown (bell-icon notification panel) |
-| **Presets** | DefaultCalendar (styled), TailwindCalendar (Tailwind-optimized) |
-
-### Tech Stack
-
-| Layer | Technology |
-|---|---|
-| Runtime | React 18+/19, TypeScript 5.9 |
-| Build | Vite 7 (library mode), vite-plugin-dts |
-| Styling | TailwindCSS 4+, class-variance-authority (CVA), clsx, tailwind-merge |
-| UI Primitives | Radix UI (`@radix-ui/react-dialog` as direct dep; optional peer deps: popover, tooltip, dropdown-menu, scroll-area, select, avatar) |
-| Icons | lucide-react |
-| Date handling | Native Date API (no external date library) |
-| Linting | Biome 2.3 |
-
----
-
-## 2. npm Scripts
-
-```bash
-npm run dev          # Vite dev mode
-npm run build        # Production build (Vite + dts declarations)
-npm run typecheck    # tsc --noEmit
-npm run lint         # Biome lint check
-npm run format       # Biome format
-```
-
----
-
-## 3. Package Exports
-
-Defined in `package.json`:
-
-```jsonc
-{
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.mjs",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs"
-    },
-    "./utils": {
-      "types": "./dist/utils.d.ts",
-      "import": "./dist/utils.mjs",
-      "require": "./dist/utils.cjs"
-    },
-    "./core": {
-      "types": "./dist/core/index.d.ts",
-      "import": "./dist/core/index.mjs",
-      "require": "./dist/core/index.cjs"
-    },
-    "./components": {
-      "types": "./dist/components/index.d.ts",
-      "import": "./dist/components/index.mjs",
-      "require": "./dist/components/index.cjs"
-    },
-    "./presets": {
-      "types": "./dist/presets/index.d.ts",
-      "import": "./dist/presets/index.mjs",
-      "require": "./dist/presets/index.cjs"
-    },
-    "./lib": {
-      "types": "./dist/lib/index.d.ts",
-      "import": "./dist/lib/index.mjs",
-      "require": "./dist/lib/index.cjs"
-    },
-    "./styles": "./dist/styles/index.css",
-    "./styles.css": "./dist/styles/index.css"
-  }
-}
-```
-
-Consumer import patterns:
-
-```tsx
-// Components and types
-import { InnoCalendar, type CalendarEvent } from '@innosolutions/inno-calendar';
-// Core-only (headless hooks, types, utils)
-import { useCalendar, type TCalendarView } from '@innosolutions/inno-calendar/core';
-// Components only
-import { EventCard } from '@innosolutions/inno-calendar/components';
-// Presets only
-import { DefaultCalendar } from '@innosolutions/inno-calendar/presets';
-// Styles (required for built-in components)
-import '@innosolutions/inno-calendar/styles';
-```
-
----
-
-## 4. Core Types
-
-All types are defined in `src/core/types.ts` (1449 lines).
-
-### CalendarEvent\<TData\>
-
-```typescript
-interface CalendarEvent<TData = Record<string, unknown>> extends IBaseEvent {
-  // Required (from IBaseEvent)
-  id: string;
-  title: ReactNode;       // String or JSX — plain strings are fully backwards compatible
-  startDate: Date;
-  endDate: Date;
-
-  // Optional visual/behavioral
-  description?: ReactNode; // String or JSX
-  color?: TEventColor;
-  hexColor?: string;
-  isAllDay?: boolean;
-  isMultiDay?: boolean;
-  isCanceled?: boolean;
-  isRecurring?: boolean;
-  resourceId?: string;
-
-  // Built-in filtering (optional)
-  scheduleTypeId?: number;
-  scheduleTypeName?: ReactNode; // String or JSX
-  participants?: ICalendarUser[];
-
-  // Consumer data bag (RECOMMENDED for all domain fields)
-  data?: TData;
-
-  // @deprecated — still functional, will be removed in next major
-  meetingTookPlace?: boolean;
-  isAccepted?: boolean;
-  companyId?: number;
-  cancelReason?: string | null;
-  scheduleTypeCode?: string;
-  opportunityId?: number;
-  propertyId?: number;
-  projectId?: number;
-  contactId?: number;
-  user?: ICalendarUser;
-}
-```
-
-#### ReactNode Props
-
-`title`, `description`, and `scheduleTypeName` accept `ReactNode`. Pass plain strings (backwards compatible) or custom JSX. Built-in search and `aria-label` use `reactNodeToText()` to extract plain text from JSX nodes automatically.
-
-#### data bag: ReactNode-compatible fields
-
-The following `event.data` fields are rendered as `ReactNode` in EventCard/EventBlock:
-
-| Field | Type | Description |
-|---|---|---|
-| `productName` | `ReactNode` | Product/activity name line |
-| `siteName` | `ReactNode` | Location site name |
-| `siteCity` | `ReactNode` | Location city |
-| `extendedProps` | `ReactNode[]` | Arbitrary custom lines rendered below productName |
-
-`extendedProps` renders each array entry as its own row. Visible on EventCard (full variant always, EventBlock when >= 45min). Also shown in tooltips.
-
-### IResource\<TData\>
-
-```typescript
-interface IResource<TData = Record<string, unknown>> {
-  id: string;
-  name: string;
-  title?: string;
-  avatar?: string;
-  color?: TEventColor | string;
-  data?: TData;
-}
-```
-
-### IScheduleType\<TData\>
-
-```typescript
-interface IScheduleType<TData = Record<string, unknown>> {
-  id: number;
-  name: string;
-  color?: TEventColor | string;
-  icon?: string;
-  isDefault?: boolean;
-  isActive?: boolean;
-  code?: string;
-  resourceKey?: string;
-  colorHex?: string;
-  defaultMinutes?: number;
-  data?: TData;
-}
-```
-
-### ICalendarUser\<TData\>
-
-```typescript
-interface ICalendarUser<TData = Record<string, unknown>> {
-  id: string;
-  name: string;
-  email?: string;
-  avatar?: string;
-  data?: TData;
-}
-```
-
-### ICalendarRefHandle
-
-Imperative handle exposed via `React.forwardRef` on `<InnoCalendar>`:
-
-```typescript
-interface ICalendarRefHandle {
-  scrollToToday: () => void;
-  scrollToWorkingHours: () => void;
-  getViewRect: () => DOMRect | null;
-  focusEvent: (eventId: string) => void;
-}
-```
-
-Usage:
-
-```tsx
-const ref = useRef<ICalendarRefHandle>(null);
-<InnoCalendar ref={ref} events={events} />
-// Later:
-ref.current?.scrollToToday();
-ref.current?.focusEvent('appointment-42');
-```
-
-### ICalendarPreferences
-
-```typescript
-interface ICalendarPreferences {
-  startHour: number;        // 0–23
-  endHour: number;          // 0–24
-  firstDayOfWeek: 0|1|2|3|4|5|6;
-  slotDuration: number;
-  showWeekends: boolean;
-  timeFormat: '12h' | '24h';
-  badgeVariant: TBadgeVariant;
-  showCanceledEvents: boolean;
-}
-```
-
-### View Types
-
-```typescript
-type TCalendarView =
-  | 'day' | 'week' | 'month' | 'year' | 'agenda'
-  | 'resource-day' | 'resource-week'
-  | 'timeline-day' | 'timeline-3day' | 'timeline-week';
-```
-
-### Other Key Types
-
-| Type | Purpose |
-|---|---|
-| `TEventColor` | `'blue'│'green'│'red'│'yellow'│'purple'│'orange'│'pink'│'teal'│'gray'│'indigo'` |
-| `TBadgeVariant` | `'dot'│'colored'│'mixed'` |
-| `TSlotDuration` | `15│30│60` |
-| `TWorkingHours` | `Record<number, IWorkingHoursDay>` (0=Sun..6=Sat) |
-| `ISelectionResult` | `{ startDate: Date; endDate: Date; resourceId?: string }` |
-| `IDropResult<TData>` | Drag-drop result with event, newStartDate, newEndDate, newResourceId |
-| `IDateRange` | `{ startDate: Date; endDate: Date }` |
-| `IEventPosition` | `{ top, height, left, width, zIndex }` |
-| `IPositionedEvent<TData>` | Event + IEventPosition + column info |
-| `ICalendarFilters` | `{ scheduleTypeIds?, resourceIds?, search?, showCanceled?, dateRange?, [key]: unknown }` |
-| `TSelectionMode` | `'time'│'day'` |
-| `TEventDetailMode` | `'popover'│'dialog'│'sheet'│'custom'` — controls how event details are shown |
-| `ICalendarHeaderConfig` | Object with 7 optional boolean keys controlling header section visibility |
-
-### Callback Types
-
-| Type | Signature |
-|---|---|
-| `TOnEventClick<TData>` | `(event, e?) => void` |
-| `TOnSlotSelect` | `(selection: ISelectionResult) => void` |
-| `TOnEventDrop<TData>` | `(event, newStart, newEnd, newResourceId?) => void` |
-| `TOnEventResize<TData>` | `(event, newStart, newEnd) => void` |
-| `TOnViewChange` | `(view: TCalendarView) => void` |
-| `TOnDateChange` | `(date: Date) => void` |
-| `TOnFiltersChange` | `(filters: ICalendarFilters) => void` |
-
----
-
-## 5. InnoCalendar Props
-
-`<InnoCalendar>` is the primary entry point. It wraps `InnoCalendarProvider` + `SlotSelectionProvider` + `DragDropProvider` internally.
-
-```typescript
-interface InnoCalendarProps<TEventData> {
-  // === DATA ===
-  events: CalendarEvent<TEventData>[];
-  users?: ICalendarUser[];
-  scheduleTypes?: IScheduleType[];
-
-  // === INITIAL STATE ===
-  initialView?: TCalendarView;                    // default: 'week'
-  initialDate?: Date;                             // default: new Date()
-  initialSelectedUserId?: string | 'all';         // default: 'all'
-  initialScheduleTypeIds?: number[];
-  initialParticipantIds?: string[];
-  initialWorkingHoursView?: 'default' | 'enabled' | 'disabled';
-  initialSearchQuery?: string;
-
-  // === PREFERENCES ===
-  preferencesConfig?: IPreferencesConfig;
-
-  // === CALLBACKS ===
-  onEventClick?: (event: CalendarEvent<TEventData>) => void;
-  onSlotClick?: (date: Date, hour?: number) => void;
-  onSlotSelect?: (selection: ISelectionResult) => void;
-  onAddEvent?: () => void;
-  onEventDrop?: (result: IDropResult<TEventData>) => void;
-  onDateChange?: (date: Date, view: TCalendarView) => void;
-  onViewChange?: (view: TCalendarView) => void;
-
-  // === UI OPTIONS ===
-  className?: string;
-  showHeader?: boolean;                           // default: true
-  minSelectionMinutes?: number;                   // default: 30
-  showMoreMode?: 'dayView' | 'popover' | 'expand'; // default: 'expand'
-  isLoading?: boolean;                            // default: false
-
-  // === CUSTOM RENDERING ===
-  renderPopover?: (props: { event; onClose }) => ReactNode;
-  slots?: ICalendarSlots<TEventData>;
-  classNames?: ICalendarClassNames;
-
-  // === HEADER CONFIGURATION ===
-  headerConfig?: ICalendarHeaderConfig;            // fine-grained header visibility
-  // see ICalendarHeaderConfig below
-
-  // === EVENT DETAIL MODE ===
-  eventDetailMode?: TEventDetailMode;              // default: 'popover'
-  renderEventDetail?: (props: { event; onClose }) => ReactNode; // for 'custom' + override in dialog/sheet
-
-  // === CONTENT SLOTS ===
-  settingsContent?: ReactNode;
-  filterContent?: ReactNode;
-  headerActions?: ReactNode;
-
-  // === DEEP LINKING ===
-  focusEventId?: string | null;
-
-  // @deprecated — use showMoreMode instead
-  showMoreEventsInPopover?: boolean;
-}
-```
-
-#### ICalendarHeaderConfig
-
-Fine-grained visibility control for calendar header sections. Each key defaults to `true` when omitted.
-
-```typescript
-interface ICalendarHeaderConfig {
-  showToday?: boolean;           // Today button
-  showDateNavigator?: boolean;   // Prev/Next arrows + date label
-  showCalendarViews?: boolean;   // Day/Week/Month/Agenda dropdown
-  showResourceViews?: boolean;   // Timeline/Resource dropdown
-  showSettings?: boolean;        // Settings gear icon
-  showAddEvent?: boolean;        // "+" add event button
-  showFilters?: boolean;         // Filter row below header
-}
-```
-
-#### TEventDetailMode
-
-Controls how event details are displayed when clicking an event:
-
-- `'popover'` — Radix popover anchored to the event card (default)
-- `'dialog'` — Centered modal dialog overlay
-- `'sheet'` — Slide-in side panel from the right
-- `'custom'` — No built-in container; delegates to `renderEventDetail`
-
-```typescript
-type TEventDetailMode = 'popover' | 'dialog' | 'sheet' | 'custom';
-```
-
-### Ref Support
-
-`InnoCalendar` is wrapped with `forwardRef` and exposes `ICalendarRefHandle`:
-
-```tsx
-const calendarRef = useRef<ICalendarRefHandle>(null);
-<InnoCalendar ref={calendarRef} events={events} />
-```
-
----
-
-## 6. Slots System
-
-Every visual region can be replaced via `slots`:
-
-```typescript
-interface ICalendarSlots<TEventData, TScheduleTypeData, TResourceData> {
-  // Structural
-  header?: ComponentType<IHeaderSlotProps>;
-  footer?: ComponentType<IFooterSlotProps<TEventData>>;
-  viewWrapper?: ComponentType<IViewWrapperSlotProps>;
-
-  // Day Cell (month/year views)
-  dayCell?: ComponentType<IDayCellSlotPropsExtended<TEventData>>;
-  dayCellHeader?: ComponentType<IDayCellAdornmentSlotProps<TEventData>>;
-  dayCellFooter?: ComponentType<IDayCellAdornmentSlotProps<TEventData>>;
-  dayCellStartAdornment?: ComponentType<IDayCellAdornmentSlotProps<TEventData>>;
-  dayCellEndAdornment?: ComponentType<IDayCellAdornmentSlotProps<TEventData>>;
-
-  // Time Grid (day/week views)
-  timeGutter?: ComponentType<ITimeGutterSlotProps>;
-  timeSlotBackground?: ComponentType<ITimeSlotBackgroundSlotProps>;
-  columnHeader?: ComponentType<IColumnHeaderSlotProps>;
-  currentTimeIndicator?: ComponentType<ICurrentTimeIndicatorSlotProps>;
-  multiDayBanner?: ComponentType<IMultiDayBannerSlotProps<TEventData>>;
-
-  // Events
-  eventCard?: ComponentType<IEventCardSlotProps<TEventData>>;
-  eventPopover?: ComponentType<IEventPopoverSlotProps<TEventData>>;
-
-  // Resource/Timeline
-  resourceHeader?: ComponentType<IResourceHeaderSlotProps<TResourceData>>;
-  rowHeader?: ComponentType<IRowHeaderSlotProps<TResourceData>>;
-
-  // Filters
-  filter?: ComponentType<IFilterSlotProps<TScheduleTypeData>>;
-
-  // Empty States
-  emptyCell?: ComponentType<IEmptyCellSlotProps>;
-  emptyState?: ComponentType<IEmptyStateSlotProps>;
-
-  // @deprecated
-  timeSlot?: ComponentType<ITimeSlotSlotProps>;
-}
-```
-
-### Slot Props Interfaces
-
-| Slot | Props Interface | Key Fields |
-|---|---|---|
-| `header` | `IHeaderSlotProps` | currentDate, view, onNavigate, onViewChange |
-| `footer` | `IFooterSlotProps` | view, currentDate, events |
-| `viewWrapper` | `IViewWrapperSlotProps` | view, children |
-| `dayCell` | `IDayCellSlotPropsExtended` | date, events, isToday, isCurrentMonth, isWeekend, view, children, onDayClick |
-| `dayCellHeader/Footer` | `IDayCellAdornmentSlotProps` | date, events, isToday, isCurrentMonth, isWeekend, view |
-| `timeGutter` | `ITimeGutterSlotProps` | hour, formattedLabel, isFirst |
-| `timeSlotBackground` | `ITimeSlotBackgroundSlotProps` | date, hour, minute, isWorkingHour, isToday |
-| `columnHeader` | `IColumnHeaderSlotProps` | date, isToday, onDayClick, columnIndex |
-| `currentTimeIndicator` | `ICurrentTimeIndicatorSlotProps` | currentTime, topOffset |
-| `multiDayBanner` | `IMultiDayBannerSlotProps` | events, rangeStart, onEventClick |
-| `eventCard` | `IEventCardSlotProps` | event, view, isCompact, onClick |
-| `eventPopover` | `IEventPopoverSlotProps` | event, onClose, onEdit, onDelete |
-| `resourceHeader` | `IResourceHeaderSlotProps` | resource |
-| `rowHeader` | `IRowHeaderSlotProps` | resource, rowIndex |
-| `filter` | `IFilterSlotProps` | scheduleTypes, filters, onFiltersChange |
-| `emptyCell` | `IEmptyCellSlotProps` | date, isToday |
-| `emptyState` | `IEmptyStateSlotProps` | view, dateRange |
-
----
-
-## 7. ClassNames API
-
-`ICalendarClassNames` provides 34 CSS class override keys. Classes are merged with defaults via `cn()`.
-
-```typescript
-interface ICalendarClassNames {
-  // Structural
-  root?: string;
-  header?: string;
-  footer?: string;
-  viewContainer?: string;
-
-  // Month View
-  monthGrid?: string;
-  weekdayHeader?: string;
-  weekdayLabel?: string;
-  dayCell?: string;
-  dayCellToday?: string;
-  dayCellOutside?: string;
-  dayCellWeekend?: string;
-  dayCellNumber?: string;
-  dayCellContent?: string;
-  dayCellFooter?: string;
-
-  // Week/Day View
-  timeGutter?: string;
-  timeGutterLabel?: string;
-  timeSlot?: string;
-  timeSlotWorking?: string;
-  timeSlotNonWorking?: string;
-  columnHeader?: string;
-  columnHeaderToday?: string;
-  currentTimeIndicator?: string;
-  scrollContainer?: string;
-
-  // Events
-  eventCard?: string;
-  eventCardCompact?: string;
-  eventPopover?: string;
-  multiDayBanner?: string;
-  moreEventsIndicator?: string;
-
-  // Timeline
-  resourceHeader?: string;
-  resourceRow?: string;
-  timelineCell?: string;
-
-  // Agenda
-  agendaList?: string;
-  agendaDayGroup?: string;
-  agendaDayHeader?: string;
-}
-```
-
----
-
-## 8. EventCard & EventBlock
-
-Located in `src/components/event/event-card.tsx`.
-
-### EventCard
-
-Full-size event card used in day/week/timeline views. Renders differently based on `badgeVariant`:
-
-| Badge Variant | Rendering |
-|---|---|
-| `'colored'` | Filled background with accent color, white/dark text |
-| `'dot'` | White background with colored left-border accent |
-| `'mixed'` | Light tinted background with colored left-border |
-
-Key props:
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `event` | `CalendarEvent<TData>` | required | Event data |
-| `variant` | `'full'\|'compact'\|'dot'` | `'full'` | Visual layout |
-| `badgeVariant` | `TBadgeVariant` | `'colored'` | Color treatment |
-| `onClick` | `(event) => void` | — | Click callback |
-| `showTime` | `boolean` | `true` | Show time display |
-| `showDescription` | `boolean` | `false` | Show event description |
-| `showParticipants` | `boolean` | `false` | Show participant avatars |
-| `disablePopover` | `boolean` | `false` | Skip built-in popover, fire `onClick` |
-| `renderPopover` | `(props) => ReactNode` | — | Custom content inside the default popover shell |
-| `enableDrag` | `boolean` | `false` | Enable HTML5 drag & drop |
-| `enablePageTransition` | `boolean` | `false` | Enable page transition animation |
-| `pageTransitionDuration` | `number` | `400` | Page transition duration in ms |
-| `eventDetailMode` | `TEventDetailMode` | `'popover'` | Container for event details: popover, dialog, sheet, custom |
-| `renderEventDetail` | `(props) => ReactNode` | — | Custom renderer for 'custom' mode; also inner content for dialog/sheet |
-| `style` | `CSSProperties` | — | Inline styles |
-| `className` | `string` | — | Additional CSS classes |
-
-Built-in cards display enrichment data read from `event.data` first, with fallback to deprecated top-level fields:
-
-```typescript
-// Runtime enrichment reading pattern:
-const eventData = event.data as Record<string, unknown> | undefined;
-const meetingTookPlace = (eventData?.meetingTookPlace as boolean) ?? event.meetingTookPlace ?? false;
-const productName = eventData?.productName as ReactNode | undefined;
-const siteName = eventData?.siteName as ReactNode | undefined;
-const siteCity = eventData?.siteCity as ReactNode | undefined;
-const extendedProps = eventData?.extendedProps as ReactNode[] | undefined;
-const nrParticipant = eventData?.nrParticipant as number | undefined;
-```
-
-### EventBlock
-
-Positioned event block for day/week time grid. Renders with absolute positioning inside the time column.
-
-### MultiDayEventBar
-
-Horizontal bar for multi-day/all-day events in the banner strip above day/week time grids.
-
-### Exports
-
-```typescript
-export { EventCard, type EventCardProps }
-export { EventBlock, type EventBlockProps }
-export { MultiDayEventBar, type MultiDayEventBarProps }
-export { getEventColorClasses }  // Utility: TEventColor → { bg, text, border }
-```
-
----
-
-## 9. EventPopover Component
-
-Located in `src/components/event/event-popover.tsx` (~1400 lines).
-
-Full-featured event detail popover with action buttons, participant list, and domain data display.
-
-### Key Props
-
-```typescript
-interface EventPopoverProps<TData = Record<string, unknown>> {
-  event: IPopoverEvent<TData>;
-  children: ReactNode;
-  open?: boolean;
-  onOpenChange?: (open: boolean) => void;
-  isLoading?: boolean;
-
-  // Action callbacks
-  onEdit?: (event: IPopoverEvent<TData>) => void;
-  onDelete?: (event: IPopoverEvent<TData>) => void;
-  onCancel?: (event: IPopoverEvent<TData>) => void;
-  onAccept?: (event: IPopoverEvent<TData>) => void;
-  onDecline?: (event: IPopoverEvent<TData>) => void;
-  onConfirmMeeting?: (event: IPopoverEvent<TData>) => void;
-
-  // Permission flags
-  canEdit?: boolean;
-  canDelete?: boolean;
-  canCancel?: boolean;
-
-  // Current user state
-  isCurrentUserParticipant?: boolean;
-  isCurrentUserClient?: boolean;
-  currentUserAcceptStatus?: boolean | null;
-
-  // Loading states
-  isAcceptLoading?: boolean;
-  isDeclineLoading?: boolean;
-  isConfirmLoading?: boolean;
-  isDeleteLoading?: boolean;
-
-  // Render customization
-  renderParticipant?: (participant: IEventParticipant, index: number) => ReactNode;
-  renderHeaderActions?: (props: { onClose: () => void }) => ReactNode;
-  renderCancelReason?: (event: IPopoverEvent<TData>) => ReactNode;
-  renderDeleteConfirmation?: (props: {
-    onConfirm: () => void;
-    onCancel: () => void;
-    isLoading?: boolean;
-  }) => ReactNode;
-
-  // Formatting
-  formatDate?: (date: Date, format?: string) => string;
-  formatTimeRange?: (start: Date, end: Date) => string;
-
-  // Styling
-  className?: string;
-  width?: number;
-
-  // i18n labels
-  labels?: Partial<IEventPopoverLabels>;
-}
-```
-
-### IEventPopoverLabels
-
-All label strings are customizable for i18n:
-
-```typescript
-interface IEventPopoverLabels {
-  edit?: string;
-  delete?: string;
-  cancel?: string;
-  close?: string;
-  going?: string;
-  notGoing?: string;
-  confirmMeeting?: string;
-  completed?: string;
-  canceled?: string;
-  participants?: string;
-  guest?: string;
-  guests?: string;
-  confirmed?: string;
-  organizer?: string;
-  client?: string;
-  more?: string;
-  noDateProvided?: string;
-  eventNotFound?: string;
-  cancellationNote?: string;
-  canceledOn?: string;
-  acceptThisEvent?: string;
-  acceptAllEvents?: string;
-  deleteConfirmTitle?: string;
-  deleteConfirmDescription?: string;
-}
-```
-
----
-
-## 10. Preferences System
-
-Located in `src/core/preferences/`.
-
-### IPreferencesConfig
-
-Passed via `<InnoCalendar preferencesConfig={...}>`:
-
-```typescript
-interface IPreferencesConfig {
-  modes?: TPreferenceModes;       // Per-key control mode
-  locked?: TLockedPreferences;    // Values for locked preferences
-  defaults?: TPartialPreferences; // Custom defaults
-  storageKey?: string;            // Custom localStorage key
-  disableStorage?: boolean;       // Disable localStorage entirely
-}
-```
-
-### Preference Modes
-
-| Mode | Behavior |
-|---|---|
-| `'user'` | User can modify, persisted to localStorage (default) |
-| `'locked'` | Developer-controlled, user cannot modify |
-| `'session'` | User can modify during session, not persisted |
-
-### IPreferences
-
-```typescript
-interface IPreferences {
-  view: TCalendarView;
-  badgeVariant: TBadgeVariant;
-  slotDuration: TSlotDuration;
-  visibleHours: IVisibleHoursConfig;         // { from: number; to: number }
-  workingHours: TWorkingHoursConfig;         // { [dayIndex]: { from, to } }
-  showWorkingHoursOnly: boolean;
-  showWeekends: boolean;
-  firstDayOfWeek: 0|1|2|3|4|5|6;
-}
-```
-
-### useCalendarPreferences Hook
-
-Returns `IUsePreferencesReturn`:
-
-```typescript
-interface IUsePreferencesReturn {
-  preferences: IPreferences;
-  setPreference: <K extends TPreferenceKey>(key: K, value: IPreferences[K]) => void;
-  setPreferences: (updates: TPartialPreferences) => void;
-  resetPreferences: () => void;
-  resetPreference: (key: TPreferenceKey) => void;
-  isLocked: (key: TPreferenceKey) => boolean;
-  isPersisted: (key: TPreferenceKey) => boolean;
-  getMode: (key: TPreferenceKey) => TPreferenceMode;
-}
-```
-
-### Example: Locking slot duration
-
-```tsx
-<InnoCalendar
-  events={events}
-  preferencesConfig={{
-    modes: { slotDuration: 'locked' },
-    locked: { slotDuration: 30 },
-  }}
-/>
-```
-
----
-
-## 11. Widget Components
-
-Located in `src/components/widget/`.
-
-### AgendaWidget
-
-Embeddable agenda card for dashboards. Can work standalone or tap into an existing `InnoCalendarProvider`.
-
-```typescript
-interface AgendaWidgetProps {
-  events: CalendarEvent[];
-  maxItems?: number;
-  onEventClick?: (event: CalendarEvent) => void;
-  className?: string;
-  // ... additional display options
-}
-```
-
-### AgendaDropdown
-
-Bell-style notification dropdown for upcoming events:
-
-```typescript
-interface AgendaDropdownProps {
-  events: CalendarEvent[];
-  onEventClick?: (event: CalendarEvent) => void;
-  className?: string;
-  // ... trigger customization
-}
-```
-
----
-
-## 12. Filter Components
-
-Located in `src/components/filters/`.
-
-### CalendarFilterSidebar
-
-Full filter panel with schedule type and user filters:
-
-```typescript
-interface CalendarFilterSidebarProps {
-  scheduleTypes: IScheduleTypeOption[];
-  users: IUserOption[];
-  labels?: CalendarFilterSidebarLabels;
-  // Controlled state or context-driven
-}
-```
-
-### ScheduleTypeFilter
-
-Standalone schedule type filter component with checkbox list.
-
-### UserFilter
-
-Standalone user/participant filter with avatar support.
-
----
-
-## 13. Settings Components
-
-Located in `src/components/settings/`.
-
-| Component | Props | What It Controls |
-|---|---|---|
-| `BadgeVariantSetting` | `BadgeVariantSettingProps` | Dot / Colored / Mixed badge display |
-| `SlotDurationSetting` | `SlotDurationSettingProps` | 15 / 30 / 60 minute time slot granularity |
-| `VisibleHoursSetting` | `VisibleHoursSettingProps` | Start/end hour range for day/week views |
-| `WorkingHoursSetting` | `WorkingHoursSettingProps` | Per-day working hours with enable/disable toggle |
-
-All settings components read/write preferences through the preferences context.
-
----
-
-## 14. Context & Hooks
-
-### Context Providers
-
-| Provider | Purpose |
-|---|---|
-| `InnoCalendarProvider` | Main state: events, date, view, filters, search, preferences, time config |
-| `CalendarProvider` | Lower-level provider (used by `Calendar` component) |
-| `SlotSelectionProvider` | Drag-to-select state management |
-| `DragDropProvider` | Event drag-and-drop state management |
-
-### Primary Hooks
-
-| Hook | Return Type | Purpose |
-|---|---|---|
-| `useInnoCalendar()` | `IInnoCalendarContext` | Full context access (events, view, date, filters, search, preferences) |
-| `useCalendarContext()` | `IInnoCalendarContext` | Alias for `useInnoCalendar` |
-| `useCalendar()` | `UseCalendarReturn` | Core calendar state (date, view, navigation, event helpers) |
-| `useSlotSelection()` | `UseSlotSelectionReturn` | Drag-to-select hook |
-| `useCalendarTimeConfig()` | `UseCalendarTimeConfigReturn` | Slot duration, visible hours, working hours |
-| `usePreferences()` | `UsePreferencesReturn` | Basic preferences hook |
-| `useAdvancedPreferences()` | `IUsePreferencesReturn` | Full preferences with locking support |
-| `useDragDrop()` | `IDragDropContext` | Drag-drop state and handlers |
-
-### Selective Context Hooks
-
-These read only a slice of the context for performance:
-
-| Hook | Returns |
-|---|---|
-| `useCalendarDate()` | Current date + navigation |
-| `useCalendarView()` | Current view + view change |
-| `useCalendarEvents()` | Events array + setEvents |
-| `useCalendarFilters()` | Filter state + setters |
-| `useCalendarPreferences()` | Preferences from context |
-| `useInnoCalendarView()` | View from InnoCalendar context |
-| `useInnoCalendarEvents()` | Events from InnoCalendar context |
-| `useInnoCalendarFilters()` | Filters from InnoCalendar context |
-| `useInnoCalendarTimeConfig()` | Time config from InnoCalendar context |
-
-### Optional Hooks (no throw if outside provider)
-
-| Hook | Returns |
-|---|---|
-| `useOptionalCalendar()` | `context │ undefined` |
-| `useOptionalCalendarContext()` | `context │ undefined` |
-| `useOptionalInnoCalendar()` | `context │ undefined` |
-| `useOptionalDragDrop()` | `context │ undefined` |
-| `useOptionalSlotSelection()` | `context │ undefined` |
-
-### Legacy Aliases (backward compat)
-
-| Alias | Maps To |
-|---|---|
-| `IntegratedCalendarProvider` | `InnoCalendarProvider` |
-| `useIntegratedCalendar()` | `useInnoCalendar()` |
-| `useIntegratedCalendarEvents()` | `useInnoCalendarEvents()` |
-| `useIntegratedCalendarFilters()` | `useInnoCalendarFilters()` |
-| `useIntegratedCalendarView()` | `useInnoCalendarView()` |
-| `useIntegratedCalendarTimeConfig()` | `useInnoCalendarTimeConfig()` |
-| `useOptionalIntegratedCalendar()` | `useOptionalInnoCalendar()` |
-| `IntegratedCalendar` | `InnoCalendar` |
-
----
-
-## 15. Drag & Drop
-
-Located in `src/core/context/drag-drop-context.tsx`.
-
-### DragDropProvider
-
-Manages drag state for event repositioning. Wraps the calendar tree automatically when using `<InnoCalendar>`.
-
-```typescript
-interface IDragState<TData = Record<string, unknown>> {
-  event: CalendarEvent<TData>;
-  originalStartDate: Date;
-  originalEndDate: Date;
-  previewDate?: Date;              // current preview position
-  previewHour?: number;            // for time-based views
-  previewMinute?: number;
-  originalResourceId?: string;     // for resource/timeline views
-  targetResourceId?: string;       // current drag target resource
-}
-
-interface IDropResult<TData = Record<string, unknown>> {
-  event: CalendarEvent<TData>;
-  newStartDate: Date;
-  newEndDate: Date;                // maintains original duration
-  newResourceId?: string;          // set when dropped on different resource
-}
-
-interface IDragDropContext<TData = Record<string, unknown>> {
-  dragState: IDragState<TData> | null;
-  isDragging: boolean;
-  startDrag: (event: CalendarEvent<any>) => void;
-  updateDragPreview: (date: Date, hour?: number, minute?: number, resourceId?: string) => void;
-  endDrag: () => IDropResult<TData> | null;
-  cancelDrag: () => void;
-}
-```
-
-### Timeline / Resource View Drag & Drop
-
-`TimelineView` supports HTML5 drag & drop out of the box:
-
-- Events render with `enableDrag={true}` by default
-- Each resource row acts as a drop zone
-- Dragging across rows updates `targetResourceId` in the drag state
-- Dropping calls `endDrag()` which fires `onEventDrop` on `DragDropProvider`
-
-```tsx
-<InnoCalendar
-  events={events}
-  initialView="timeline-week"
-  onEventDrop={(result) => {
-    console.log(result.event.id, result.newStartDate, result.newResourceId);
-    // Update your backend
-  }}
-/>
-```
-
----
-
-## 16. Core Utilities
-
-Located in `src/core/utils/`. All exported from `src/core/utils/index.ts`.
-
-### date-utils.ts
-
-Date manipulation using native Date API:
-
-| Function | Signature |
-|---|---|
-| `startOfDay` | `(date: Date) => Date` |
-| `endOfDay` | `(date: Date) => Date` |
-| `startOfWeek` | `(date: Date, weekStartsOn?: 0\|1\|2\|3\|4\|5\|6) => Date` |
-| `endOfWeek` | `(date: Date, weekStartsOn?: 0\|1\|2\|3\|4\|5\|6) => Date` |
-| `startOfMonth` | `(date: Date) => Date` |
-| `endOfMonth` | `(date: Date) => Date` |
-| `startOfYear` | `(date: Date) => Date` |
-| `endOfYear` | `(date: Date) => Date` |
-| `addDays` | `(date: Date, days: number) => Date` |
-| `subDays` | `(date: Date, days: number) => Date` |
-| `addWeeks` | `(date: Date, weeks: number) => Date` |
-| `subWeeks` | `(date: Date, weeks: number) => Date` |
-| `addMonths` | `(date: Date, months: number) => Date` |
-| `subMonths` | `(date: Date, months: number) => Date` |
-| `addYears` | `(date: Date, years: number) => Date` |
-| `subYears` | `(date: Date, years: number) => Date` |
-| `addHours` | `(date: Date, hours: number) => Date` |
-| `addMinutes` | `(date: Date, minutes: number) => Date` |
-| `setTime` | `(date: Date, hours: number, minutes?: number, seconds?: number) => Date` |
-| `getDecimalHours` | `(date: Date) => number` |
-| `isSameDay` | `(a: Date, b: Date) => boolean` |
-| `isSameWeek` | `(a: Date, b: Date, weekStartsOn?) => boolean` |
-| `isSameMonth` | `(a: Date, b: Date) => boolean` |
-| `isSameYear` | `(a: Date, b: Date) => boolean` |
-| `isToday` | `(date: Date) => boolean` |
-| `isWeekend` | `(date: Date) => boolean` |
-| `getDayOfWeek` | `(date: Date) => number` |
-| `isBefore` | `(a: Date, b: Date) => boolean` |
-| `isAfter` | `(a: Date, b: Date) => boolean` |
-| `isBetween` | `(date: Date, start: Date, end: Date) => boolean` |
-| `minDate` | `(dates: Date[]) => Date \| undefined` |
-| `maxDate` | `(dates: Date[]) => Date \| undefined` |
-| `differenceInMilliseconds` | `(a: Date, b: Date) => number` |
-| `differenceInMinutes` | `(a: Date, b: Date) => number` |
-| `differenceInHours` | `(a: Date, b: Date) => number` |
-| `differenceInDays` | `(a: Date, b: Date) => number` |
-| `getWeekDays` | `(date: Date, weekStartsOn?) => Date[]` |
-| `getWeekNumber` | `(date: Date) => number` |
-| `getDaysInMonth` | `(date: Date) => number` |
-| `getYearMonths` | `(year: number) => Date[]` |
-| `formatTime` | `(date: Date, format?: '12h'\|'24h') => string` |
-| `formatDateISO` | `(date: Date) => string` |
-| `formatHourLabel` | `(hour: number, format?: '12h'\|'24h') => string` |
-| `parseISO` | `(dateString: string) => Date` |
-| `eachDayOfInterval` | `(start: Date, end: Date) => Date[]` |
-| `eachHourOfInterval` | `(start: Date, end: Date) => Date[]` |
-| `getWeekdayNames` | `(locale?, format?) => string[]` |
-| `getMonthNames` | `(locale?, format?) => string[]` |
-| `getVisibleHoursArray` | `(visibleHours) => number[]` |
-| `generateMonthGrid` | `(date: Date, weekStartsOn?) => Array<{ date, isCurrentMonth, isWeekend }>` |
-| `detectAllDayEvent` | `(event) => boolean` |
-| `separateEventsByDuration` | `<TEvent>(events) => { singleDay, multiDay }` |
-| `getEventsInRange` | `<TEvent>(events, rangeStart, rangeEnd) => TEvent[]` |
-| `isWorkingHour` | `(date, hour, workingHours?) => boolean` |
-| `getWorkingHoursForDay` | `(date, workingHours) => { from, to } \| null` |
-
-### event-utils.ts
-
-Event filtering, sorting, classification, and color utilities:
-
-| Function | Purpose |
-|---|---|
-| `isMultiDayEvent` | Checks if event spans midnight |
-| `getEventsForDay` | Filters events that overlap a given day |
-| `getAllDayEvents` | Filters all-day events from array |
-| `getTimedEvents` | Filters timed (non-all-day) events |
-| `getMultiDayEvents` | Filters multi-day events |
-| `filterEventsByDateRange` | Filters events overlapping a date range |
-| `filterEventsByScheduleType` | Client-side schedule type filter |
-| `filterEventsByResource` | Client-side resource filter |
-| `filterEventsBySearch` | Text search across event fields |
-| `filterOutCanceled` | Remove canceled events |
-| `applyEventFilters` | Composite filter applying multiple criteria |
-| `sortEventsByStart` | Sort by start date |
-| `sortEventsByEnd` | Sort by end date |
-| `sortEventsByDuration` | Sort by event duration |
-| `groupEventsByDate` | Groups events by calendar date |
-| `groupEventsByScheduleType` | Groups events by schedule type |
-| `groupEventsByResource` | Groups events by resourceId |
-| `getEventDurationMinutes` | Returns event duration in minutes |
-| `getEventColor` | Resolves event color with fallback |
-| `formatEventTimeDisplay` | Formats event time for display |
-
-### grid-utils.ts
-
-Grid layout calculations, view navigation, and cell generation:
-
-| Function | Purpose |
-|---|---|
-| `getViewDateRange` | Returns date range for any view |
-| `navigateNext` | Advance date by one view step |
-| `navigatePrev` | Go back one view step |
-| `navigateToday` | Returns today's Date |
-| `generateMonthCells` | Creates cell array for month grid |
-| `generateWeekCells` | Creates cell array for week view |
-| `generateYearCells` | Creates cell array for year view |
-| `generateTimeSlots` | Creates time slot array for given hour range and slot duration |
-| `generateHourLabels` | Creates hour label array for gutter |
-| `getViewTitle` | Formatted title string for current view + date |
-
-### react-node-utils.ts
-
-Utility for extracting plain text from ReactNode trees:
-
-| Function | Signature | Purpose |
-|---|---|---|
-| `reactNodeToText` | `(node: ReactNode) => string` | Recursively extracts plain text from any ReactNode. Used internally for search, aria-labels, and string operations on ReactNode-typed fields. |
-
-```typescript
-reactNodeToText("hello")                              // "hello"
-reactNodeToText(<span>hello <b>world</b></span>)      // "hello world"
-reactNodeToText(<><MapPinIcon /> BELGIUM</>)           // " BELGIUM"
-reactNodeToText(null)                                  // ""
-reactNodeToText(42)                                    // "42"
-```
-
-### position-utils.ts
-
-Event overlap and positioning:
-
-| Function | Purpose |
-|---|---|
-| `calculateEventPosition` | Computes position for a single event in a column |
-| `calculateOverlappingPositions` | Computes non-overlapping layout for multiple events |
-| `yToTime` | Converts vertical pixel offset to Date |
-| `timeToY` | Converts Date to vertical pixel offset |
-| `eventsOverlap` | Checks if two events overlap in time |
-| `getOverlappingGroups` | Groups events that share time ranges |
-| `calculateSelectionOverlay` | Computes drag selection overlay dimensions |
-
----
-
-## 17. Presets
-
-Located in `src/presets/`.
-
-### DefaultCalendar
-
-Pre-configured calendar with sensible defaults:
-
-```tsx
-import { DefaultCalendar } from '@innosolutions/inno-calendar';
-
-<DefaultCalendar events={events} />
-```
-
-### TailwindCalendar
-
-Tailwind-optimized calendar preset with carefully chosen utility classes:
-
-```tsx
-import { TailwindCalendar } from '@innosolutions/inno-calendar';
-
-<TailwindCalendar events={events} />
-```
-
----
-
-## 18. CSS & Theming
-
-Styles are in `src/styles/calendar.css` (imported via `@innosolutions/inno-calendar/styles`).
-
-### CSS Custom Properties
-
-```css
-:root {
-  /* Surfaces */
-  --inno-border-color: #e5e7eb;
-  --inno-background: #ffffff;
-  --inno-foreground: #111827;
-  --inno-muted: #f3f4f6;
-  --inno-muted-foreground: #6b7280;
-  --inno-primary: #3b82f6;
-  --inno-primary-foreground: #ffffff;
-
-  /* Event Colors */
-  --inno-event-blue: #3b82f6;
-  --inno-event-green: #22c55e;
-  --inno-event-red: #ef4444;
-  --inno-event-yellow: #eab308;
-  --inno-event-purple: #a855f7;
-  --inno-event-orange: #f97316;
-  --inno-event-pink: #ec4899;
-  --inno-event-teal: #14b8a6;
-  --inno-event-gray: #6b7280;
-  --inno-event-indigo: #6366f1;
-
-  /* Layout */
-  --inno-hour-height: 96px;
-  --inno-header-height: 56px;
-  --inno-sidebar-width: 200px;
-}
-```
-
-### Dark Mode
-
-Override with `.dark` class:
-
-```css
-.dark {
-  --inno-border-color: #374151;
-  --inno-background: #111827;
-  --inno-foreground: #f9fafb;
-  --inno-muted: #1f2937;
-  --inno-muted-foreground: #9ca3af;
-}
-```
-
-### Key CSS Classes
-
-| Class | Purpose |
-|---|---|
-| `.inno-calendar-root` | Root container with scrollbar styles |
-| `.inno-calendar-loading-overlay` | Translucent loading indicator overlay |
-| `.inno-calendar-spinner` | Spinner animation |
-| `.inno-calendar-selection` | Drag-to-select overlay |
-| `.inno-calendar-current-time` | Red current time indicator |
-| `.inno-calendar-event` | Event card styling |
-| `.inno-calendar-event-canceled` | Canceled event styling |
-| `.inno-calendar-disabled-hour` | Disabled/non-working hours pattern |
-| `.inno-calendar-no-scrollbar` | Hide scrollbar utility |
-| `.inno-scroll-nav` | D-pad controller container |
-| `.inno-scroll-nav-btn` | Directional buttons (up, down, left, right) |
-| `.ic-expansion-backdrop` | Backdrop for expanded month cell |
-| `.ic-expansion-panel` | Expanded events panel in month view |
-
----
-
-## 19. Constants
-
-Located in `src/core/constants.ts`.
-
-### View List
-
-```typescript
-const CALENDAR_VIEWS: TCalendarView[] = [
-  'day', 'week', 'month', 'year', 'agenda',
-  'resource-day', 'resource-week',
-  'timeline-day', 'timeline-week'
-];
-```
-
-### Default Preferences
-
-```typescript
-const DEFAULT_PREFERENCES: ICalendarPreferences = {
-  startHour: 8,
-  endHour: 18,
-  firstDayOfWeek: 1,  // Monday
-  slotDuration: 30,
-  showWeekends: true,
-  timeFormat: '24h',
-  badgeVariant: 'colored',
-  showCanceledEvents: false,
-};
-```
-
-### Color Palette
-
-```typescript
-const EVENT_COLORS: Record<TEventColor, string> = {
-  blue: '#3b82f6', green: '#22c55e', red: '#ef4444',
-  yellow: '#eab308', purple: '#a855f7', orange: '#f97316',
-  pink: '#ec4899', teal: '#14b8a6', gray: '#6b7280', indigo: '#6366f1',
-};
-
-const EVENT_COLOR_CLASSES: Record<TEventColor, { bg, text, border }>;
-const HEX_TO_EVENT_COLOR: Record<string, TEventColor>;
-```
-
-### Grid Constants
-
-| Constant | Value |
-|---|---|
-| `DEFAULT_HOUR_HEIGHT` | 64px |
-| `DEFAULT_SLOT_HEIGHT` | 32px |
-| `DEFAULT_HEADER_HEIGHT` | 56px |
-| `DEFAULT_RESOURCE_WIDTH` | 200px |
-| `MIN_EVENT_HEIGHT` | 20px |
-| `HOURS_IN_DAY` | 24 |
-| `MINUTES_IN_HOUR` | 60 |
-| `MS_PER_MINUTE` | 60000 |
-| `MS_PER_HOUR` | 3600000 |
-| `MS_PER_DAY` | 86400000 |
-
-### Time Defaults
-
-```typescript
-const DEFAULT_VISIBLE_HOURS: IVisibleHours = { startHour: 0, endHour: 24 };
-const DEFAULT_BUSINESS_HOURS: IVisibleHours = { startHour: 8, endHour: 18 };
-```
-
----
-
-## 20. Integration Guide
-
-### Minimal Setup
-
-```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-12T09:00:00'),
-    endDate: new Date('2026-02-12T10:00:00'),
-    color: 'blue',
-  },
-];
-
-function App() {
-  return (
-    <InnoCalendar
-      events={events}
-      onEventClick={(event) => console.log('Clicked:', event.title)}
-      onSlotSelect={(sel) => console.log('Selected:', sel.startDate, sel.endDate)}
-    />
-  );
-}
-```
-
-### With Custom Popover
-
-```tsx
-<InnoCalendar
-  events={events}
-  renderPopover={({ event, onClose }) => (
-    <div className="p-4 space-y-2">
-      <h3 className="font-bold">{event.title}</h3>
-      <p>{event.description}</p>
-      <button onClick={onClose}>Close</button>
-    </div>
-  )}
-/>
-```
-
-### With Loading State
-
-```tsx
-const [isLoading, setIsLoading] = useState(false);
-
-<InnoCalendar
-  events={events}
-  isLoading={isLoading}
-  onDateChange={async (date, view) => {
-    setIsLoading(true);
-    const newEvents = await fetchEvents(date, view);
-    setEvents(newEvents);
-    setIsLoading(false);
-  }}
-/>
-```
-
-### With Deep-Linking
-
-```tsx
-// URL: /calendar?eventId=appointment-42
-const eventId = useSearchParams().get('eventId');
-
-<InnoCalendar events={events} focusEventId={eventId} />
-```
-
-### Imperative Control
-
-```tsx
-const ref = useRef<ICalendarRefHandle>(null);
-
-<Button onClick={() => ref.current?.scrollToWorkingHours()}>
-  Go to Work Hours
-</Button>
-
-<InnoCalendar ref={ref} events={events} />
-```
-
-### Resource / Timeline Views
-
-```tsx
-const resources: IResource[] = [
-  { id: 'room-a', name: 'Meeting Room A', color: 'blue' },
-  { id: 'room-b', name: 'Board Room', color: 'green' },
-];
-
-<InnoCalendar
-  events={events}
-  initialView="timeline-week"
-  onEventDrop={(result) => {
-    // result.newResourceId is set when event is dragged to a different row
-    api.updateEvent(result.event.id, {
-      startDate: result.newStartDate,
-      endDate: result.newEndDate,
-      resourceId: result.newResourceId,
-    });
-  }}
-/>
-```
-
-### Header Configuration
-
-```tsx
-// Hide resource views and settings — only show calendar views + Today + navigation
-<InnoCalendar
-  events={events}
-  headerConfig={{
-    showResourceViews: false,
-    showSettings: false,
-    showFilters: false,
-  }}
-/>
-```
-
-### Event Detail Mode
-
-```tsx
-// Show event details in a slide-in sheet instead of default popover
-<InnoCalendar
-  events={events}
-  eventDetailMode="sheet"
-/>
-
-// Fully custom event detail container
-<InnoCalendar
-  events={events}
-  eventDetailMode="custom"
-  renderEventDetail={({ event, onClose }) => (
-    <MyCustomDrawer event={event} onClose={onClose} />
-  )}
-/>
-```
-
-### With Preferences Locking
-
-```tsx
-<InnoCalendar
-  events={events}
-  preferencesConfig={{
-    defaults: { view: 'month', badgeVariant: 'dot' },
-    modes: {
-      slotDuration: 'locked',
-      showWeekends: 'locked',
-    },
-    locked: {
-      slotDuration: 30,
-      showWeekends: false,
-    },
-  }}
-/>
-```
-
-### Widget Embedding
-
-```tsx
-import { AgendaWidget, AgendaDropdown } from '@innosolutions/inno-calendar';
-
-// Dashboard card
-<AgendaWidget events={todayEvents} onEventClick={openEvent} />
-
-// Navbar notification bell
-<AgendaDropdown events={upcomingEvents} onEventClick={openEvent} />
-```
-
-### Custom Slot Example
-
-```tsx
-<InnoCalendar
-  events={events}
-  slots={{
-    dayCellFooter: ({ date, events }) => (
-      <div className="text-xs text-muted-foreground border-t mt-1 pt-1">
-        {events.length} events
-      </div>
-    ),
-    columnHeader: ({ date, isToday, onDayClick }) => (
-      <button
-        className={cn('text-center', isToday && 'font-bold text-primary')}
-        onClick={() => onDayClick?.(date)}
-      >
-        {date.toLocaleDateString(undefined, { weekday: 'short', day: 'numeric' })}
-      </button>
-    ),
-  }}
-/>
-```
-
----
-
-## 21. Full Export Catalog
-
-### From `src/components/`
-
-**Main Components:**
-- `InnoCalendar`, `InnoCalendarProps`
-- `Calendar`, `CalendarProps`
-- `IntegratedCalendar` (alias), `IntegratedCalendarProps` (alias)
-
-**Event Components:**
-- `EventCard`, `EventCardProps`
-- `EventBlock`, `EventBlockProps`
-- `EventPopover`, `EventPopoverProps`, `IEventPopoverLabels`, `IPopoverEvent`, `IEventParticipant`
-- `MultiDayEventBar`, `MultiDayEventBarProps`
-- `getEventColorClasses`
-
-**Header Components:**
-- `CalendarHeader`, `CalendarHeaderProps`
-- `DateNavigator`, `DateNavigatorProps`
-- `TodayButton`, `TodayButtonProps`
-
-**View Components:**
-- `DayView`, `DayViewProps`
-- `WeekView`, `WeekViewProps`
-- `MonthView`, `MonthViewProps`
-- `YearView`, `YearViewProps`
-- `AgendaView`, `AgendaViewProps`
-- `TimelineView`, `TimelineViewProps`
-- `DayEventsExpansion`, `DayEventsExpansionProps`
-
-**Primitive Components:**
-- `DaySlot`, `DaySlotProps`
-- `MultiDayBanner`, `MultiDayBannerProps`
-- `TimeSlot`
-
-> **Internal-only Primitives** (not re-exported via public barrel): `CalendarTimeline`, `ScrollNavigator`, `ScrollNavigatorProps`, `SelectableSlot`, `SelectableSlotProps`, `TimeSlotProps`, `WeekAllDayRow`, `WeekAllDayRowProps`
-
-**Settings Components:**
-- `BadgeVariantSetting`, `BadgeVariantSettingProps`
-- `SlotDurationSetting`, `SlotDurationSettingProps`
-- `VisibleHoursSetting`, `VisibleHoursSettingProps`
-- `WorkingHoursSetting`, `WorkingHoursSettingProps`
-- `DEFAULT_WEEK_WORKING_HOURS`, `IDayWorkingHours`, `IWeekWorkingHours`, `TDayOfWeek`
-
-**Filter Components:**
-- `CalendarFilterSidebar`, `CalendarFilterSidebarProps`, `CalendarFilterSidebarLabels`
-- `ScheduleTypeFilter`, `ScheduleTypeFilterProps`, `IScheduleTypeOption`
-- `UserFilter`, `UserFilterProps`, `IUserOption`
-
-**Widget Components:**
-- `AgendaWidget`, `AgendaWidgetProps`
-- `AgendaDropdown`, `AgendaDropdownProps`
-
-**UI Primitives:**
-- `Button`, `ButtonProps`, `buttonVariants`
-- `Dialog`, `DialogClose`, `DialogContent`, `DialogDescription`, `DialogHeader`, `DialogTitle`, `DialogTrigger`
-- `Popover`, `PopoverAnchor`, `PopoverContent`, `PopoverTrigger`
-- `Sheet`, `SheetClose`, `SheetContent`, `SheetDescription`, `SheetHeader`, `SheetTitle`, `SheetTrigger`
-- `Tooltip`, `TooltipContent`, `TooltipProvider`, `TooltipTrigger`
-
-> **Internal-only UI** (not re-exported via public barrel, available via direct `./ui` import within the package): `Badge`, `BadgeProps`, `badgeVariants`, `DropdownMenu` family, `DialogOverlay`, `DialogPortal`, `Label`, `LabelProps`, `Select`, `SelectProps`, `SheetOverlay`, `SheetPortal`
-
-### From `src/core/`
-
-**Types** (60+ type exports) — see Section 4.
-
-**Context Providers:**
-- `InnoCalendarProvider`, `InnoCalendarProviderProps`
-- `CalendarProvider`, `CalendarProviderProps`
-- `SlotSelectionProvider`, `SlotSelectionProviderProps`
-- `DragDropProvider`, `DragDropProviderProps`
-- `IntegratedCalendarProvider` (alias), `IntegratedCalendarProviderProps` (alias)
-
-**Hooks** — see Section 14.
-
-**Constants** — see Section 19.
-
-**Utilities** — see Section 16. All re-exported via `export * from './utils'`.
-
-**Preferences:**
-- `IPreferences`, `IPreferencesConfig`, `IUsePreferencesReturn`
-- `TPreferenceMode`, `TPreferenceModes`, `TLockedPreferences`, `TPartialPreferences`, `TPreferenceKey`
-- `IVisibleHoursConfig`, `TWorkingHoursConfig`
-- `PREFERENCES_STORAGE_KEY`, default constants
-- `useAdvancedPreferences` (re-exported as alias)
-
-### From `src/presets/`
-
-- `DefaultCalendar`, `DefaultCalendarProps`
-- `TailwindCalendar`, `TailwindCalendarProps`
-- `RenderEventProps`, `RenderEventPopoverProps`, `RenderFilterSidebarProps`, `RenderHeaderProps`
-
-### From `src/lib/`
-
-- `cn` — `clsx(...inputs) | twMerge` className composer
-
----
-
-## 22. File Naming Conventions
-
-**All files and folders use kebab-case.**
-
-| Type | Pattern | Example |
-|---|---|---|
-| Components | `kebab-case.tsx` | `event-card.tsx` |
-| Hooks | `use-kebab-case.ts` | `use-calendar.ts` |
-| Context | `kebab-case.tsx` | `calendar-context.tsx` |
-| Types | `types.ts` | `types.ts` |
-| Utilities | `kebab-case.ts` | `date-utils.ts` |
-| Constants | `constants.ts` | `constants.ts` |
-| Barrel exports | `index.ts` | `index.ts` |
-| Styles | `kebab-case.css` | `calendar.css` |
-
----
-
-## 23. Styling Patterns
-
-### className Composition
-
-```tsx
-import { cn } from '../../lib/utils';
-
-<div className={cn('base-styles', isActive && 'active-styles', className)} />
-```
-
-### CVA for Variants
-
-```tsx
-import { cva, type VariantProps } from 'class-variance-authority';
-
-const buttonVariants = cva('base-classes', {
-  variants: {
-    variant: { default: '...', outline: '...' },
-    size: { sm: '...', md: '...' },
-  },
-  defaultVariants: { variant: 'default', size: 'md' },
-});
-```
-
----
-
-## 24. Biome Configuration
-
-From `biome.json` (schema v2.3.13):
-
-- **Formatter**: tabs, single quotes, JSX double quotes, 100 line width, trailing commas (ES5), semicolons always
-- **Linter**: recommended + `noUnusedVariables`, `noExplicitAny` (warn), `noNonNullAssertion` (warn), `useConst` (error), `noExcessiveCognitiveComplexity` (max 15, warn)
-- **Organize imports**: enabled via assist actions
-
-```bash
-npm run lint     # Check
-npm run format   # Auto-fix
-```
-
----
-
-## 25. State Synchronization Guide
-
-How state flows through the calendar and guidance for integrating with consumer projects.
-
-### Data Flow
-
-```
-Consumer App
-  └─ <InnoCalendar events={events} onEventDrop={...} ...>
-       └─ DragDropProvider (drag state, onEventDrop callback)
-           └─ InnoCalendarProvider (view, date, preferences, filtered events)
-               └─ SlotSelectionProvider (drag-to-select state)
-                   └─ InnerCalendar (renders header + active view)
-                       ├─ CalendarHeader (nav, view switcher, settings)
-                       └─ Active View (DayView, WeekView, TimelineView, etc.)
-                           └─ EventCard (popover/dialog/sheet/custom)
-```
-
-### Events: BYO Approach
-
-The package **never fetches data**. The consumer owns the events array and updates it:
-
-```tsx
-// Using React Query
-const { data: events } = useQuery(['events', dateRange], fetchEvents);
-const updateEvent = useMutation(api.updateEvent, {
-  onSuccess: () => queryClient.invalidateQueries(['events']),
-});
-
-<InnoCalendar
-  events={events ?? []}
-  onEventDrop={(result) => updateEvent.mutate({
-    id: result.event.id,
-    startDate: result.newStartDate,
-    endDate: result.newEndDate,
-    resourceId: result.newResourceId,
-  })}
-  onSlotSelect={(sel) => openCreateDialog(sel.startDate, sel.endDate)}
-/>
-```
-
-### Preferences Persistence
-
-Preferences (view, slot duration, badge variant, etc.) persist to `localStorage` by default. The key is configurable:
-
-```tsx
-<InnoCalendar
-  preferencesConfig={{
-    storageKey: 'my-app-calendar-prefs',  // default: 'inno-calendar-preferences'
-    defaults: { view: 'week', badgeVariant: 'colored' },
-    modes: { slotDuration: 'locked' },      // prevent user from changing
-    locked: { slotDuration: 30 },
-  }}
-/>
-```
-
-### Cross-Project State Patterns
-
-For apps that embed InnoCalendar (e.g., promosport-erp, generationimmo-erp):
-
-1. **URL Sync** — Sync view/date with URL params so back-button works:
-   ```tsx
-   <InnoCalendar
-     initialView={searchParams.get('view') as TCalendarView ?? 'week'}
-     initialDate={searchParams.get('date') ? new Date(searchParams.get('date')!) : undefined}
-     onViewChange={(v) => setSearchParams({ view: v })}
-     onDateChange={(d) => setSearchParams({ date: d.toISOString() })}
-   />
-   ```
-
-2. **Deep-linking events** — Navigate to a specific event from another page:
-   ```tsx
-   <InnoCalendar events={events} focusEventId={eventIdFromUrl} />
-   ```
-
-3. **External filter state** — The calendar's built-in filtering is opt-in. You can filter server-side and just pass filtered `events`:
-   ```tsx
-   const filteredEvents = useFilteredEvents(allEvents, externalFilters);
-   <InnoCalendar events={filteredEvents} />
-   ```
-
-4. **Imperative control** — Use ref for programmatic scroll/navigation:
-   ```tsx
-   const ref = useRef<ICalendarRefHandle>(null);
-   ref.current?.scrollToToday();
-   ref.current?.scrollToWorkingHours();
-   ref.current?.focusEvent(eventId);
-   ```
-
----
-
-## 26. Critical Rules
-
-1. **CalendarEvent must stay domain-agnostic** — no new top-level fields. Use `data?: TData` for domain data.
-2. **Deprecated fields stay** until next major version — never remove them prematurely.
-3. **Built-in components read `event.data` first**, then fall back to deprecated top-level fields.
-4. **Core module has zero external dependencies** — only React + native APIs.
-5. **Follow existing patterns** before inventing new ones (composition, slot props, CVA).
-6. **kebab-case everywhere** — files, folders, no exceptions.
-7. **JSDoc on every public export** — summary + `@param` + `@example` + `@default`.
-8. **Run `npm run typecheck`** before committing.
-9. **Update AGENT.md, README.md, and copilot-instructions.md** when public API changes.
-10. **Section separators** in type files: `// ============================================================================`
-11. **Performance**: `useMemo`, `useCallback`, memoize context values, stable keys.
-12. **Accessibility**: semantic HTML, ARIA attributes, keyboard navigation (Arrow keys, Enter/Space, Escape, Tab).
-13. **No inline objects/arrays in JSX props** — extract or memoize them.
-14. **Generic type propagation** — maintain `<TData>` through hooks, context, and component boundaries.
+# @innosolutions/inno-calendar — AI Agent Reference
+
+> **Version 1.0.58** | React 18+/19 | TypeScript 5.9 | Vite 7 library-mode  
+> Headless-first, fully customizable React calendar for enterprise applications.
+
+---
+
+## Table of Contents
+
+1. [What This Package Is](#1-what-this-package-is)
+2. [npm Scripts](#2-npm-scripts)
+3. [Package Exports](#3-package-exports)
+4. [Core Types](#4-core-types)
+5. [InnoCalendar Props](#5-innocalendar-props)
+6. [Slots System](#6-slots-system)
+7. [ClassNames API](#7-classnames-api)
+8. [EventCard & EventBlock](#8-eventcard--eventblock)
+9. [EventPopover Component](#9-eventpopover-component)
+10. [Preferences System](#10-preferences-system)
+11. [Widget Components](#11-widget-components)
+12. [Filter Components](#12-filter-components)
+13. [Settings Components](#13-settings-components)
+14. [Context & Hooks](#14-context--hooks)
+15. [Drag & Drop](#15-drag--drop)
+16. [Core Utilities](#16-core-utilities)
+17. [Presets](#17-presets)
+18. [CSS & Theming](#18-css--theming)
+19. [Constants](#19-constants)
+20. [Integration Guide](#20-integration-guide)
+21. [Full Export Catalog](#21-full-export-catalog)
+22. [File Naming Conventions](#22-file-naming-conventions)
+23. [Styling Patterns](#23-styling-patterns)
+24. [Biome Configuration](#24-biome-configuration)
+25. [State Synchronization Guide](#25-state-synchronization-guide)
+26. [Critical Rules](#26-critical-rules)
+
+---
+
+## 1. What This Package Is
+
+A **headless-first** React calendar component library — all view logic lives in hooks and contexts; every UI element is an optional, replaceable component.
+
+### Feature Set
+
+| Category | Features |
+|---|---|
+| **Views** | Day, Week, Month, Year, Agenda, Resource-Day, Resource-Week, Timeline-Day, Timeline-3Day, Timeline-Week |
+| **Interaction** | Drag-to-select (time & day mode), event click, slot click, drag-and-drop reposition, event resize |
+| **Customization** | 25+ component slots, 30+ classNames keys, render props, custom popover |
+| **Data** | Generic `CalendarEvent<TData>`, adapter pattern, BYO data fetching |
+| **Preferences** | localStorage persistence, locking, session mode, per-instance storage keys |
+| **Filtering** | Built-in schedule type filter, user/participant filter, text search |
+| **UI Extras** | Loading overlay, focus-event deep-linking, imperative ref API, settings panel, filter sidebar |
+| **Embeddable** | AgendaWidget (standalone card), AgendaDropdown (bell-icon notification panel) |
+| **Presets** | DefaultCalendar (styled), TailwindCalendar (Tailwind-optimized) |
+
+### Tech Stack
+
+| Layer | Technology |
+|---|---|
+| Runtime | React 18+/19, TypeScript 5.9 |
+| Build | Vite 7 (library mode), vite-plugin-dts |
+| Styling | TailwindCSS 4+, class-variance-authority (CVA), clsx, tailwind-merge |
+| UI Primitives | Radix UI (`@radix-ui/react-dialog` as direct dep; optional peer deps: popover, tooltip, dropdown-menu, scroll-area, select, avatar) |
+| Icons | lucide-react |
+| Date handling | Native Date API (no external date library) |
+| Linting | Biome 2.3 |
+
+---
+
+## 2. npm Scripts
+
+```bash
+npm run dev          # Vite dev mode
+npm run build        # Production build (Vite + dts declarations)
+npm run typecheck    # tsc --noEmit
+npm run lint         # Biome lint check
+npm run format       # Biome format
+```
+
+---
+
+## 3. Package Exports
+
+Defined in `package.json`:
+
+```jsonc
+{
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./utils": {
+      "types": "./dist/utils.d.ts",
+      "import": "./dist/utils.mjs",
+      "require": "./dist/utils.cjs"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.mjs",
+      "require": "./dist/core/index.cjs"
+    },
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "import": "./dist/components/index.mjs",
+      "require": "./dist/components/index.cjs"
+    },
+    "./presets": {
+      "types": "./dist/presets/index.d.ts",
+      "import": "./dist/presets/index.mjs",
+      "require": "./dist/presets/index.cjs"
+    },
+    "./lib": {
+      "types": "./dist/lib/index.d.ts",
+      "import": "./dist/lib/index.mjs",
+      "require": "./dist/lib/index.cjs"
+    },
+    "./styles": "./dist/styles/index.css",
+    "./styles.css": "./dist/styles/index.css"
+  }
+}
+```
+
+Consumer import patterns:
+
+```tsx
+// Components and types
+import { InnoCalendar, type CalendarEvent } from '@innosolutions/inno-calendar';
+// Core-only (headless hooks, types, utils)
+import { useCalendar, type TCalendarView } from '@innosolutions/inno-calendar/core';
+// Components only
+import { EventCard } from '@innosolutions/inno-calendar/components';
+// Presets only
+import { DefaultCalendar } from '@innosolutions/inno-calendar/presets';
+// Styles (required for built-in components — import in the page/component that renders the calendar)
+import '@innosolutions/inno-calendar/styles.css';
+```
+
+### TailwindCSS Source Directive (Required)
+
+For Tailwind to scan the package's class names, add a `@source` directive in your **global CSS file** (e.g., `app/style.css` or `globals.css`):
+
+```css
+/* app/style.css (or your global CSS entry point) */
+@source "../../node_modules/@innosolutions/inno-calendar/dist";
+```
+
+> **Why?** TailwindCSS 4+ only scans files under your project source by default. Without this directive, Tailwind will purge the calendar's utility classes and the components will render unstyled. Adjust the relative path based on your CSS file's location relative to `node_modules`.
+
+---
+
+## 4. Core Types
+
+All types are defined in `src/core/types.ts` (1449 lines).
+
+### CalendarEvent\<TData\>
+
+```typescript
+interface CalendarEvent<TData = Record<string, unknown>> extends IBaseEvent {
+  // Required (from IBaseEvent)
+  id: string;
+  title: ReactNode;       // String or JSX — plain strings are fully backwards compatible
+  startDate: Date;
+  endDate: Date;
+
+  // Optional visual/behavioral
+  description?: ReactNode; // String or JSX
+  color?: TEventColor;
+  hexColor?: string;
+  isAllDay?: boolean;
+  isMultiDay?: boolean;
+  isCanceled?: boolean;
+  isRecurring?: boolean;
+  resourceId?: string;
+
+  // Built-in filtering (optional)
+  scheduleTypeId?: number;
+  scheduleTypeName?: ReactNode; // String or JSX
+  participants?: ICalendarUser[];
+
+  // Consumer data bag (RECOMMENDED for all domain fields)
+  data?: TData;
+
+  // @deprecated — still functional, will be removed in next major
+  meetingTookPlace?: boolean;
+  isAccepted?: boolean;
+  companyId?: number;
+  cancelReason?: string | null;
+  scheduleTypeCode?: string;
+  opportunityId?: number;
+  propertyId?: number;
+  projectId?: number;
+  contactId?: number;
+  user?: ICalendarUser;
+}
+```
+
+#### ReactNode Props
+
+`title`, `description`, and `scheduleTypeName` accept `ReactNode`. Pass plain strings (backwards compatible) or custom JSX. Built-in search and `aria-label` use `reactNodeToText()` to extract plain text from JSX nodes automatically.
+
+#### data bag: ReactNode-compatible fields
+
+The following `event.data` fields are rendered as `ReactNode` in EventCard/EventBlock:
+
+| Field | Type | Description |
+|---|---|---|
+| `productName` | `ReactNode` | Product/activity name line |
+| `siteName` | `ReactNode` | Location site name |
+| `siteCity` | `ReactNode` | Location city |
+| `extendedProps` | `ReactNode[]` | Arbitrary custom lines rendered below productName |
+
+`extendedProps` renders each array entry as its own row. Visible on EventCard (full variant always, EventBlock when >= 45min). Also shown in tooltips.
+
+### IResource\<TData\>
+
+```typescript
+interface IResource<TData = Record<string, unknown>> {
+  id: string;
+  name: string;
+  title?: string;
+  avatar?: string;
+  color?: TEventColor | string;
+  data?: TData;
+}
+```
+
+### IScheduleType\<TData\>
+
+```typescript
+interface IScheduleType<TData = Record<string, unknown>> {
+  id: number;
+  name: string;
+  color?: TEventColor | string;
+  icon?: string;
+  isDefault?: boolean;
+  isActive?: boolean;
+  code?: string;
+  resourceKey?: string;
+  colorHex?: string;
+  defaultMinutes?: number;
+  data?: TData;
+}
+```
+
+### ICalendarUser\<TData\>
+
+```typescript
+interface ICalendarUser<TData = Record<string, unknown>> {
+  id: string;
+  name: string;
+  email?: string;
+  avatar?: string;
+  data?: TData;
+}
+```
+
+### ICalendarRefHandle
+
+Imperative handle exposed via `React.forwardRef` on `<InnoCalendar>`:
+
+```typescript
+interface ICalendarRefHandle {
+  scrollToToday: () => void;
+  scrollToWorkingHours: () => void;
+  getViewRect: () => DOMRect | null;
+  focusEvent: (eventId: string) => void;
+}
+```
+
+Usage:
+
+```tsx
+const ref = useRef<ICalendarRefHandle>(null);
+<InnoCalendar ref={ref} events={events} />
+// Later:
+ref.current?.scrollToToday();
+ref.current?.focusEvent('appointment-42');
+```
+
+### ICalendarPreferences
+
+```typescript
+interface ICalendarPreferences {
+  startHour: number;        // 0–23
+  endHour: number;          // 0–24
+  firstDayOfWeek: 0|1|2|3|4|5|6;
+  slotDuration: number;
+  showWeekends: boolean;
+  timeFormat: '12h' | '24h';
+  badgeVariant: TBadgeVariant;
+  showCanceledEvents: boolean;
+}
+```
+
+### View Types
+
+```typescript
+type TCalendarView =
+  | 'day' | 'week' | 'month' | 'year' | 'agenda'
+  | 'resource-day' | 'resource-week'
+  | 'timeline-day' | 'timeline-3day' | 'timeline-week';
+```
+
+### Other Key Types
+
+| Type | Purpose |
+|---|---|
+| `TEventColor` | `'blue'│'green'│'red'│'yellow'│'purple'│'orange'│'pink'│'teal'│'gray'│'indigo'` |
+| `TBadgeVariant` | `'dot'│'colored'│'mixed'` |
+| `TSlotDuration` | `15│30│60` |
+| `TWorkingHours` | `Record<number, IWorkingHoursDay>` (0=Sun..6=Sat) |
+| `ISelectionResult` | `{ startDate: Date; endDate: Date; resourceId?: string }` |
+| `IDropResult<TData>` | Drag-drop result with event, newStartDate, newEndDate, newResourceId |
+| `IDateRange` | `{ startDate: Date; endDate: Date }` |
+| `IEventPosition` | `{ top, height, left, width, zIndex }` |
+| `IPositionedEvent<TData>` | Event + IEventPosition + column info |
+| `ICalendarFilters` | `{ scheduleTypeIds?, resourceIds?, search?, showCanceled?, dateRange?, [key]: unknown }` |
+| `TSelectionMode` | `'time'│'day'` |
+| `TEventDetailMode` | `'popover'│'dialog'│'sheet'│'custom'` — controls how event details are shown |
+| `ICalendarHeaderConfig` | Object with 7 optional boolean keys controlling header section visibility |
+
+### Callback Types
+
+| Type | Signature |
+|---|---|
+| `TOnEventClick<TData>` | `(event, e?) => void` |
+| `TOnSlotSelect` | `(selection: ISelectionResult) => void` |
+| `TOnEventDrop<TData>` | `(event, newStart, newEnd, newResourceId?) => void` |
+| `TOnEventResize<TData>` | `(event, newStart, newEnd) => void` |
+| `TOnViewChange` | `(view: TCalendarView) => void` |
+| `TOnDateChange` | `(date: Date) => void` |
+| `TOnFiltersChange` | `(filters: ICalendarFilters) => void` |
+
+---
+
+## 5. InnoCalendar Props
+
+`<InnoCalendar>` is the primary entry point. It wraps `InnoCalendarProvider` + `SlotSelectionProvider` + `DragDropProvider` internally.
+
+```typescript
+interface InnoCalendarProps<TEventData> {
+  // === DATA ===
+  events: CalendarEvent<TEventData>[];
+  users?: ICalendarUser[];
+  scheduleTypes?: IScheduleType[];
+
+  // === INITIAL STATE ===
+  initialView?: TCalendarView;                    // default: 'week'
+  initialDate?: Date;                             // default: new Date()
+  initialSelectedUserId?: string | 'all';         // default: 'all'
+  initialScheduleTypeIds?: number[];
+  initialParticipantIds?: string[];
+  initialWorkingHoursView?: 'default' | 'enabled' | 'disabled';
+  initialSearchQuery?: string;
+
+  // === PREFERENCES ===
+  preferencesConfig?: IPreferencesConfig;
+
+  // === CALLBACKS ===
+  onEventClick?: (event: CalendarEvent<TEventData>) => void;
+  onSlotClick?: (date: Date, hour?: number) => void;
+  onSlotSelect?: (selection: ISelectionResult) => void;
+  onAddEvent?: () => void;
+  onEventDrop?: (result: IDropResult<TEventData>) => void;
+  onDateChange?: (date: Date, view: TCalendarView) => void;
+  onViewChange?: (view: TCalendarView) => void;
+
+  // === UI OPTIONS ===
+  className?: string;
+  showHeader?: boolean;                           // default: true
+  minSelectionMinutes?: number;                   // default: 30
+  showMoreMode?: 'dayView' | 'popover' | 'expand'; // default: 'expand'
+  isLoading?: boolean;                            // default: false
+
+  // === CUSTOM RENDERING ===
+  renderPopover?: (props: { event; onClose }) => ReactNode;
+  slots?: ICalendarSlots<TEventData>;
+  classNames?: ICalendarClassNames;
+
+  // === HEADER CONFIGURATION ===
+  headerConfig?: ICalendarHeaderConfig;            // fine-grained header visibility
+  // see ICalendarHeaderConfig below
+
+  // === EVENT DETAIL MODE ===
+  eventDetailMode?: TEventDetailMode;              // default: 'popover'
+  renderEventDetail?: (props: { event; onClose }) => ReactNode; // for 'custom' + override in dialog/sheet
+
+  // === CONTENT SLOTS ===
+  settingsContent?: ReactNode;
+  filterContent?: ReactNode;
+  headerActions?: ReactNode;
+
+  // === DEEP LINKING ===
+  focusEventId?: string | null;
+
+  // @deprecated — use showMoreMode instead
+  showMoreEventsInPopover?: boolean;
+}
+```
+
+#### ICalendarHeaderConfig
+
+Fine-grained visibility control for calendar header sections. Each key defaults to `true` when omitted.
+
+```typescript
+interface ICalendarHeaderConfig {
+  showToday?: boolean;           // Today button
+  showDateNavigator?: boolean;   // Prev/Next arrows + date label
+  showCalendarViews?: boolean;   // Day/Week/Month/Agenda dropdown
+  showResourceViews?: boolean;   // Timeline/Resource dropdown
+  showSettings?: boolean;        // Settings gear icon
+  showAddEvent?: boolean;        // "+" add event button
+  showFilters?: boolean;         // Filter row below header
+}
+```
+
+#### TEventDetailMode
+
+Controls how event details are displayed when clicking an event:
+
+- `'popover'` — Radix popover anchored to the event card (default)
+- `'dialog'` — Centered modal dialog overlay
+- `'sheet'` — Slide-in side panel from the right
+- `'custom'` — No built-in container; delegates to `renderEventDetail`
+
+```typescript
+type TEventDetailMode = 'popover' | 'dialog' | 'sheet' | 'custom';
+```
+
+### Ref Support
+
+`InnoCalendar` is wrapped with `forwardRef` and exposes `ICalendarRefHandle`:
+
+```tsx
+const calendarRef = useRef<ICalendarRefHandle>(null);
+<InnoCalendar ref={calendarRef} events={events} />
+```
+
+---
+
+## 6. Slots System
+
+Every visual region can be replaced via `slots`:
+
+```typescript
+interface ICalendarSlots<TEventData, TScheduleTypeData, TResourceData> {
+  // Structural
+  header?: ComponentType<IHeaderSlotProps>;
+  footer?: ComponentType<IFooterSlotProps<TEventData>>;
+  viewWrapper?: ComponentType<IViewWrapperSlotProps>;
+
+  // Day Cell (month/year views)
+  dayCell?: ComponentType<IDayCellSlotPropsExtended<TEventData>>;
+  dayCellHeader?: ComponentType<IDayCellAdornmentSlotProps<TEventData>>;
+  dayCellFooter?: ComponentType<IDayCellAdornmentSlotProps<TEventData>>;
+  dayCellStartAdornment?: ComponentType<IDayCellAdornmentSlotProps<TEventData>>;
+  dayCellEndAdornment?: ComponentType<IDayCellAdornmentSlotProps<TEventData>>;
+
+  // Time Grid (day/week views)
+  timeGutter?: ComponentType<ITimeGutterSlotProps>;
+  timeSlotBackground?: ComponentType<ITimeSlotBackgroundSlotProps>;
+  columnHeader?: ComponentType<IColumnHeaderSlotProps>;
+  currentTimeIndicator?: ComponentType<ICurrentTimeIndicatorSlotProps>;
+  multiDayBanner?: ComponentType<IMultiDayBannerSlotProps<TEventData>>;
+
+  // Events
+  eventCard?: ComponentType<IEventCardSlotProps<TEventData>>;
+  eventPopover?: ComponentType<IEventPopoverSlotProps<TEventData>>;
+
+  // Resource/Timeline
+  resourceHeader?: ComponentType<IResourceHeaderSlotProps<TResourceData>>;
+  rowHeader?: ComponentType<IRowHeaderSlotProps<TResourceData>>;
+
+  // Filters
+  filter?: ComponentType<IFilterSlotProps<TScheduleTypeData>>;
+
+  // Empty States
+  emptyCell?: ComponentType<IEmptyCellSlotProps>;
+  emptyState?: ComponentType<IEmptyStateSlotProps>;
+
+  // @deprecated
+  timeSlot?: ComponentType<ITimeSlotSlotProps>;
+}
+```
+
+### Slot Props Interfaces
+
+| Slot | Props Interface | Key Fields |
+|---|---|---|
+| `header` | `IHeaderSlotProps` | currentDate, view, onNavigate, onViewChange |
+| `footer` | `IFooterSlotProps` | view, currentDate, events |
+| `viewWrapper` | `IViewWrapperSlotProps` | view, children |
+| `dayCell` | `IDayCellSlotPropsExtended` | date, events, isToday, isCurrentMonth, isWeekend, view, children, onDayClick |
+| `dayCellHeader/Footer` | `IDayCellAdornmentSlotProps` | date, events, isToday, isCurrentMonth, isWeekend, view |
+| `timeGutter` | `ITimeGutterSlotProps` | hour, formattedLabel, isFirst |
+| `timeSlotBackground` | `ITimeSlotBackgroundSlotProps` | date, hour, minute, isWorkingHour, isToday |
+| `columnHeader` | `IColumnHeaderSlotProps` | date, isToday, onDayClick, columnIndex |
+| `currentTimeIndicator` | `ICurrentTimeIndicatorSlotProps` | currentTime, topOffset |
+| `multiDayBanner` | `IMultiDayBannerSlotProps` | events, rangeStart, onEventClick |
+| `eventCard` | `IEventCardSlotProps` | event, view, isCompact, onClick |
+| `eventPopover` | `IEventPopoverSlotProps` | event, onClose, onEdit, onDelete |
+| `resourceHeader` | `IResourceHeaderSlotProps` | resource |
+| `rowHeader` | `IRowHeaderSlotProps` | resource, rowIndex |
+| `filter` | `IFilterSlotProps` | scheduleTypes, filters, onFiltersChange |
+| `emptyCell` | `IEmptyCellSlotProps` | date, isToday |
+| `emptyState` | `IEmptyStateSlotProps` | view, dateRange |
+
+---
+
+## 7. ClassNames API
+
+`ICalendarClassNames` provides 34 CSS class override keys. Classes are merged with defaults via `cn()`.
+
+```typescript
+interface ICalendarClassNames {
+  // Structural
+  root?: string;
+  header?: string;
+  footer?: string;
+  viewContainer?: string;
+
+  // Month View
+  monthGrid?: string;
+  weekdayHeader?: string;
+  weekdayLabel?: string;
+  dayCell?: string;
+  dayCellToday?: string;
+  dayCellOutside?: string;
+  dayCellWeekend?: string;
+  dayCellNumber?: string;
+  dayCellContent?: string;
+  dayCellFooter?: string;
+
+  // Week/Day View
+  timeGutter?: string;
+  timeGutterLabel?: string;
+  timeSlot?: string;
+  timeSlotWorking?: string;
+  timeSlotNonWorking?: string;
+  columnHeader?: string;
+  columnHeaderToday?: string;
+  currentTimeIndicator?: string;
+  scrollContainer?: string;
+
+  // Events
+  eventCard?: string;
+  eventCardCompact?: string;
+  eventPopover?: string;
+  multiDayBanner?: string;
+  moreEventsIndicator?: string;
+
+  // Timeline
+  resourceHeader?: string;
+  resourceRow?: string;
+  timelineCell?: string;
+
+  // Agenda
+  agendaList?: string;
+  agendaDayGroup?: string;
+  agendaDayHeader?: string;
+}
+```
+
+---
+
+## 8. EventCard & EventBlock
+
+Located in `src/components/event/event-card.tsx`.
+
+### EventCard
+
+Full-size event card used in day/week/timeline views. Renders differently based on `badgeVariant`:
+
+| Badge Variant | Rendering |
+|---|---|
+| `'colored'` | Filled background with accent color, white/dark text |
+| `'dot'` | White background with colored left-border accent |
+| `'mixed'` | Light tinted background with colored left-border |
+
+Key props:
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `event` | `CalendarEvent<TData>` | required | Event data |
+| `variant` | `'full'\|'compact'\|'dot'` | `'full'` | Visual layout |
+| `badgeVariant` | `TBadgeVariant` | `'colored'` | Color treatment |
+| `onClick` | `(event) => void` | — | Click callback |
+| `showTime` | `boolean` | `true` | Show time display |
+| `showDescription` | `boolean` | `false` | Show event description |
+| `showParticipants` | `boolean` | `false` | Show participant avatars |
+| `disablePopover` | `boolean` | `false` | Skip built-in popover, fire `onClick` |
+| `renderPopover` | `(props) => ReactNode` | — | Custom content inside the default popover shell |
+| `enableDrag` | `boolean` | `false` | Enable HTML5 drag & drop |
+| `enablePageTransition` | `boolean` | `false` | Enable page transition animation |
+| `pageTransitionDuration` | `number` | `400` | Page transition duration in ms |
+| `eventDetailMode` | `TEventDetailMode` | `'popover'` | Container for event details: popover, dialog, sheet, custom |
+| `renderEventDetail` | `(props) => ReactNode` | — | Custom renderer for 'custom' mode; also inner content for dialog/sheet |
+| `style` | `CSSProperties` | — | Inline styles |
+| `className` | `string` | — | Additional CSS classes |
+
+Built-in cards display enrichment data read from `event.data` first, with fallback to deprecated top-level fields:
+
+```typescript
+// Runtime enrichment reading pattern:
+const eventData = event.data as Record<string, unknown> | undefined;
+const meetingTookPlace = (eventData?.meetingTookPlace as boolean) ?? event.meetingTookPlace ?? false;
+const productName = eventData?.productName as ReactNode | undefined;
+const siteName = eventData?.siteName as ReactNode | undefined;
+const siteCity = eventData?.siteCity as ReactNode | undefined;
+const extendedProps = eventData?.extendedProps as ReactNode[] | undefined;
+const nrParticipant = eventData?.nrParticipant as number | undefined;
+```
+
+### EventBlock
+
+Positioned event block for day/week time grid. Renders with absolute positioning inside the time column.
+
+### MultiDayEventBar
+
+Horizontal bar for multi-day/all-day events in the banner strip above day/week time grids.
+
+### Exports
+
+```typescript
+export { EventCard, type EventCardProps }
+export { EventBlock, type EventBlockProps }
+export { MultiDayEventBar, type MultiDayEventBarProps }
+export { getEventColorClasses }  // Utility: TEventColor → { bg, text, border }
+```
+
+---
+
+## 9. EventPopover Component
+
+Located in `src/components/event/event-popover.tsx` (~1400 lines).
+
+Full-featured event detail popover with action buttons, participant list, and domain data display.
+
+### Key Props
+
+```typescript
+interface EventPopoverProps<TData = Record<string, unknown>> {
+  event: IPopoverEvent<TData>;
+  children: ReactNode;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  isLoading?: boolean;
+
+  // Action callbacks
+  onEdit?: (event: IPopoverEvent<TData>) => void;
+  onDelete?: (event: IPopoverEvent<TData>) => void;
+  onCancel?: (event: IPopoverEvent<TData>) => void;
+  onAccept?: (event: IPopoverEvent<TData>) => void;
+  onDecline?: (event: IPopoverEvent<TData>) => void;
+  onConfirmMeeting?: (event: IPopoverEvent<TData>) => void;
+
+  // Permission flags
+  canEdit?: boolean;
+  canDelete?: boolean;
+  canCancel?: boolean;
+
+  // Current user state
+  isCurrentUserParticipant?: boolean;
+  isCurrentUserClient?: boolean;
+  currentUserAcceptStatus?: boolean | null;
+
+  // Loading states
+  isAcceptLoading?: boolean;
+  isDeclineLoading?: boolean;
+  isConfirmLoading?: boolean;
+  isDeleteLoading?: boolean;
+
+  // Render customization
+  renderParticipant?: (participant: IEventParticipant, index: number) => ReactNode;
+  renderHeaderActions?: (props: { onClose: () => void }) => ReactNode;
+  renderCancelReason?: (event: IPopoverEvent<TData>) => ReactNode;
+  renderDeleteConfirmation?: (props: {
+    onConfirm: () => void;
+    onCancel: () => void;
+    isLoading?: boolean;
+  }) => ReactNode;
+
+  // Formatting
+  formatDate?: (date: Date, format?: string) => string;
+  formatTimeRange?: (start: Date, end: Date) => string;
+
+  // Styling
+  className?: string;
+  width?: number;
+
+  // i18n labels
+  labels?: Partial<IEventPopoverLabels>;
+}
+```
+
+### IEventPopoverLabels
+
+All label strings are customizable for i18n:
+
+```typescript
+interface IEventPopoverLabels {
+  edit?: string;
+  delete?: string;
+  cancel?: string;
+  close?: string;
+  going?: string;
+  notGoing?: string;
+  confirmMeeting?: string;
+  completed?: string;
+  canceled?: string;
+  participants?: string;
+  guest?: string;
+  guests?: string;
+  confirmed?: string;
+  organizer?: string;
+  client?: string;
+  more?: string;
+  noDateProvided?: string;
+  eventNotFound?: string;
+  cancellationNote?: string;
+  canceledOn?: string;
+  acceptThisEvent?: string;
+  acceptAllEvents?: string;
+  deleteConfirmTitle?: string;
+  deleteConfirmDescription?: string;
+}
+```
+
+---
+
+## 10. Preferences System
+
+Located in `src/core/preferences/`.
+
+### IPreferencesConfig
+
+Passed via `<InnoCalendar preferencesConfig={...}>`:
+
+```typescript
+interface IPreferencesConfig {
+  modes?: TPreferenceModes;       // Per-key control mode
+  locked?: TLockedPreferences;    // Values for locked preferences
+  defaults?: TPartialPreferences; // Custom defaults
+  storageKey?: string;            // Custom localStorage key
+  disableStorage?: boolean;       // Disable localStorage entirely
+}
+```
+
+### Preference Modes
+
+| Mode | Behavior |
+|---|---|
+| `'user'` | User can modify, persisted to localStorage (default) |
+| `'locked'` | Developer-controlled, user cannot modify |
+| `'session'` | User can modify during session, not persisted |
+
+### IPreferences
+
+```typescript
+interface IPreferences {
+  view: TCalendarView;
+  badgeVariant: TBadgeVariant;
+  slotDuration: TSlotDuration;
+  visibleHours: IVisibleHoursConfig;         // { from: number; to: number }
+  workingHours: TWorkingHoursConfig;         // { [dayIndex]: { from, to } }
+  showWorkingHoursOnly: boolean;
+  showWeekends: boolean;
+  firstDayOfWeek: 0|1|2|3|4|5|6;
+}
+```
+
+### useCalendarPreferences Hook
+
+Returns `IUsePreferencesReturn`:
+
+```typescript
+interface IUsePreferencesReturn {
+  preferences: IPreferences;
+  setPreference: <K extends TPreferenceKey>(key: K, value: IPreferences[K]) => void;
+  setPreferences: (updates: TPartialPreferences) => void;
+  resetPreferences: () => void;
+  resetPreference: (key: TPreferenceKey) => void;
+  isLocked: (key: TPreferenceKey) => boolean;
+  isPersisted: (key: TPreferenceKey) => boolean;
+  getMode: (key: TPreferenceKey) => TPreferenceMode;
+}
+```
+
+### Example: Locking slot duration
+
+```tsx
+<InnoCalendar
+  events={events}
+  preferencesConfig={{
+    modes: { slotDuration: 'locked' },
+    locked: { slotDuration: 30 },
+  }}
+/>
+```
+
+---
+
+## 11. Widget Components
+
+Located in `src/components/widget/`.
+
+### AgendaWidget
+
+Embeddable agenda card for dashboards. Can work standalone or tap into an existing `InnoCalendarProvider`.
+
+```typescript
+interface AgendaWidgetProps {
+  events: CalendarEvent[];
+  maxItems?: number;
+  onEventClick?: (event: CalendarEvent) => void;
+  className?: string;
+  // ... additional display options
+}
+```
+
+### AgendaDropdown
+
+Bell-style notification dropdown for upcoming events:
+
+```typescript
+interface AgendaDropdownProps {
+  events: CalendarEvent[];
+  onEventClick?: (event: CalendarEvent) => void;
+  className?: string;
+  // ... trigger customization
+}
+```
+
+---
+
+## 12. Filter Components
+
+Located in `src/components/filters/`.
+
+### CalendarFilterSidebar
+
+Full filter panel with schedule type and user filters:
+
+```typescript
+interface CalendarFilterSidebarProps {
+  scheduleTypes: IScheduleTypeOption[];
+  users: IUserOption[];
+  labels?: CalendarFilterSidebarLabels;
+  // Controlled state or context-driven
+}
+```
+
+### ScheduleTypeFilter
+
+Standalone schedule type filter component with checkbox list.
+
+### UserFilter
+
+Standalone user/participant filter with avatar support.
+
+---
+
+## 13. Settings Components
+
+Located in `src/components/settings/`.
+
+| Component | Props | What It Controls |
+|---|---|---|
+| `BadgeVariantSetting` | `BadgeVariantSettingProps` | Dot / Colored / Mixed badge display |
+| `SlotDurationSetting` | `SlotDurationSettingProps` | 15 / 30 / 60 minute time slot granularity |
+| `VisibleHoursSetting` | `VisibleHoursSettingProps` | Start/end hour range for day/week views |
+| `WorkingHoursSetting` | `WorkingHoursSettingProps` | Per-day working hours with enable/disable toggle |
+
+All settings components read/write preferences through the preferences context.
+
+---
+
+## 14. Context & Hooks
+
+### Context Providers
+
+| Provider | Purpose |
+|---|---|
+| `InnoCalendarProvider` | Main state: events, date, view, filters, search, preferences, time config |
+| `CalendarProvider` | Lower-level provider (used by `Calendar` component) |
+| `SlotSelectionProvider` | Drag-to-select state management |
+| `DragDropProvider` | Event drag-and-drop state management |
+
+### Primary Hooks
+
+| Hook | Return Type | Purpose |
+|---|---|---|
+| `useInnoCalendar()` | `IInnoCalendarContext` | Full context access (events, view, date, filters, search, preferences) |
+| `useCalendarContext()` | `IInnoCalendarContext` | Alias for `useInnoCalendar` |
+| `useCalendar()` | `UseCalendarReturn` | Core calendar state (date, view, navigation, event helpers) |
+| `useSlotSelection()` | `UseSlotSelectionReturn` | Drag-to-select hook |
+| `useCalendarTimeConfig()` | `UseCalendarTimeConfigReturn` | Slot duration, visible hours, working hours |
+| `usePreferences()` | `UsePreferencesReturn` | Basic preferences hook |
+| `useAdvancedPreferences()` | `IUsePreferencesReturn` | Full preferences with locking support |
+| `useDragDrop()` | `IDragDropContext` | Drag-drop state and handlers |
+
+### Selective Context Hooks
+
+These read only a slice of the context for performance:
+
+| Hook | Returns |
+|---|---|
+| `useCalendarDate()` | Current date + navigation |
+| `useCalendarView()` | Current view + view change |
+| `useCalendarEvents()` | Events array + setEvents |
+| `useCalendarFilters()` | Filter state + setters |
+| `useCalendarPreferences()` | Preferences from context |
+| `useInnoCalendarView()` | View from InnoCalendar context |
+| `useInnoCalendarEvents()` | Events from InnoCalendar context |
+| `useInnoCalendarFilters()` | Filters from InnoCalendar context |
+| `useInnoCalendarTimeConfig()` | Time config from InnoCalendar context |
+
+### Optional Hooks (no throw if outside provider)
+
+| Hook | Returns |
+|---|---|
+| `useOptionalCalendar()` | `context │ undefined` |
+| `useOptionalCalendarContext()` | `context │ undefined` |
+| `useOptionalInnoCalendar()` | `context │ undefined` |
+| `useOptionalDragDrop()` | `context │ undefined` |
+| `useOptionalSlotSelection()` | `context │ undefined` |
+
+### Legacy Aliases (backward compat)
+
+| Alias | Maps To |
+|---|---|
+| `IntegratedCalendarProvider` | `InnoCalendarProvider` |
+| `useIntegratedCalendar()` | `useInnoCalendar()` |
+| `useIntegratedCalendarEvents()` | `useInnoCalendarEvents()` |
+| `useIntegratedCalendarFilters()` | `useInnoCalendarFilters()` |
+| `useIntegratedCalendarView()` | `useInnoCalendarView()` |
+| `useIntegratedCalendarTimeConfig()` | `useInnoCalendarTimeConfig()` |
+| `useOptionalIntegratedCalendar()` | `useOptionalInnoCalendar()` |
+| `IntegratedCalendar` | `InnoCalendar` |
+
+---
+
+## 15. Drag & Drop
+
+Located in `src/core/context/drag-drop-context.tsx`.
+
+### DragDropProvider
+
+Manages drag state for event repositioning. Wraps the calendar tree automatically when using `<InnoCalendar>`.
+
+```typescript
+interface IDragState<TData = Record<string, unknown>> {
+  event: CalendarEvent<TData>;
+  originalStartDate: Date;
+  originalEndDate: Date;
+  previewDate?: Date;              // current preview position
+  previewHour?: number;            // for time-based views
+  previewMinute?: number;
+  originalResourceId?: string;     // for resource/timeline views
+  targetResourceId?: string;       // current drag target resource
+}
+
+interface IDropResult<TData = Record<string, unknown>> {
+  event: CalendarEvent<TData>;
+  newStartDate: Date;
+  newEndDate: Date;                // maintains original duration
+  newResourceId?: string;          // set when dropped on different resource
+}
+
+interface IDragDropContext<TData = Record<string, unknown>> {
+  dragState: IDragState<TData> | null;
+  isDragging: boolean;
+  startDrag: (event: CalendarEvent<any>) => void;
+  updateDragPreview: (date: Date, hour?: number, minute?: number, resourceId?: string) => void;
+  endDrag: () => IDropResult<TData> | null;
+  cancelDrag: () => void;
+}
+```
+
+### Timeline / Resource View Drag & Drop
+
+`TimelineView` supports HTML5 drag & drop out of the box:
+
+- Events render with `enableDrag={true}` by default
+- Each resource row acts as a drop zone
+- Dragging across rows updates `targetResourceId` in the drag state
+- Dropping calls `endDrag()` which fires `onEventDrop` on `DragDropProvider`
+
+```tsx
+<InnoCalendar
+  events={events}
+  initialView="timeline-week"
+  onEventDrop={(result) => {
+    console.log(result.event.id, result.newStartDate, result.newResourceId);
+    // Update your backend
+  }}
+/>
+```
+
+---
+
+## 16. Core Utilities
+
+Located in `src/core/utils/`. All exported from `src/core/utils/index.ts`.
+
+### date-utils.ts
+
+Date manipulation using native Date API:
+
+| Function | Signature |
+|---|---|
+| `startOfDay` | `(date: Date) => Date` |
+| `endOfDay` | `(date: Date) => Date` |
+| `startOfWeek` | `(date: Date, weekStartsOn?: 0\|1\|2\|3\|4\|5\|6) => Date` |
+| `endOfWeek` | `(date: Date, weekStartsOn?: 0\|1\|2\|3\|4\|5\|6) => Date` |
+| `startOfMonth` | `(date: Date) => Date` |
+| `endOfMonth` | `(date: Date) => Date` |
+| `startOfYear` | `(date: Date) => Date` |
+| `endOfYear` | `(date: Date) => Date` |
+| `addDays` | `(date: Date, days: number) => Date` |
+| `subDays` | `(date: Date, days: number) => Date` |
+| `addWeeks` | `(date: Date, weeks: number) => Date` |
+| `subWeeks` | `(date: Date, weeks: number) => Date` |
+| `addMonths` | `(date: Date, months: number) => Date` |
+| `subMonths` | `(date: Date, months: number) => Date` |
+| `addYears` | `(date: Date, years: number) => Date` |
+| `subYears` | `(date: Date, years: number) => Date` |
+| `addHours` | `(date: Date, hours: number) => Date` |
+| `addMinutes` | `(date: Date, minutes: number) => Date` |
+| `setTime` | `(date: Date, hours: number, minutes?: number, seconds?: number) => Date` |
+| `getDecimalHours` | `(date: Date) => number` |
+| `isSameDay` | `(a: Date, b: Date) => boolean` |
+| `isSameWeek` | `(a: Date, b: Date, weekStartsOn?) => boolean` |
+| `isSameMonth` | `(a: Date, b: Date) => boolean` |
+| `isSameYear` | `(a: Date, b: Date) => boolean` |
+| `isToday` | `(date: Date) => boolean` |
+| `isWeekend` | `(date: Date) => boolean` |
+| `getDayOfWeek` | `(date: Date) => number` |
+| `isBefore` | `(a: Date, b: Date) => boolean` |
+| `isAfter` | `(a: Date, b: Date) => boolean` |
+| `isBetween` | `(date: Date, start: Date, end: Date) => boolean` |
+| `minDate` | `(dates: Date[]) => Date \| undefined` |
+| `maxDate` | `(dates: Date[]) => Date \| undefined` |
+| `differenceInMilliseconds` | `(a: Date, b: Date) => number` |
+| `differenceInMinutes` | `(a: Date, b: Date) => number` |
+| `differenceInHours` | `(a: Date, b: Date) => number` |
+| `differenceInDays` | `(a: Date, b: Date) => number` |
+| `getWeekDays` | `(date: Date, weekStartsOn?) => Date[]` |
+| `getWeekNumber` | `(date: Date) => number` |
+| `getDaysInMonth` | `(date: Date) => number` |
+| `getYearMonths` | `(year: number) => Date[]` |
+| `formatTime` | `(date: Date, format?: '12h'\|'24h') => string` |
+| `formatDateISO` | `(date: Date) => string` |
+| `formatHourLabel` | `(hour: number, format?: '12h'\|'24h') => string` |
+| `parseISO` | `(dateString: string) => Date` |
+| `eachDayOfInterval` | `(start: Date, end: Date) => Date[]` |
+| `eachHourOfInterval` | `(start: Date, end: Date) => Date[]` |
+| `getWeekdayNames` | `(locale?, format?) => string[]` |
+| `getMonthNames` | `(locale?, format?) => string[]` |
+| `getVisibleHoursArray` | `(visibleHours) => number[]` |
+| `generateMonthGrid` | `(date: Date, weekStartsOn?) => Array<{ date, isCurrentMonth, isWeekend }>` |
+| `detectAllDayEvent` | `(event) => boolean` |
+| `separateEventsByDuration` | `<TEvent>(events) => { singleDay, multiDay }` |
+| `getEventsInRange` | `<TEvent>(events, rangeStart, rangeEnd) => TEvent[]` |
+| `isWorkingHour` | `(date, hour, workingHours?) => boolean` |
+| `getWorkingHoursForDay` | `(date, workingHours) => { from, to } \| null` |
+
+### event-utils.ts
+
+Event filtering, sorting, classification, and color utilities:
+
+| Function | Purpose |
+|---|---|
+| `isMultiDayEvent` | Checks if event spans midnight |
+| `getEventsForDay` | Filters events that overlap a given day |
+| `getAllDayEvents` | Filters all-day events from array |
+| `getTimedEvents` | Filters timed (non-all-day) events |
+| `getMultiDayEvents` | Filters multi-day events |
+| `filterEventsByDateRange` | Filters events overlapping a date range |
+| `filterEventsByScheduleType` | Client-side schedule type filter |
+| `filterEventsByResource` | Client-side resource filter |
+| `filterEventsBySearch` | Text search across event fields |
+| `filterOutCanceled` | Remove canceled events |
+| `applyEventFilters` | Composite filter applying multiple criteria |
+| `sortEventsByStart` | Sort by start date |
+| `sortEventsByEnd` | Sort by end date |
+| `sortEventsByDuration` | Sort by event duration |
+| `groupEventsByDate` | Groups events by calendar date |
+| `groupEventsByScheduleType` | Groups events by schedule type |
+| `groupEventsByResource` | Groups events by resourceId |
+| `getEventDurationMinutes` | Returns event duration in minutes |
+| `getEventColor` | Resolves event color with fallback |
+| `formatEventTimeDisplay` | Formats event time for display |
+
+### grid-utils.ts
+
+Grid layout calculations, view navigation, and cell generation:
+
+| Function | Purpose |
+|---|---|
+| `getViewDateRange` | Returns date range for any view |
+| `navigateNext` | Advance date by one view step |
+| `navigatePrev` | Go back one view step |
+| `navigateToday` | Returns today's Date |
+| `generateMonthCells` | Creates cell array for month grid |
+| `generateWeekCells` | Creates cell array for week view |
+| `generateYearCells` | Creates cell array for year view |
+| `generateTimeSlots` | Creates time slot array for given hour range and slot duration |
+| `generateHourLabels` | Creates hour label array for gutter |
+| `getViewTitle` | Formatted title string for current view + date |
+
+### react-node-utils.ts
+
+Utility for extracting plain text from ReactNode trees:
+
+| Function | Signature | Purpose |
+|---|---|---|
+| `reactNodeToText` | `(node: ReactNode) => string` | Recursively extracts plain text from any ReactNode. Used internally for search, aria-labels, and string operations on ReactNode-typed fields. |
+
+```typescript
+reactNodeToText("hello")                              // "hello"
+reactNodeToText(<span>hello <b>world</b></span>)      // "hello world"
+reactNodeToText(<><MapPinIcon /> BELGIUM</>)           // " BELGIUM"
+reactNodeToText(null)                                  // ""
+reactNodeToText(42)                                    // "42"
+```
+
+### position-utils.ts
+
+Event overlap and positioning:
+
+| Function | Purpose |
+|---|---|
+| `calculateEventPosition` | Computes position for a single event in a column |
+| `calculateOverlappingPositions` | Computes non-overlapping layout for multiple events |
+| `yToTime` | Converts vertical pixel offset to Date |
+| `timeToY` | Converts Date to vertical pixel offset |
+| `eventsOverlap` | Checks if two events overlap in time |
+| `getOverlappingGroups` | Groups events that share time ranges |
+| `calculateSelectionOverlay` | Computes drag selection overlay dimensions |
+
+---
+
+## 17. Presets
+
+Located in `src/presets/`.
+
+### DefaultCalendar
+
+Pre-configured calendar with sensible defaults:
+
+```tsx
+import { DefaultCalendar } from '@innosolutions/inno-calendar';
+
+<DefaultCalendar events={events} />
+```
+
+### TailwindCalendar
+
+Tailwind-optimized calendar preset with carefully chosen utility classes:
+
+```tsx
+import { TailwindCalendar } from '@innosolutions/inno-calendar';
+
+<TailwindCalendar events={events} />
+```
+
+---
+
+## 18. CSS & Theming
+
+Styles are in `src/styles/calendar.css` (imported via `@innosolutions/inno-calendar/styles.css`).
+
+### Consumer Setup (Required)
+
+**1. Global CSS — TailwindCSS source directive:**
+
+```css
+/* app/style.css or globals.css */
+@source "../../node_modules/@innosolutions/inno-calendar/dist";
+```
+
+**2. Page/component — style import:**
+
+```tsx
+// In the file where you render <InnoCalendar> (e.g., agenda.tsx)
+import '@innosolutions/inno-calendar/styles.css';
+```
+
+### CSS Custom Properties
+
+```css
+:root {
+  /* Surfaces */
+  --inno-border-color: #e5e7eb;
+  --inno-background: #ffffff;
+  --inno-foreground: #111827;
+  --inno-muted: #f3f4f6;
+  --inno-muted-foreground: #6b7280;
+  --inno-primary: #3b82f6;
+  --inno-primary-foreground: #ffffff;
+
+  /* Event Colors */
+  --inno-event-blue: #3b82f6;
+  --inno-event-green: #22c55e;
+  --inno-event-red: #ef4444;
+  --inno-event-yellow: #eab308;
+  --inno-event-purple: #a855f7;
+  --inno-event-orange: #f97316;
+  --inno-event-pink: #ec4899;
+  --inno-event-teal: #14b8a6;
+  --inno-event-gray: #6b7280;
+  --inno-event-indigo: #6366f1;
+
+  /* Layout */
+  --inno-hour-height: 96px;
+  --inno-header-height: 56px;
+  --inno-sidebar-width: 200px;
+}
+```
+
+### Dark Mode
+
+Override with `.dark` class:
+
+```css
+.dark {
+  --inno-border-color: #374151;
+  --inno-background: #111827;
+  --inno-foreground: #f9fafb;
+  --inno-muted: #1f2937;
+  --inno-muted-foreground: #9ca3af;
+}
+```
+
+### Key CSS Classes
+
+| Class | Purpose |
+|---|---|
+| `.inno-calendar-root` | Root container with scrollbar styles |
+| `.inno-calendar-loading-overlay` | Translucent loading indicator overlay |
+| `.inno-calendar-spinner` | Spinner animation |
+| `.inno-calendar-selection` | Drag-to-select overlay |
+| `.inno-calendar-current-time` | Red current time indicator |
+| `.inno-calendar-event` | Event card styling |
+| `.inno-calendar-event-canceled` | Canceled event styling |
+| `.inno-calendar-disabled-hour` | Disabled/non-working hours pattern |
+| `.inno-calendar-no-scrollbar` | Hide scrollbar utility |
+| `.inno-scroll-nav` | D-pad controller container |
+| `.inno-scroll-nav-btn` | Directional buttons (up, down, left, right) |
+| `.ic-expansion-backdrop` | Backdrop for expanded month cell |
+| `.ic-expansion-panel` | Expanded events panel in month view |
+
+---
+
+## 19. Constants
+
+Located in `src/core/constants.ts`.
+
+### View List
+
+```typescript
+const CALENDAR_VIEWS: TCalendarView[] = [
+  'day', 'week', 'month', 'year', 'agenda',
+  'resource-day', 'resource-week',
+  'timeline-day', 'timeline-week'
+];
+```
+
+### Default Preferences
+
+```typescript
+const DEFAULT_PREFERENCES: ICalendarPreferences = {
+  startHour: 8,
+  endHour: 18,
+  firstDayOfWeek: 1,  // Monday
+  slotDuration: 30,
+  showWeekends: true,
+  timeFormat: '24h',
+  badgeVariant: 'colored',
+  showCanceledEvents: false,
+};
+```
+
+### Color Palette
+
+```typescript
+const EVENT_COLORS: Record<TEventColor, string> = {
+  blue: '#3b82f6', green: '#22c55e', red: '#ef4444',
+  yellow: '#eab308', purple: '#a855f7', orange: '#f97316',
+  pink: '#ec4899', teal: '#14b8a6', gray: '#6b7280', indigo: '#6366f1',
+};
+
+const EVENT_COLOR_CLASSES: Record<TEventColor, { bg, text, border }>;
+const HEX_TO_EVENT_COLOR: Record<string, TEventColor>;
+```
+
+### Grid Constants
+
+| Constant | Value |
+|---|---|
+| `DEFAULT_HOUR_HEIGHT` | 64px |
+| `DEFAULT_SLOT_HEIGHT` | 32px |
+| `DEFAULT_HEADER_HEIGHT` | 56px |
+| `DEFAULT_RESOURCE_WIDTH` | 200px |
+| `MIN_EVENT_HEIGHT` | 20px |
+| `HOURS_IN_DAY` | 24 |
+| `MINUTES_IN_HOUR` | 60 |
+| `MS_PER_MINUTE` | 60000 |
+| `MS_PER_HOUR` | 3600000 |
+| `MS_PER_DAY` | 86400000 |
+
+### Time Defaults
+
+```typescript
+const DEFAULT_VISIBLE_HOURS: IVisibleHours = { startHour: 0, endHour: 24 };
+const DEFAULT_BUSINESS_HOURS: IVisibleHours = { startHour: 8, endHour: 18 };
+```
+
+---
+
+## 20. Integration Guide
+
+### Minimal Setup
+
+```tsx
+import { InnoCalendar, type CalendarEvent } from '@innosolutions/inno-calendar';
+import '@innosolutions/inno-calendar/styles.css';
+
+const events: CalendarEvent[] = [
+  {
+    id: '1',
+    title: 'Team Meeting',
+    startDate: new Date('2026-02-12T09:00:00'),
+    endDate: new Date('2026-02-12T10:00:00'),
+    color: 'blue',
+  },
+];
+
+function App() {
+  return (
+    <InnoCalendar
+      events={events}
+      onEventClick={(event) => console.log('Clicked:', event.title)}
+      onSlotSelect={(sel) => console.log('Selected:', sel.startDate, sel.endDate)}
+    />
+  );
+}
+```
+
+### With Custom Popover
+
+```tsx
+<InnoCalendar
+  events={events}
+  renderPopover={({ event, onClose }) => (
+    <div className="p-4 space-y-2">
+      <h3 className="font-bold">{event.title}</h3>
+      <p>{event.description}</p>
+      <button onClick={onClose}>Close</button>
+    </div>
+  )}
+/>
+```
+
+### With Loading State
+
+```tsx
+const [isLoading, setIsLoading] = useState(false);
+
+<InnoCalendar
+  events={events}
+  isLoading={isLoading}
+  onDateChange={async (date, view) => {
+    setIsLoading(true);
+    const newEvents = await fetchEvents(date, view);
+    setEvents(newEvents);
+    setIsLoading(false);
+  }}
+/>
+```
+
+### With Deep-Linking
+
+```tsx
+// URL: /calendar?eventId=appointment-42
+const eventId = useSearchParams().get('eventId');
+
+<InnoCalendar events={events} focusEventId={eventId} />
+```
+
+### Imperative Control
+
+```tsx
+const ref = useRef<ICalendarRefHandle>(null);
+
+<Button onClick={() => ref.current?.scrollToWorkingHours()}>
+  Go to Work Hours
+</Button>
+
+<InnoCalendar ref={ref} events={events} />
+```
+
+### Resource / Timeline Views
+
+```tsx
+const resources: IResource[] = [
+  { id: 'room-a', name: 'Meeting Room A', color: 'blue' },
+  { id: 'room-b', name: 'Board Room', color: 'green' },
+];
+
+<InnoCalendar
+  events={events}
+  initialView="timeline-week"
+  onEventDrop={(result) => {
+    // result.newResourceId is set when event is dragged to a different row
+    api.updateEvent(result.event.id, {
+      startDate: result.newStartDate,
+      endDate: result.newEndDate,
+      resourceId: result.newResourceId,
+    });
+  }}
+/>
+```
+
+### Header Configuration
+
+```tsx
+// Hide resource views and settings — only show calendar views + Today + navigation
+<InnoCalendar
+  events={events}
+  headerConfig={{
+    showResourceViews: false,
+    showSettings: false,
+    showFilters: false,
+  }}
+/>
+```
+
+### Event Detail Mode
+
+```tsx
+// Show event details in a slide-in sheet instead of default popover
+<InnoCalendar
+  events={events}
+  eventDetailMode="sheet"
+/>
+
+// Fully custom event detail container
+<InnoCalendar
+  events={events}
+  eventDetailMode="custom"
+  renderEventDetail={({ event, onClose }) => (
+    <MyCustomDrawer event={event} onClose={onClose} />
+  )}
+/>
+```
+
+### With Preferences Locking
+
+```tsx
+<InnoCalendar
+  events={events}
+  preferencesConfig={{
+    defaults: { view: 'month', badgeVariant: 'dot' },
+    modes: {
+      slotDuration: 'locked',
+      showWeekends: 'locked',
+    },
+    locked: {
+      slotDuration: 30,
+      showWeekends: false,
+    },
+  }}
+/>
+```
+
+### Widget Embedding
+
+```tsx
+import { AgendaWidget, AgendaDropdown } from '@innosolutions/inno-calendar';
+
+// Dashboard card
+<AgendaWidget events={todayEvents} onEventClick={openEvent} />
+
+// Navbar notification bell
+<AgendaDropdown events={upcomingEvents} onEventClick={openEvent} />
+```
+
+### Custom Slot Example
+
+```tsx
+<InnoCalendar
+  events={events}
+  slots={{
+    dayCellFooter: ({ date, events }) => (
+      <div className="text-xs text-muted-foreground border-t mt-1 pt-1">
+        {events.length} events
+      </div>
+    ),
+    columnHeader: ({ date, isToday, onDayClick }) => (
+      <button
+        className={cn('text-center', isToday && 'font-bold text-primary')}
+        onClick={() => onDayClick?.(date)}
+      >
+        {date.toLocaleDateString(undefined, { weekday: 'short', day: 'numeric' })}
+      </button>
+    ),
+  }}
+/>
+```
+
+---
+
+## 21. Full Export Catalog
+
+### From `src/components/`
+
+**Main Components:**
+- `InnoCalendar`, `InnoCalendarProps`
+- `Calendar`, `CalendarProps`
+- `IntegratedCalendar` (alias), `IntegratedCalendarProps` (alias)
+
+**Event Components:**
+- `EventCard`, `EventCardProps`
+- `EventBlock`, `EventBlockProps`
+- `EventPopover`, `EventPopoverProps`, `IEventPopoverLabels`, `IPopoverEvent`, `IEventParticipant`
+- `MultiDayEventBar`, `MultiDayEventBarProps`
+- `getEventColorClasses`
+
+**Header Components:**
+- `CalendarHeader`, `CalendarHeaderProps`
+- `DateNavigator`, `DateNavigatorProps`
+- `TodayButton`, `TodayButtonProps`
+
+**View Components:**
+- `DayView`, `DayViewProps`
+- `WeekView`, `WeekViewProps`
+- `MonthView`, `MonthViewProps`
+- `YearView`, `YearViewProps`
+- `AgendaView`, `AgendaViewProps`
+- `TimelineView`, `TimelineViewProps`
+- `DayEventsExpansion`, `DayEventsExpansionProps`
+
+**Primitive Components:**
+- `DaySlot`, `DaySlotProps`
+- `MultiDayBanner`, `MultiDayBannerProps`
+- `TimeSlot`
+
+> **Internal-only Primitives** (not re-exported via public barrel): `CalendarTimeline`, `ScrollNavigator`, `ScrollNavigatorProps`, `SelectableSlot`, `SelectableSlotProps`, `TimeSlotProps`, `WeekAllDayRow`, `WeekAllDayRowProps`
+
+**Settings Components:**
+- `BadgeVariantSetting`, `BadgeVariantSettingProps`
+- `SlotDurationSetting`, `SlotDurationSettingProps`
+- `VisibleHoursSetting`, `VisibleHoursSettingProps`
+- `WorkingHoursSetting`, `WorkingHoursSettingProps`
+- `DEFAULT_WEEK_WORKING_HOURS`, `IDayWorkingHours`, `IWeekWorkingHours`, `TDayOfWeek`
+
+**Filter Components:**
+- `CalendarFilterSidebar`, `CalendarFilterSidebarProps`, `CalendarFilterSidebarLabels`
+- `ScheduleTypeFilter`, `ScheduleTypeFilterProps`, `IScheduleTypeOption`
+- `UserFilter`, `UserFilterProps`, `IUserOption`
+
+**Widget Components:**
+- `AgendaWidget`, `AgendaWidgetProps`
+- `AgendaDropdown`, `AgendaDropdownProps`
+
+**UI Primitives:**
+- `Button`, `ButtonProps`, `buttonVariants`
+- `Dialog`, `DialogClose`, `DialogContent`, `DialogDescription`, `DialogHeader`, `DialogTitle`, `DialogTrigger`
+- `Popover`, `PopoverAnchor`, `PopoverContent`, `PopoverTrigger`
+- `Sheet`, `SheetClose`, `SheetContent`, `SheetDescription`, `SheetHeader`, `SheetTitle`, `SheetTrigger`
+- `Tooltip`, `TooltipContent`, `TooltipProvider`, `TooltipTrigger`
+
+> **Internal-only UI** (not re-exported via public barrel, available via direct `./ui` import within the package): `Badge`, `BadgeProps`, `badgeVariants`, `DropdownMenu` family, `DialogOverlay`, `DialogPortal`, `Label`, `LabelProps`, `Select`, `SelectProps`, `SheetOverlay`, `SheetPortal`
+
+### From `src/core/`
+
+**Types** (60+ type exports) — see Section 4.
+
+**Context Providers:**
+- `InnoCalendarProvider`, `InnoCalendarProviderProps`
+- `CalendarProvider`, `CalendarProviderProps`
+- `SlotSelectionProvider`, `SlotSelectionProviderProps`
+- `DragDropProvider`, `DragDropProviderProps`
+- `IntegratedCalendarProvider` (alias), `IntegratedCalendarProviderProps` (alias)
+
+**Hooks** — see Section 14.
+
+**Constants** — see Section 19.
+
+**Utilities** — see Section 16. All re-exported via `export * from './utils'`.
+
+**Preferences:**
+- `IPreferences`, `IPreferencesConfig`, `IUsePreferencesReturn`
+- `TPreferenceMode`, `TPreferenceModes`, `TLockedPreferences`, `TPartialPreferences`, `TPreferenceKey`
+- `IVisibleHoursConfig`, `TWorkingHoursConfig`
+- `PREFERENCES_STORAGE_KEY`, default constants
+- `useAdvancedPreferences` (re-exported as alias)
+
+### From `src/presets/`
+
+- `DefaultCalendar`, `DefaultCalendarProps`
+- `TailwindCalendar`, `TailwindCalendarProps`
+- `RenderEventProps`, `RenderEventPopoverProps`, `RenderFilterSidebarProps`, `RenderHeaderProps`
+
+### From `src/lib/`
+
+- `cn` — `clsx(...inputs) | twMerge` className composer
+
+---
+
+## 22. File Naming Conventions
+
+**All files and folders use kebab-case.**
+
+| Type | Pattern | Example |
+|---|---|---|
+| Components | `kebab-case.tsx` | `event-card.tsx` |
+| Hooks | `use-kebab-case.ts` | `use-calendar.ts` |
+| Context | `kebab-case.tsx` | `calendar-context.tsx` |
+| Types | `types.ts` | `types.ts` |
+| Utilities | `kebab-case.ts` | `date-utils.ts` |
+| Constants | `constants.ts` | `constants.ts` |
+| Barrel exports | `index.ts` | `index.ts` |
+| Styles | `kebab-case.css` | `calendar.css` |
+
+---
+
+## 23. Styling Patterns
+
+### className Composition
+
+```tsx
+import { cn } from '../../lib/utils';
+
+<div className={cn('base-styles', isActive && 'active-styles', className)} />
+```
+
+### CVA for Variants
+
+```tsx
+import { cva, type VariantProps } from 'class-variance-authority';
+
+const buttonVariants = cva('base-classes', {
+  variants: {
+    variant: { default: '...', outline: '...' },
+    size: { sm: '...', md: '...' },
+  },
+  defaultVariants: { variant: 'default', size: 'md' },
+});
+```
+
+---
+
+## 24. Biome Configuration
+
+From `biome.json` (schema v2.3.13):
+
+- **Formatter**: tabs, single quotes, JSX double quotes, 100 line width, trailing commas (ES5), semicolons always
+- **Linter**: recommended + `noUnusedVariables`, `noExplicitAny` (warn), `noNonNullAssertion` (warn), `useConst` (error), `noExcessiveCognitiveComplexity` (max 15, warn)
+- **Organize imports**: enabled via assist actions
+
+```bash
+npm run lint     # Check
+npm run format   # Auto-fix
+```
+
+---
+
+## 25. State Synchronization Guide
+
+How state flows through the calendar and guidance for integrating with consumer projects.
+
+### Data Flow
+
+```
+Consumer App
+  └─ <InnoCalendar events={events} onEventDrop={...} ...>
+       └─ DragDropProvider (drag state, onEventDrop callback)
+           └─ InnoCalendarProvider (view, date, preferences, filtered events)
+               └─ SlotSelectionProvider (drag-to-select state)
+                   └─ InnerCalendar (renders header + active view)
+                       ├─ CalendarHeader (nav, view switcher, settings)
+                       └─ Active View (DayView, WeekView, TimelineView, etc.)
+                           └─ EventCard (popover/dialog/sheet/custom)
+```
+
+### Events: BYO Approach
+
+The package **never fetches data**. The consumer owns the events array and updates it:
+
+```tsx
+// Using React Query
+const { data: events } = useQuery(['events', dateRange], fetchEvents);
+const updateEvent = useMutation(api.updateEvent, {
+  onSuccess: () => queryClient.invalidateQueries(['events']),
+});
+
+<InnoCalendar
+  events={events ?? []}
+  onEventDrop={(result) => updateEvent.mutate({
+    id: result.event.id,
+    startDate: result.newStartDate,
+    endDate: result.newEndDate,
+    resourceId: result.newResourceId,
+  })}
+  onSlotSelect={(sel) => openCreateDialog(sel.startDate, sel.endDate)}
+/>
+```
+
+### Preferences Persistence
+
+Preferences (view, slot duration, badge variant, etc.) persist to `localStorage` by default. The key is configurable:
+
+```tsx
+<InnoCalendar
+  preferencesConfig={{
+    storageKey: 'my-app-calendar-prefs',  // default: 'inno-calendar-preferences'
+    defaults: { view: 'week', badgeVariant: 'colored' },
+    modes: { slotDuration: 'locked' },      // prevent user from changing
+    locked: { slotDuration: 30 },
+  }}
+/>
+```
+
+### Cross-Project State Patterns
+
+For apps that embed InnoCalendar (e.g., promosport-erp, generationimmo-erp):
+
+1. **URL Sync** — Sync view/date with URL params so back-button works:
+   ```tsx
+   <InnoCalendar
+     initialView={searchParams.get('view') as TCalendarView ?? 'week'}
+     initialDate={searchParams.get('date') ? new Date(searchParams.get('date')!) : undefined}
+     onViewChange={(v) => setSearchParams({ view: v })}
+     onDateChange={(d) => setSearchParams({ date: d.toISOString() })}
+   />
+   ```
+
+2. **Deep-linking events** — Navigate to a specific event from another page:
+   ```tsx
+   <InnoCalendar events={events} focusEventId={eventIdFromUrl} />
+   ```
+
+3. **External filter state** — The calendar's built-in filtering is opt-in. You can filter server-side and just pass filtered `events`:
+   ```tsx
+   const filteredEvents = useFilteredEvents(allEvents, externalFilters);
+   <InnoCalendar events={filteredEvents} />
+   ```
+
+4. **Imperative control** — Use ref for programmatic scroll/navigation:
+   ```tsx
+   const ref = useRef<ICalendarRefHandle>(null);
+   ref.current?.scrollToToday();
+   ref.current?.scrollToWorkingHours();
+   ref.current?.focusEvent(eventId);
+   ```
+
+---
+
+## 26. Critical Rules
+
+1. **CalendarEvent must stay domain-agnostic** — no new top-level fields. Use `data?: TData` for domain data.
+2. **Deprecated fields stay** until next major version — never remove them prematurely.
+3. **Built-in components read `event.data` first**, then fall back to deprecated top-level fields.
+4. **Core module has zero external dependencies** — only React + native APIs.
+5. **Follow existing patterns** before inventing new ones (composition, slot props, CVA).
+6. **kebab-case everywhere** — files, folders, no exceptions.
+7. **JSDoc on every public export** — summary + `@param` + `@example` + `@default`.
+8. **Run `npm run typecheck`** before committing.
+9. **Update AGENT.md, README.md, and copilot-instructions.md** when public API changes.
+10. **Section separators** in type files: `// ============================================================================`
+11. **Performance**: `useMemo`, `useCallback`, memoize context values, stable keys.
+12. **Accessibility**: semantic HTML, ARIA attributes, keyboard navigation (Arrow keys, Enter/Space, Escape, Tab).
+13. **No inline objects/arrays in JSX props** — extract or memoize them.
+14. **Generic type propagation** — maintain `<TData>` through hooks, context, and component boundaries.