@innosolutions/inno-calendar 1.0.58 → 1.0.60

package/AGENT.md

@@ -1,1610 +1,1756 @@
-# @innosolutions/inno-calendar — AI Agent Reference
-
-> **Version 1.0.49** | 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 (optional peer deps: popover, tooltip, dropdown-menu, dialog, scroll-area, select, avatar) |
-| Icons | lucide-react |
-| Date handling | Native Date API (no external date library) |
-| Linting | Biome 2.2 |
-
----
-
-## 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.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs",
-      "types": "./dist/index.d.ts"
-    },
-    "./styles": "./dist/styles/index.css"
-  }
-}
-```
-
-Consumer import patterns:
-
-```tsx
-// Components and types
-import { InnoCalendar, type CalendarEvent } from '@innosolutions/inno-calendar';
-// Styles (required for built-in components)
-import '@innosolutions/inno-calendar/styles';
-```
-
----
-
-## 4. Core Types
-
-All types are defined in `src/core/types.ts` (1473 lines).
-
-### CalendarEvent\<TData\>
-
-```typescript
-interface CalendarEvent<TData = Record<string, unknown>> extends IBaseEvent {
-  // Required (from IBaseEvent)
-  id: string;
-  title: string;
-  startDate: Date;
-  endDate: Date;
-
-  // Optional visual/behavioral
-  description?: string;
-  color?: TEventColor;
-  hexColor?: string;
-  isAllDay?: boolean;
-  isMultiDay?: boolean;
-  isCanceled?: boolean;
-  isRecurring?: boolean;
-  resourceId?: string;
-
-  // Built-in filtering (optional)
-  scheduleTypeId?: number;
-  scheduleTypeName?: string;
-  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;
-}
-```
-
-### 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 30+ 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 |
-| `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 |
-| `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 |
-
-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 typeName = eventData?.typeName as string | undefined;
-const siteName = eventData?.siteName as string | undefined;
-const nrParticipant = eventData?.nrParticipant as number | undefined;
-```
-
-### EventBlock
-
-Compact event chip for month/year view cells. Displays title with optional color dot.
-
-### 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` (1519 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: CalendarEvent<TData>;
-  onClose: () => void;
-
-  // Action callbacks
-  onEdit?: () => void;
-  onDelete?: () => void;
-  onCancel?: () => void;
-  onAccept?: () => void;
-  onDecline?: () => void;
-  onConfirmMeeting?: () => void;
-
-  // Permission flags
-  canEdit?: boolean;
-  canDelete?: boolean;
-  canCancel?: boolean;
-
-  // Loading states
-  isAccepting?: boolean;
-  isDeclining?: boolean;
-  isConfirming?: boolean;
-
-  // Render customization
-  renderHeader?: (event) => ReactNode;
-  renderFooter?: (event) => ReactNode;
-  renderActions?: (event) => ReactNode;
-
-  // i18n labels
-  labels?: IEventPopoverLabels;
-}
-```
-
-### IEventPopoverLabels
-
-All label strings are customizable for i18n:
-
-```typescript
-interface IEventPopoverLabels {
-  edit?: string;
-  delete?: string;
-  cancel?: string;
-  accept?: string;
-  decline?: string;
-  confirmMeeting?: string;
-  participants?: string;
-  description?: string;
-  // ... more keys
-}
-```
-
----
-
-## 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, firstDay?: number) => Date` |
-| `endOfWeek` | `(date: Date, firstDay?: number) => Date` |
-| `startOfMonth` | `(date: Date) => Date` |
-| `endOfMonth` | `(date: Date) => Date` |
-| `startOfYear` | `(date: Date) => Date` |
-| `endOfYear` | `(date: Date) => Date` |
-| `addDays` | `(date: Date, days: number) => Date` |
-| `addMonths` | `(date: Date, months: number) => Date` |
-| `addYears` | `(date: Date, years: number) => Date` |
-| `addHours` | `(date: Date, hours: number) => Date` |
-| `addMinutes` | `(date: Date, minutes: number) => Date` |
-| `isSameDay` | `(a: Date, b: Date) => boolean` |
-| `isSameMonth` | `(a: Date, b: Date) => boolean` |
-| `isSameYear` | `(a: Date, b: Date) => boolean` |
-| `isToday` | `(date: Date) => boolean` |
-| `isWeekend` | `(date: Date) => boolean` |
-| `isBefore` | `(a: Date, b: Date) => boolean` |
-| `isAfter` | `(a: Date, b: Date) => boolean` |
-| `isBetween` | `(date: Date, start: Date, end: Date) => boolean` |
-| `getWeekDays` | `(start: Date, count?: number) => Date[]` |
-| `getMonthDays` | `(date: Date, firstDay?: number) => Date[]` |
-| `getYearMonths` | `(date: Date) => Date[]` |
-| `getDaysBetween` | `(start: Date, end: Date) => number` |
-| `getMinutesBetween` | `(start: Date, end: Date) => number` |
-| `formatTime` | `(date: Date, format: '12h'│'24h') => string` |
-| `formatDate` | `(date: Date, options?: Intl.DateTimeFormatOptions) => string` |
-| `formatDateRange` | `(start: Date, end: Date) => string` |
-| `getWeekNumber` | `(date: Date) => number` |
-| `getDaysInMonth` | `(date: Date) => number` |
-| `clampDate` | `(date: Date, min: Date, max: Date) => Date` |
-
-### event-utils.ts
-
-Event filtering, sorting, and classification:
-
-| Function | Purpose |
-|---|---|
-| `isMultiDayEvent` | Checks if event spans midnight |
-| `isAllDayEvent` | Checks if event is all-day |
-| `getEventsForDay` | Filters events that overlap a given day |
-| `getEventsForRange` | Filters events that overlap a date range |
-| `sortEvents` | Sort by start date, then duration |
-| `groupEventsByDay` | Groups events by calendar date |
-| `groupEventsByResource` | Groups events by resourceId |
-| `filterEventsByScheduleType` | Client-side schedule type filter |
-| `filterEventsByParticipant` | Client-side participant filter |
-| `searchEvents` | Text search across event fields |
-| `getEventDurationMinutes` | Returns event duration in minutes |
-| `splitMultiDayEvent` | Splits multi-day event into per-day segments |
-
-### grid-utils.ts
-
-Grid layout calculations:
-
-| Function | Purpose |
-|---|---|
-| `generateTimeSlots` | Creates time slot array for given hour range |
-| `getHourHeight` | Pixel height for one hour from slot config |
-| `getSlotHeight` | Pixel height for one slot |
-| `timeToPixels` | Converts time to vertical pixel offset |
-| `pixelsToTime` | Converts vertical pixel offset to time |
-| `getColumnsForDay` | Column count for a day in week view |
-| `snapToSlot` | Snaps a time to nearest slot boundary |
-
-### position-utils.ts
-
-Event overlap and positioning:
-
-| Function | Purpose |
-|---|---|
-| `calculateEventPositions` | Computes non-overlapping layout for events in a column |
-| `findOverlappingGroups` | Groups events that share time ranges |
-| `calculateColumnSpans` | Assigns columns and spans within overlap groups |
-
----
-
-## 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 */
-  --calendar-bg: #ffffff;
-  --calendar-surface: #f8fafc;
-
-  /* Borders */
-  --calendar-border: #e2e8f0;
-  --calendar-border-strong: #cbd5e1;
-
-  /* Text */
-  --calendar-text: #0f172a;
-  --calendar-text-muted: #64748b;
-  --calendar-text-inverted: #ffffff;
-
-  /* Interactive */
-  --calendar-primary: #3b82f6;
-  --calendar-primary-hover: #2563eb;
-  --calendar-hover: #f1f5f9;
-
-  /* Grid */
-  --calendar-hour-height: 64px;
-  --calendar-slot-height: 32px;
-  --calendar-header-height: 56px;
-  --calendar-gutter-width: 72px;
-
-  /* Selection */
-  --calendar-selection-bg: rgba(59, 130, 246, 0.1);
-  --calendar-selection-border: rgba(59, 130, 246, 0.3);
-  --calendar-selection-handle: #3b82f6;
-
-  /* Current time */
-  --calendar-now-line: #ef4444;
-  --calendar-now-dot: #ef4444;
-
-  /* Working hours */
-  --calendar-working-bg: transparent;
-  --calendar-non-working-bg: #f8fafc;
-
-  /* Sidebar / filter */
-  --calendar-sidebar-width: 280px;
-}
-```
-
-### Dark Mode
-
-Override with `.dark` class:
-
-```css
-.dark {
-  --calendar-bg: #0f172a;
-  --calendar-surface: #1e293b;
-  --calendar-border: #334155;
-  --calendar-text: #f1f5f9;
-  --calendar-text-muted: #94a3b8;
-  /* ... etc */
-}
-```
-
-### Key CSS Classes
-
-| Class | Purpose |
-|---|---|
-| `.calendar-loading-overlay` | Translucent loading indicator overlay |
-| `.calendar-scroll-container` | Scrollable grid container |
-| `.calendar-time-gutter` | Hour labels column |
-| `.calendar-current-time-indicator` | Red line + dot for current time |
-| `.calendar-selection-overlay` | Blue drag selection highlight |
-| `.day-events-expansion-backdrop` | Backdrop for expanded month cell |
-| `.day-events-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`
-- `TimeSlot`
-- `MultiDayBanner`, `MultiDayBannerProps`
-
-**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`, `DialogContent`, `DialogTrigger`, `DialogClose`, `DialogHeader`, `DialogTitle`, `DialogDescription`
-- `Popover`, `PopoverContent`, `PopoverTrigger`, `PopoverAnchor`
-- `Sheet`, `SheetContent`, `SheetTrigger`, `SheetClose`, `SheetHeader`, `SheetTitle`, `SheetDescription`
-- `Tooltip`, `TooltipContent`, `TooltipProvider`, `TooltipTrigger`
-
-### 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`
-- `TailwindCalendar`
-
-### 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`:
-
-- **Formatter**: tabs, single quotes, 100 line width
-- **Linter**: recommended + `noUnusedVariables`, `noExplicitAny`
-- **Organize imports**: enabled
-
-```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 '@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.