@innosolutions/inno-calendar 1.0.49 → 1.0.51

package/AGENT.md

@@ -1,42 +1,78 @@
 # @innosolutions/inno-calendar — AI Agent Reference
 
-> **Version**: 1.0.33 · **Runtime**: React 18+ / TypeScript · **Build**: Vite (library mode) + vite-plugin-dts
-> **Published as**: `@innosolutions/inno-calendar` on npm (public)
+> **Version 1.0.49** | React 18+/19 | TypeScript 5.9 | Vite 7 library-mode  
+> Headless-first, fully customizable React calendar for enterprise applications.
 
-This document gives an AI coding agent all the context it needs to work **in this
-package** or **integrate it into a consuming application** correctly. Treat it as the
-single source of truth for types, props, exports, patterns, and integration guidance.
+---
+
+## 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, fully customizable React calendar package. It provides:
-
-- Multiple views: day, week, month, year, agenda, timeline, and resource views
-- Drag-to-select time slots for event creation
-- Drag & drop event repositioning
-- A slot system for replacing any visual region
-- A classNames API for granular CSS overrides
-- Rich event cards (title, type, product, participant count, time, location)
-- Working hours visualization with disabled-hour hatching
-- Widget components for dashboard embedding
-- Generic `CalendarEvent<TData>` — consumers bring their own data shape
-- Built-in client-side filtering by schedule type, participants, and search query
-- Preferences persistence (slot duration, working hours, badge variant, etc.)
-
-The package is **fully data-agnostic**: it never fetches data, never knows about
-any backend, and never imposes a domain model. Consumers provide an `events` array
-and handle mutations themselves — works with any data layer (React Query, SWR,
-tRPC, plain fetch, etc.).
+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 server
-npm run build        # Vite build (outputs dist/)
+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
@@ -46,110 +82,95 @@ npm run format       # Biome format
 
 ## 3. Package Exports
 
+Defined in `package.json`:
+
 ```jsonc
 {
-  ".": "dist/index.{mjs,cjs,d.ts}", // Full API
-  "./core": "dist/core/index.{mjs,cjs}", // Headless core only
-  "./components": "dist/components/index.{mjs,cjs}", // UI components
-  "./presets": "dist/presets/index.{mjs,cjs}", // Pre-built configs
-  "./lib": "dist/lib/index.{mjs,cjs}", // cn() util
-  "./utils": "dist/utils.{mjs,cjs}", // utils
-  "./styles": "dist/styles/index.css", // CSS
-  "./styles.css": "dist/styles/index.css", // CSS alias
+  "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"
+  }
 }
 ```
 
-Typical consumer imports:
+Consumer import patterns:
 
 ```tsx
-import { InnoCalendar, type CalendarEvent } from "@innosolutions/inno-calendar";
-import "@innosolutions/inno-calendar/styles";
+// 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 (types.ts)
+## 4. Core Types
 
-### CalendarEvent\<TData\>
+All types are defined in `src/core/types.ts` (1473 lines).
 
-The main event type. `TData` defaults to `Record<string, unknown>`.
+### CalendarEvent\<TData\>
 
 ```typescript
 interface CalendarEvent<TData = Record<string, unknown>> extends IBaseEvent {
   // Required (from IBaseEvent)
   id: string;
+  title: string;
   startDate: Date;
   endDate: Date;
-  title: string;
 
-  // Optional display fields
+  // Optional visual/behavioral
   description?: string;
-  color?: TEventColor; // 'blue' | 'green' | 'red' | ... | 'indigo'
-  hexColor?: string; // Hex override (takes precedence over color)
+  color?: TEventColor;
+  hexColor?: string;
   isAllDay?: boolean;
   isMultiDay?: boolean;
   isCanceled?: boolean;
   isRecurring?: boolean;
-  resourceId?: string; // For resource/timeline views
-
-  // Built-in filtering (optional — skip if you filter server-side)
-  scheduleTypeId?: number; // Enables built-in schedule type filtering
-  scheduleTypeName?: string; // Enables built-in search
-  participants?: ICalendarUser[]; // Enables built-in participant filtering
-
-  // @deprecated — still functional for backward compat, will be removed in next major.
-  // Migrate to the `data` bag. Built-in components read `data` first, then fall back here.
-  meetingTookPlace?: boolean; // → data.meetingTookPlace
-  isAccepted?: boolean; // → data.isAccepted
-  companyId?: number; // → data.companyId
-  cancelReason?: string | null; // → data.cancelReason
-  scheduleTypeCode?: string; // → data.scheduleTypeCode
-  opportunityId?: number; // → data.opportunityId
-  propertyId?: number; // → data.propertyId
-  projectId?: number; // → data.projectId
-  contactId?: number; // → data.contactId
-  user?: ICalendarUser; // → data.user
-
-  // Consumer's domain-specific data (RECOMMENDED)
-  data?: TData;
-}
-```
+  resourceId?: string;
 
-**Data placement rule:** All domain-specific fields belong in `data?: TData`.
-The deprecated top-level fields above are kept only for backward compatibility —
-consumers should migrate values into the `data` bag. Built-in components
-(EventCard, EventPopover, TimelineView) read from `event.data` first, then
-fall back to the deprecated top-level fields.
+  // Built-in filtering (optional)
+  scheduleTypeId?: number;
+  scheduleTypeName?: string;
+  participants?: ICalendarUser[];
 
-### TCalendarView
+  // Consumer data bag (RECOMMENDED for all domain fields)
+  data?: TData;
 
-```typescript
-type TCalendarView =
-  | "day"
-  | "week"
-  | "month"
-  | "year"
-  | "agenda"
-  | "resource-day"
-  | "resource-week"
-  | "timeline-day"
-  | "timeline-3day"
-  | "timeline-week";
+  // @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;
+}
 ```
 
-### ICalendarUser
+### IResource\<TData\>
 
 ```typescript
-interface ICalendarUser<TData = Record<string, unknown>> {
+interface IResource<TData = Record<string, unknown>> {
   id: string;
   name: string;
-  email?: string;
+  title?: string;
   avatar?: string;
+  color?: TEventColor | string;
   data?: TData;
 }
 ```
 
-### IScheduleType
+### IScheduleType\<TData\>
 
 ```typescript
 interface IScheduleType<TData = Record<string, unknown>> {
@@ -167,27 +188,100 @@ interface IScheduleType<TData = Record<string, unknown>> {
 }
 ```
 
-### ISelectionResult
+### ICalendarUser\<TData\>
 
 ```typescript
-interface ISelectionResult {
-  startDate: Date;
-  endDate: Date;
-  resourceId?: string; // Set when selecting in resource/timeline views
+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;
 }
 ```
 
-### TBadgeVariant
+### View Types
 
 ```typescript
-type TBadgeVariant = "dot" | "colored" | "mixed";
+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
 
-The main `<InnoCalendar>` component accepts:
+`<InnoCalendar>` is the primary entry point. It wraps `InnoCalendarProvider` + `SlotSelectionProvider` + `DragDropProvider` internally.
 
 ```typescript
 interface InnoCalendarProps<TEventData> {
@@ -197,12 +291,12 @@ interface InnoCalendarProps<TEventData> {
   scheduleTypes?: IScheduleType[];
 
   // === INITIAL STATE ===
-  initialView?: TCalendarView; // default: 'week'
-  initialDate?: Date; // default: today
-  initialSelectedUserId?: string | "all";
+  initialView?: TCalendarView;                    // default: 'week'
+  initialDate?: Date;                             // default: new Date()
+  initialSelectedUserId?: string | 'all';         // default: 'all'
   initialScheduleTypeIds?: number[];
   initialParticipantIds?: string[];
-  initialWorkingHoursView?: "default" | "enabled" | "disabled";
+  initialWorkingHoursView?: 'default' | 'enabled' | 'disabled';
   initialSearchQuery?: string;
 
   // === PREFERENCES ===
@@ -219,33 +313,80 @@ interface InnoCalendarProps<TEventData> {
 
   // === UI OPTIONS ===
   className?: string;
-  showHeader?: boolean; // default: true
-  minSelectionMinutes?: number; // default: 30
-  showMoreEventsInPopover?: boolean; // @deprecated — use showMoreMode instead
-  showMoreMode?: 'expand' | 'popover' | 'dayView'; // default: 'expand'
+  showHeader?: boolean;                           // default: true
+  minSelectionMinutes?: number;                   // default: 30
+  showMoreMode?: 'dayView' | 'popover' | 'expand'; // default: 'expand'
+  isLoading?: boolean;                            // default: false
 
   // === CUSTOM RENDERING ===
-  renderPopover?: (props: {
-    event: CalendarEvent<TEventData>;
-    onClose: () => void;
-  }) => ReactNode;
-
-  // === EXTENSIBILITY ===
+  renderPopover?: (props: { event; onClose }) => ReactNode;
   slots?: ICalendarSlots<TEventData>;
   classNames?: ICalendarClassNames;
 
-  // === CUSTOM CONTENT SLOTS ===
+  // === 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 (ICalendarSlots)
+## 6. Slots System
 
-Every visual region can be replaced:
+Every visual region can be replaced via `slots`:
 
 ```typescript
 interface ICalendarSlots<TEventData, TScheduleTypeData, TResourceData> {
@@ -254,14 +395,14 @@ interface ICalendarSlots<TEventData, TScheduleTypeData, TResourceData> {
   footer?: ComponentType<IFooterSlotProps<TEventData>>;
   viewWrapper?: ComponentType<IViewWrapperSlotProps>;
 
-  // Day cell (month/year)
+  // 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)
+  // Time Grid (day/week views)
   timeGutter?: ComponentType<ITimeGutterSlotProps>;
   timeSlotBackground?: ComponentType<ITimeSlotBackgroundSlotProps>;
   columnHeader?: ComponentType<IColumnHeaderSlotProps>;
@@ -276,20 +417,45 @@ interface ICalendarSlots<TEventData, TScheduleTypeData, TResourceData> {
   resourceHeader?: ComponentType<IResourceHeaderSlotProps<TResourceData>>;
   rowHeader?: ComponentType<IRowHeaderSlotProps<TResourceData>>;
 
-  // Filter
+  // Filters
   filter?: ComponentType<IFilterSlotProps<TScheduleTypeData>>;
 
-  // Empty states
+  // 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)
+## 7. ClassNames API
 
-Granular CSS class overrides merged via `cn()`:
+`ICalendarClassNames` provides 30+ CSS class override keys. Classes are merged with defaults via `cn()`.
 
 ```typescript
 interface ICalendarClassNames {
@@ -299,7 +465,7 @@ interface ICalendarClassNames {
   footer?: string;
   viewContainer?: string;
 
-  // Month view
+  // Month View
   monthGrid?: string;
   weekdayHeader?: string;
   weekdayLabel?: string;
@@ -311,7 +477,7 @@ interface ICalendarClassNames {
   dayCellContent?: string;
   dayCellFooter?: string;
 
-  // Week/Day view
+  // Week/Day View
   timeGutter?: string;
   timeGutterLabel?: string;
   timeSlot?: string;
@@ -343,339 +509,1102 @@ interface ICalendarClassNames {
 
 ---
 
-## 8. EventCard Rich Data Display
+## 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 |
 
-The `EventCard` component (used in day/week time grids) extracts and displays
-rich data from `event.data`, then falls back to deprecated top-level fields:
+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
-// Fields extracted from event.data (safe runtime access, then deprecated fallback)
+// Runtime enrichment reading pattern:
 const eventData = event.data as Record<string, unknown> | undefined;
-const meetingTookPlace =
-  (eventData?.meetingTookPlace as boolean) ?? event.meetingTookPlace ?? false;
-const scheduleTypeName =
-  event.scheduleTypeName ||
-  (eventData?.scheduleTypeName as string) ||
-  (eventData?.typeName as string);
-const productName = eventData?.productName as string;
-const nrParticipant = eventData?.nrParticipant as number;
-const siteName = eventData?.siteName as string;
-const siteCity = eventData?.siteCity as string;
-const locationStr = [siteName, siteCity].filter(Boolean).join(", ");
+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;
 ```
 
-### All-Day / Multi-Day Time Display
+### 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.
 
-All time displays use `formatEventTimeDisplay()` from `core/utils/event-utils.ts`.
-All-day events show **"All day"** instead of confusing raw times like "00:00 - 23:59".
+### Exports
 
-| Event Type            | Display                               |
-| --------------------- | ------------------------------------- |
-| All-day (single day)  | "All day"                             |
-| All-day (multi-day)   | "All day · Feb 16 – Feb 18"           |
-| Timed (multi-day)     | "Feb 16, 09:00 – Feb 18, 17:00"       |
-| Timed (same day)      | "09:00 - 17:00"                       |
+```typescript
+export { EventCard, type EventCardProps }
+export { EventBlock, type EventBlockProps }
+export { MultiDayEventBar, type MultiDayEventBarProps }
+export { getEventColorClasses }  // Utility: TEventColor → { bg, text, border }
+```
 
-Detection uses `detectAllDayEvent()` which checks `isAllDay: true` flag OR
-midnight-to-midnight time boundaries (00:00:00 start, 23:59/00:00 end).
+---
 
-`separateEventsByDuration()` routes all-day events to the `multiDay` bucket
-(banner display) even when they span only a single day.
+## 9. EventPopover Component
 
-Display rules based on event duration:
+Located in `src/components/event/event-popover.tsx` (1519 lines).
 
-| Duration  | Shows                                                             |
-| --------- | ----------------------------------------------------------------- |
-| < 25 min  | Title only (centered)                                             |
-| 25–44 min | Title + time (with ClockIcon)                                     |
-| ≥ 45 min  | Full details: title + type, product, participants, time, location |
+Full-featured event detail popover with action buttons, participant list, and domain data display.
 
-The title line format: `{title}` + optional ` - {scheduleTypeName}` in lighter weight.
+### Key Props
 
-### Month View "Show More" Expansion
+```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;
+}
+```
 
-When a day cell has more events than `MAX_EVENTS_SHOWN`, the "+N more" indicator
-uses one of three modes controlled by `showMoreMode`:
+### IEventPopoverLabels
 
-| Mode       | Behavior                                                                       |
-| ---------- | ------------------------------------------------------------------------------ |
-| `'expand'` | Morphing overlay (`DayEventsExpansion`) animates from cell to centered panel    |
-| `'popover'`| Radix popover shows all events inline                                          |
-| `'dayView'`| Redirects to day view via `onDateChange`                                       |
+All label strings are customizable for i18n:
 
-Default is `'expand'`. The `DayEventsExpansion` component uses CSS transitions
-(280ms, `cubic-bezier(0.32, 0.72, 0, 1)`) with phase states
-(`closed` → `entering` → `open` → `exiting` → `closed`).
+```typescript
+interface IEventPopoverLabels {
+  edit?: string;
+  delete?: string;
+  cancel?: string;
+  accept?: string;
+  decline?: string;
+  confirmMeeting?: string;
+  participants?: string;
+  description?: string;
+  // ... more keys
+}
+```
 
 ---
 
-## 9. Integration Guide
+## 10. Preferences System
 
-This section documents the common patterns consumers use when integrating the
-package. Adapt to whatever data layer, routing, or UI framework the consuming
-application uses.
+Located in `src/core/preferences/`.
 
-### 9.1 Transform API Data → CalendarEvent
+### IPreferencesConfig
 
-Every consumer needs a **transformer layer** that maps its API response shapes to
-the package's generic `CalendarEvent<TData>` type. Place these in a `transformers.ts`
-(or similar) file, co-located with the calendar feature.
+Passed via `<InnoCalendar preferencesConfig={...}>`:
 
 ```typescript
-// Example: transformers.ts in the consuming app
-import type {
-  CalendarEvent,
-  ICalendarUser,
-  IScheduleType,
-} from "@innosolutions/inno-calendar";
-
-/** Define the shape of your domain-specific event data. */
-interface MyEventData {
-  [key: string]: unknown;
-  agendaTypeId: number;
-  agendaTypeName: string;
-  companyId: number;
-  meetingTookPlace: boolean;
-  isAccepted: boolean;
-  cancelReason?: string;
-  participantNames: string[];
+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
 }
+```
 
-/**
- * Transform raw API events into CalendarEvent[].
- * Core fields at top level, domain data in the `data` bag.
- */
-export function transformEvents(
-  apiEvents: ApiEvent[],
-): CalendarEvent<MyEventData>[] {
-  return apiEvents.map((event) => ({
-    id: event.id.toString(),
-    title: event.title,
-    startDate: new Date(event.startDate),
-    endDate: new Date(event.endDate),
-    description: event.description ?? undefined,
-    color: eventTypeColorMap[event.type.id] ?? "blue",
-    hexColor: eventTypeHexMap[event.type.id] ?? "#069AD7",
-    isCanceled: event.isCanceled,
-    isAllDay: false,
-    isMultiDay: isDifferentDay(
-      new Date(event.startDate),
-      new Date(event.endDate),
-    ),
+### Preference Modes
 
-    // Built-in filtering (optional — omit if you filter server-side)
-    scheduleTypeId: event.type.id,
-    scheduleTypeName: event.type.name,
-
-    // Domain-specific data (RECOMMENDED location)
-    data: {
-      agendaTypeId: event.type.id,
-      agendaTypeName: event.type.name,
-      companyId: event.companyId,
-      meetingTookPlace: event.meetingTookPlace,
-      isAccepted: event.isAccepted,
-      cancelReason: event.cancelReason,
-      participantNames: event.participants?.map((p) => p.name) ?? [],
-    },
-  }));
+| 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;
 }
 ```
 
-### 9.2 Filtering Strategies
+### useCalendarPreferences Hook
 
-The package supports **two** filtering approaches — pick whichever fits:
+Returns `IUsePreferencesReturn`:
 
-| Strategy                   | How it works                                                                | When to use                                    |
-| -------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------- |
-| **Client-side** (built-in) | Provide `scheduleTypeId`, `participants` on events + set initial filter IDs | Small datasets, no server-side filter endpoint |
-| **Server-side**            | Filter events at the API level; pass already-filtered `events[]`            | Large datasets, URL-driven filters, pagination |
+```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;
+}
+```
 
-For server-side filtering, build a filter panel as a regular form component and
-pass it via `filterContent`:
+### Example: Locking slot duration
 
 ```tsx
 <InnoCalendar
-  events={filteredEventsFromApi}
-  filterContent={<MyFilterPanel />}
+  events={events}
+  preferencesConfig={{
+    modes: { slotDuration: 'locked' },
+    locked: { slotDuration: 30 },
+  }}
 />
 ```
 
-The filter panel writes to URL state (or any state manager); the data query
-includes those filter values; the calendar just renders whatever `events` it receives.
+---
+
+## 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`.
 
-### 9.3 Custom Event Popover
+### DragDropProvider
 
-The built-in popover works out of the box, but most applications customize it to
-show domain-specific details (linked entities, action buttons, RSVP status, etc.).
-Override via `renderPopover`:
+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
-  renderPopover={({ event, onClose }) => (
-    <MyEventPopover event={event} onClose={onClose} />
-  )}
+  events={events}
+  initialView="timeline-week"
+  onEventDrop={(result) => {
+    console.log(result.event.id, result.newStartDate, result.newResourceId);
+    // Update your backend
+  }}
 />
 ```
 
-A custom popover typically:
+---
+
+## 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 |
 
-1. Fetches full event details on open (list endpoints often return minimal data)
-2. Shows domain-specific fields from `event.data` (cancel reason, linked contacts, etc.)
-3. Provides action buttons (edit, cancel, delete, confirm, etc.)
+---
+
+## 17. Presets
+
+Located in `src/presets/`.
 
-### 9.4 Custom Header Actions
+### DefaultCalendar
 
-Replace the default "Add Event" button with your own header actions (dropdown
-menus, multiple create buttons per event type, etc.):
+Pre-configured calendar with sensible defaults:
 
 ```tsx
-<InnoCalendar headerActions={<MyCreateDropdown />} />
+import { DefaultCalendar } from '@innosolutions/inno-calendar';
+
+<DefaultCalendar events={events} />
 ```
 
-### 9.5 Slot Selection → Event Creation
+### TailwindCalendar
 
-When a user drags across time slots, `onSlotSelect` fires with the selected
-date range. The consumer decides what happens next — open a form directly, show a
-dialog to pick the event type, or create an event immediately:
+Tailwind-optimized calendar preset with carefully chosen utility classes:
 
 ```tsx
-onSlotSelect={(selection) => {
-  // Option A: open a create form directly with pre-filled dates
-  openCreateForm({ startDate: selection.startDate, endDate: selection.endDate });
+import { TailwindCalendar } from '@innosolutions/inno-calendar';
 
-  // Option B: show an event type picker first, then route to the right form
-  openEventTypePicker(selection);
-}}
+<TailwindCalendar events={events} />
 ```
 
-Whether you need a type-picker step depends on whether the app has multiple
-event categories. Single-type apps can skip straight to the form.
+---
 
-### 9.6 Settings Panel
+## 18. CSS & Theming
 
-The package ships built-in settings controls (slot duration, visible hours,
-working hours, badge variant). Pass custom content via `settingsContent` to
-extend or replace them:
+Styles are in `src/styles/calendar.css` (imported via `@innosolutions/inno-calendar/styles`).
 
-```tsx
-<InnoCalendar settingsContent={<MySettingsPanel />} />
-```
+### CSS Custom Properties
 
-Most apps will customize this to include project-specific preferences or
-integrate with a persistence layer that saves settings per user.
+```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;
+}
+```
 
-### 9.7 Working Hours & Disabled Slots
+### Dark Mode
 
-Non-working-hour time slots receive the CSS class `inno-calendar-disabled-hour`.
-The consumer provides the hatching/dimming style:
+Override with `.dark` class:
 
 ```css
-.inno-calendar-disabled-hour,
-.bg-calendar-disabled-hour {
-  background-image: repeating-linear-gradient(
-    -60deg,
-    var(--inno-border-color, #e5e7eb) 0 0.5px,
-    transparent 0.5px 8px
-  );
+.dark {
+  --calendar-bg: #0f172a;
+  --calendar-surface: #1e293b;
+  --calendar-border: #334155;
+  --calendar-text: #f1f5f9;
+  --calendar-text-muted: #94a3b8;
+  /* ... etc */
 }
 ```
 
-Working hours are configurable per day via the built-in settings controls or
-programmatically via `useInnoCalendar().setWorkingHours()`.
+### 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 |
 
 ---
 
-## 10. Context Hooks
+## 19. Constants
 
-### useInnoCalendar\<TEventData\>()
+Located in `src/core/constants.ts`.
 
-The main context hook. Returns:
+### View List
 
 ```typescript
-{
-  // State
-  view: TCalendarView;
-  selectedDate: Date;
-  slotDuration: TSlotDuration;
-  filteredEvents: CalendarEvent<TEventData>[];
-  users: ICalendarUser[];
-  scheduleTypes: IScheduleType[];
-  visibleHours: { start: number; end: number };
-  workingHours: TWorkingHours;
-  badgeVariant: TBadgeVariant;
-  showWorkingHoursOnly: boolean;
-  selectedUserId: string | 'all';
-  selectedScheduleTypeIds: number[];
-
-  // Setters
-  setView: (view: TCalendarView) => void;
-  setSelectedDate: (date: Date) => void;
-  setSlotDuration: (duration: TSlotDuration) => void;
-  setVisibleHours: (hours: { start: number; end: number }) => void;
-  setWorkingHours: (hours: TWorkingHours | ((prev: TWorkingHours) => TWorkingHours)) => void;
-  setBadgeVariant: (variant: TBadgeVariant) => void;
-  setShowWorkingHoursOnly: (show: boolean) => void;
-  setSelectedUserId: (id: string | 'all') => void;
-  setSelectedScheduleTypeIds: (ids: number[]) => void;
-
-  // Utilities
-  isPreferenceLocked?: (key: string) => boolean;
+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>
+    ),
+  }}
+/>
+```
+
 ---
 
-## 11. File Naming Conventions
+## 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/`
 
-All files use **kebab-case** naming:
+- `DefaultCalendar`
+- `TailwindCalendar`
 
-| Type       | Convention               | Example                                    |
-| ---------- | ------------------------ | ------------------------------------------ |
-| Components | `kebab-case.tsx`         | `event-card.tsx`, `week-view.tsx`          |
-| Hooks      | `use-kebab-case.ts`      | `use-calendar.ts`, `use-slot-selection.ts` |
-| Context    | `kebab-case-context.tsx` | `calendar-context.tsx`                     |
-| Types      | `types.ts`               | `types.ts`                                 |
-| Utilities  | `kebab-case.ts`          | `date-utils.ts`, `position-utils.ts`       |
-| Constants  | `constants.ts`           | `constants.ts`                             |
-| Index      | `index.ts`               | `index.ts`                                 |
-| Styles     | `kebab-case.css`         | `calendar.css`                             |
+### From `src/lib/`
 
-Folders also use kebab-case: `core/`, `components/`, `presets/`.
+- `cn` — `clsx(...inputs) | twMerge` className composer
 
 ---
 
-## 12. Styling
+## 22. File Naming Conventions
 
-- **TailwindCSS 4+** with `cn()` helper (clsx + tailwind-merge)
-- **class-variance-authority (CVA)** for component variants
-- **CSS custom properties** prefixed with `--inno-` or `--ic-`
-- **lucide-react** for icons (ClockIcon, UsersIcon, MapPinIcon, etc.)
-- **Radix UI** for popovers, tooltips, dropdowns, selects (optional peer deps)
-- **Expansion overlay CSS**: `.ic-expansion-backdrop`, `.ic-expansion-panel` in `calendar.css`
+**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
+```
 
 ---
 
-## 13. Biome Configuration
+## 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
 
-- Tabs for indentation
-- Single quotes
-- Warns on `!` non-null assertions
-- Forbids unused variables
-- Forbids explicit `any`
+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 },
+  }}
+/>
+```
 
-Run before commits: `npm run format && npm run lint && npm run typecheck`
+### 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);
+   ```
 
 ---
 
-## 14. Critical Rules
-
-1. **Never add external dependencies to `core/`** — only React and native APIs
-2. **Rich data in EventCard reads from `event.data` first**, then falls back to deprecated top-level fields
-3. **CalendarEvent is domain-agnostic** — domain fields go in `data`, deprecated top-level fields stay until next major
-4. **Consumers handle data fetching** — this package never calls APIs
-5. **Filtering is the consumer's choice** — built-in client-side filtering is available via `scheduleTypeId` / `participants`, or consumers filter server-side and pass pre-filtered events
-6. **All public APIs need JSDoc** with `@example` blocks
-7. **Use section separators** (`// ====... TYPES ====...`) to organize code
-8. **Run `npm run typecheck` before committing**
-9. **Files and folders use kebab-case** — never PascalCase
-10. **Update AGENT.md, README.md, and .github/copilot-instructions.md** when changing public APIs
+## 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.