@innosolutions/inno-calendar 1.0.2 → 1.0.4

package/AGENT.md

@@ -0,0 +1,1253 @@
+# @inno/calendar - Agent Implementation Guide
+
+> This document contains comprehensive implementation details for AI coding agents. Copy this entire file into your context when working with @inno/calendar.
+
+---
+
+## Package Overview
+
+**@innosolutions/inno-calendar** is a headless-first, fully customizable React calendar package for enterprise applications.
+
+- **Version**: 1.0.4+
+- **React**: >=18.0.0
+- **TypeScript**: Full type coverage
+- **Styling**: TailwindCSS compatible, CSS custom properties
+- **Dependencies**: Minimal (clsx, tailwind-merge, class-variance-authority)
+
+---
+
+## Installation & Setup
+
+### Install Package
+
+```bash
+npm install @innosolutions/inno-calendar
+```
+
+### Install Optional Peer Dependencies
+
+```bash
+# For enhanced UI (popovers, tooltips, dropdowns)
+npm install @radix-ui/react-popover @radix-ui/react-tooltip @radix-ui/react-dropdown-menu
+```
+
+### Import Styles
+
+**Required** - Import in your app's entry point:
+
+```tsx
+// In main.tsx or App.tsx
+import '@innosolutions/inno-calendar/styles';
+```
+
+Or in CSS:
+
+```css
+@import '@innosolutions/inno-calendar/styles';
+```
+
+---
+
+## Core Types
+
+### CalendarEvent
+
+```tsx
+interface CalendarEvent<TData = Record<string, unknown>> {
+  id: string;
+  title: string;
+  startDate: Date;
+  endDate: Date;
+  color?: TEventColor;
+  description?: string;
+  isCanceled?: boolean;
+  isAllDay?: boolean;
+  scheduleTypeId?: number;
+  scheduleTypeName?: string;
+  participants?: ICalendarUser[];
+  data?: TData;
+}
+```
+
+### TEventColor
+
+```tsx
+type TEventColor =
+  | 'blue' | 'green' | 'red' | 'yellow'
+  | 'purple' | 'orange' | 'pink' | 'teal'
+  | 'gray' | 'indigo';
+```
+
+### TCalendarView
+
+```tsx
+type TCalendarView =
+  | 'day' | 'week' | 'month' | 'year' | 'agenda'
+  | 'timeline-day' | 'timeline-3day' | 'timeline-week';
+```
+
+### ICalendarUser
+
+```tsx
+interface ICalendarUser {
+  id: string;
+  name: string;
+  avatar?: string;
+  email?: string;
+}
+```
+
+### IScheduleType
+
+```tsx
+interface IScheduleType {
+  id: number;
+  name: string;
+  color?: string;
+}
+```
+
+### TWorkingHours
+
+```tsx
+interface IWorkingHoursDay {
+  enabled: boolean;
+  from: number; // 0-23
+  to: number;   // 0-23
+}
+
+type TWorkingHours = Record<number, IWorkingHoursDay>;
+// Key: 0 = Sunday, 1 = Monday, ..., 6 = Saturday
+```
+
+### ISelectionResult
+
+```tsx
+interface ISelectionResult {
+  startDate: Date;
+  endDate: Date;
+  mode?: 'time' | 'day';
+}
+```
+
+### IDropResult
+
+```tsx
+interface IDropResult<TData = Record<string, unknown>> {
+  event: CalendarEvent<TData>;
+  newStartDate: Date;
+  newEndDate: Date;
+  oldStartDate: Date;
+  oldEndDate: Date;
+}
+```
+
+---
+
+## Main Components
+
+### InnoCalendar
+
+The primary component providing a complete calendar experience.
+
+```tsx
+import { InnoCalendar, type CalendarEvent } from '@innosolutions/inno-calendar';
+
+<InnoCalendar
+  // Required
+  events={events}
+  
+  // Data (optional)
+  users={users}
+  scheduleTypes={scheduleTypes}
+  
+  // Initial state
+  initialView="week"
+  initialDate={new Date()}
+  initialSelectedUserId="all"
+  initialScheduleTypeIds={[]}
+  initialParticipantIds={[]}
+  initialWorkingHoursView="default"
+  initialSearchQuery=""
+  
+  // Preferences
+  preferencesConfig={{
+    defaults: {
+      badgeVariant: 'colored',
+      slotDuration: 30,
+      workingHours: defaultWorkingHours,
+    },
+    locked: {
+      badgeVariant: false,
+      slotDuration: false,
+    },
+  }}
+  
+  // Callbacks
+  onEventClick={(event) => {}}
+  onSlotClick={(date, hour) => {}}
+  onSlotSelect={(selection) => {}}
+  onAddEvent={() => {}}
+  onEventDrop={(result) => {}}
+  onDateChange={(date, view) => {}}
+  onViewChange={(view) => {}}
+  
+  // UI options
+  showHeader={true}
+  minSelectionMinutes={30}
+  className="h-full"
+  
+  // Custom rendering
+  renderPopover={({ event, onClose }) => <CustomPopover event={event} onClose={onClose} />}
+  settingsContent={<SettingsPanel />}
+  filterContent={<FiltersRow />}
+/>
+```
+
+### InnoCalendarProvider
+
+Context provider for shared state across components.
+
+```tsx
+import { 
+  InnoCalendarProvider, 
+  useInnoCalendar,
+  CalendarHeader,
+  WeekView 
+} from '@innosolutions/inno-calendar';
+
+function App() {
+  return (
+    <InnoCalendarProvider
+      initialEvents={events}
+      initialUsers={users}
+      initialScheduleTypes={scheduleTypes}
+      initialView="week"
+      initialDate={new Date()}
+      preferencesConfig={preferencesConfig}
+      onDateChange={(date, view) => updateURL(date, view)}
+      onViewChange={(view) => updateURL(view)}
+    >
+      <CalendarContent />
+    </InnoCalendarProvider>
+  );
+}
+
+function CalendarContent() {
+  const {
+    // View & Navigation
+    view,
+    setView,
+    selectedDate,
+    setSelectedDate,
+    
+    // Data
+    events,
+    setEvents,
+    filteredEvents,
+    users,
+    scheduleTypes,
+    
+    // Filters
+    selectedUserId,
+    setSelectedUserId,
+    selectedScheduleTypeIds,
+    setSelectedScheduleTypeIds,
+    searchQuery,
+    setSearchQuery,
+    
+    // Visual Settings
+    badgeVariant,
+    setBadgeVariant,
+    
+    // Time Configuration
+    slotDuration,
+    setSlotDuration,
+    visibleHours,
+    setVisibleHours,
+    workingHours,
+    setWorkingHours,
+    showWorkingHoursOnly,
+    setShowWorkingHoursOnly,
+    
+    // Preferences
+    isPreferenceLocked,
+  } = useInnoCalendar();
+  
+  return (
+    <div>
+      <CalendarHeader />
+      <WeekView events={filteredEvents} date={selectedDate} />
+    </div>
+  );
+}
+```
+
+### Individual View Components
+
+```tsx
+import { 
+  DayView, 
+  WeekView, 
+  MonthView, 
+  YearView, 
+  AgendaView, 
+  TimelineView 
+} from '@innosolutions/inno-calendar';
+
+// Day View
+<DayView
+  events={events}
+  date={selectedDate}
+  visibleHours={{ startHour: 8, endHour: 18 }}
+  workingHours={workingHours}
+  slotDuration={30}
+  badgeVariant="colored"
+  onEventClick={handleEventClick}
+  onSlotSelect={handleSlotSelect}
+  renderPopover={renderCustomPopover}
+/>
+
+// Week View
+<WeekView
+  events={events}
+  date={selectedDate}
+  weekStartsOn={1} // 0 = Sunday, 1 = Monday
+  visibleHours={{ startHour: 0, endHour: 24 }}
+  workingHours={workingHours}
+  slotDuration={30}
+  badgeVariant="colored"
+  onEventClick={handleEventClick}
+  onSlotSelect={handleSlotSelect}
+  onDayClick={handleDayClick}
+  renderPopover={renderCustomPopover}
+/>
+
+// Month View
+<MonthView
+  events={events}
+  date={selectedDate}
+  badgeVariant="colored"
+  onEventClick={handleEventClick}
+  onDayClick={handleDayClick}
+  renderPopover={renderCustomPopover}
+/>
+
+// Year View
+<YearView
+  events={events}
+  year={2026}
+  onMonthClick={handleMonthClick}
+  onDayClick={handleDayClick}
+/>
+
+// Agenda View
+<AgendaView
+  events={events}
+  date={selectedDate}
+  onEventClick={handleEventClick}
+  renderPopover={renderCustomPopover}
+/>
+
+// Timeline View (Resource-based)
+<TimelineView
+  events={events}
+  users={users}
+  selectedDate={selectedDate}
+  daysToShow={3} // 1, 3, or 7
+  visibleHours={{ from: 8, to: 18 }}
+  onEventClick={handleEventClick}
+  renderPopover={renderCustomPopover}
+/>
+```
+
+### CalendarHeader
+
+```tsx
+import { CalendarHeader } from '@innosolutions/inno-calendar';
+
+<CalendarHeader
+  settingsContent={<SettingsPanel />}
+  filterContent={<FiltersRow />}
+  showAddButton={true}
+  onAddEvent={() => openCreateDialog()}
+/>
+```
+
+### Settings Components
+
+```tsx
+import {
+  SlotDurationSetting,
+  VisibleHoursSetting,
+  BadgeVariantSetting,
+  WorkingHoursSetting,
+} from '@innosolutions/inno-calendar';
+
+function SettingsPanel() {
+  return (
+    <div className="space-y-4 p-4">
+      <SlotDurationSetting />
+      <BadgeVariantSetting />
+      <VisibleHoursSetting />
+      <WorkingHoursSetting />
+    </div>
+  );
+}
+```
+
+### Filter Components
+
+```tsx
+import { UserFilter, ScheduleTypeFilter } from '@innosolutions/inno-calendar';
+
+function FiltersRow() {
+  const { 
+    users, 
+    selectedUserId, 
+    setSelectedUserId,
+    scheduleTypes,
+    selectedScheduleTypeIds,
+    setSelectedScheduleTypeIds 
+  } = useInnoCalendar();
+  
+  return (
+    <div className="flex gap-2">
+      <UserFilter
+        users={users}
+        selectedUserId={selectedUserId}
+        onSelect={setSelectedUserId}
+      />
+      <ScheduleTypeFilter
+        scheduleTypes={scheduleTypes}
+        selectedIds={selectedScheduleTypeIds}
+        onChange={setSelectedScheduleTypeIds}
+      />
+    </div>
+  );
+}
+```
+
+---
+
+## Data Transformation
+
+Transform your API data to match the calendar's expected format:
+
+```tsx
+// transformers.ts
+import type { CalendarEvent, ICalendarUser, IScheduleType } from '@innosolutions/inno-calendar';
+
+export function transformApiEvents(
+  apiEvents: ApiEvent[],
+  scheduleTypes: ApiScheduleType[]
+): CalendarEvent[] {
+  return apiEvents.map((event) => {
+    const scheduleType = scheduleTypes.find((st) => st.id === event.scheduleTypeId);
+    
+    return {
+      id: String(event.id),
+      title: event.subject || event.title,
+      startDate: new Date(event.startDate),
+      endDate: new Date(event.endDate),
+      description: event.description ?? undefined,
+      color: mapHexToColor(scheduleType?.colorHex) ?? 'blue',
+      scheduleTypeId: event.scheduleTypeId,
+      scheduleTypeName: scheduleType?.code || scheduleType?.name,
+      isCanceled: event.isCanceled ?? false,
+      isAllDay: event.isAllDay ?? false,
+      participants: event.participants?.map(transformParticipant),
+    };
+  });
+}
+
+export function transformParticipants(apiParticipants: ApiParticipant[]): ICalendarUser[] {
+  return apiParticipants.map((p) => ({
+    id: String(p.id),
+    name: `${p.firstName} ${p.lastName}`.trim() || p.email,
+    avatar: p.pictureUrl || p.avatar,
+    email: p.email,
+  }));
+}
+
+export function transformScheduleTypes(apiTypes: ApiScheduleType[]): IScheduleType[] {
+  return apiTypes.map((st) => ({
+    id: st.id,
+    name: st.resourceKey ?? st.code ?? st.name ?? `Type ${st.id}`,
+    color: st.colorHex,
+  }));
+}
+
+// Helper to map hex colors to TEventColor
+function mapHexToColor(hex?: string): TEventColor | undefined {
+  if (!hex) return undefined;
+  
+  const colorMap: Record<string, TEventColor> = {
+    '#3b82f6': 'blue',
+    '#22c55e': 'green',
+    '#ef4444': 'red',
+    '#eab308': 'yellow',
+    '#a855f7': 'purple',
+    '#f97316': 'orange',
+    '#ec4899': 'pink',
+    '#14b8a6': 'teal',
+    '#6b7280': 'gray',
+    '#6366f1': 'indigo',
+  };
+  
+  // Find closest match or default
+  const normalized = hex.toLowerCase();
+  return colorMap[normalized] ?? 'blue';
+}
+```
+
+---
+
+## URL Synchronization
+
+### With TanStack Router
+
+```tsx
+import { getRouteApi } from '@tanstack/react-router';
+import { z } from 'zod';
+
+// Schema for search params
+export const calendarSearchSchema = z.object({
+  view: z.string().optional(),
+  selectedDate: z.string().optional(),
+  startDate: z.string().optional(),
+  endDate: z.string().optional(),
+  scheduleTypeIds: z.array(z.number()).optional(),
+  participants: z.array(z.string()).optional(),
+  search: z.string().optional(),
+  workingHoursView: z.enum(['default', 'working']).optional(),
+});
+
+// Route definition
+export const Route = createFileRoute('/_layout/agenda/')({
+  validateSearch: calendarSearchSchema,
+  loaderDeps: ({ search }) => ({
+    startDate: search.startDate,
+    endDate: search.endDate,
+    scheduleTypeIds: search.scheduleTypeIds,
+    participants: search.participants,
+  }),
+  loader: async ({ context, deps }) => {
+    const [events, participants, scheduleTypes] = await Promise.all([
+      context.queryClient.ensureQueryData({
+        queryKey: ['agenda', deps.startDate, deps.endDate],
+        queryFn: () => fetchAgendaEvents(deps),
+      }),
+      context.queryClient.ensureQueryData({
+        queryKey: ['participants'],
+        queryFn: fetchParticipants,
+      }),
+      context.queryClient.ensureQueryData({
+        queryKey: ['schedule-types'],
+        queryFn: fetchScheduleTypes,
+      }),
+    ]);
+    return { events, participants, scheduleTypes };
+  },
+});
+
+// Component
+const routeApi = getRouteApi('/_layout/agenda/');
+
+function AgendaPage() {
+  const navigate = routeApi.useNavigate();
+  const searchParams = routeApi.useSearch();
+  const loaderData = routeApi.useLoaderData();
+  
+  const handleDateChange = useCallback((date: Date, view: TCalendarView) => {
+    const { startDate, endDate } = getViewDateRange(date, view);
+    navigate({
+      search: (prev) => ({
+        ...prev,
+        selectedDate: formatDate(date),
+        startDate: formatDate(startDate),
+        endDate: formatDate(endDate),
+      }),
+      replace: true,
+    });
+  }, [navigate]);
+  
+  const handleViewChange = useCallback((view: TCalendarView) => {
+    navigate({
+      search: (prev) => ({ ...prev, view }),
+      replace: true,
+    });
+  }, [navigate]);
+  
+  return (
+    <InnoCalendar
+      events={loaderData.events}
+      initialView={searchParams.view ?? 'week'}
+      initialDate={parseDate(searchParams.selectedDate)}
+      onDateChange={handleDateChange}
+      onViewChange={handleViewChange}
+    />
+  );
+}
+```
+
+### Date Range Helpers
+
+```tsx
+export function getViewDateRange(date: Date, view: TCalendarView): { startDate: Date; endDate: Date } {
+  const d = new Date(date);
+  
+  switch (view) {
+    case 'day':
+      return {
+        startDate: startOfDay(d),
+        endDate: endOfDay(d),
+      };
+    case 'week':
+    case 'timeline-week':
+      return {
+        startDate: startOfWeek(d),
+        endDate: endOfWeek(d),
+      };
+    case 'month':
+      // Include surrounding weeks for month grid
+      const monthStart = startOfMonth(d);
+      const monthEnd = endOfMonth(d);
+      return {
+        startDate: startOfWeek(monthStart),
+        endDate: endOfWeek(monthEnd),
+      };
+    case 'year':
+      return {
+        startDate: new Date(d.getFullYear(), 0, 1),
+        endDate: new Date(d.getFullYear(), 11, 31),
+      };
+    default:
+      return {
+        startDate: startOfMonth(d),
+        endDate: endOfMonth(d),
+      };
+  }
+}
+
+export function formatDateForApi(date: Date): string {
+  return date.toISOString().split('T')[0]; // YYYY-MM-DD
+}
+```
+
+---
+
+## Dialog Integration
+
+### With Global Dialog Store
+
+```tsx
+import { useDialog } from '@/hooks/use-dialog';
+import dayjs from 'dayjs';
+
+function CalendarWithDialogs() {
+  const { initialize } = useDialog();
+  
+  const handleSlotSelect = useCallback((selection: ISelectionResult) => {
+    initialize({
+      title: 'Create Event',
+      children: (
+        <EventForm
+          startDate={dayjs(selection.startDate).format('YYYY-MM-DDTHH:mm:ss')}
+          endDate={dayjs(selection.endDate).format('YYYY-MM-DDTHH:mm:ss')}
+        />
+      ),
+      classes: { content: 'max-w-3xl' },
+    });
+  }, [initialize]);
+  
+  const handleEventClick = useCallback((event: CalendarEvent) => {
+    initialize({
+      title: 'Event Details',
+      children: <EventDetailsDialog eventId={event.id} />,
+    });
+  }, [initialize]);
+  
+  const handleEventDrop = useCallback((result: IDropResult) => {
+    initialize({
+      title: 'Reschedule Event',
+      children: (
+        <EventForm
+          id={result.event.id}
+          startDate={dayjs(result.newStartDate).format('YYYY-MM-DDTHH:mm:ss')}
+          endDate={dayjs(result.newEndDate).format('YYYY-MM-DDTHH:mm:ss')}
+        />
+      ),
+    });
+  }, [initialize]);
+  
+  return (
+    <InnoCalendar
+      events={events}
+      onSlotSelect={handleSlotSelect}
+      onEventClick={handleEventClick}
+      onEventDrop={handleEventDrop}
+    />
+  );
+}
+```
+
+---
+
+## Custom Event Popover
+
+```tsx
+function CustomPopover({ 
+  event, 
+  onClose 
+}: { 
+  event: CalendarEvent; 
+  onClose: () => void; 
+}) {
+  const { data: details, isLoading } = useQuery({
+    queryKey: ['event-details', event.id],
+    queryFn: () => fetchEventDetails(event.id),
+  });
+  
+  if (isLoading) {
+    return <div className="p-4 animate-pulse">Loading...</div>;
+  }
+  
+  return (
+    <div className="p-4 space-y-3 min-w-[300px]">
+      {/* Header */}
+      <div className="flex items-start justify-between">
+        <div>
+          <h3 className="font-semibold text-lg">{event.title}</h3>
+          {event.scheduleTypeName && (
+            <span className="text-xs px-2 py-0.5 rounded bg-muted">
+              {event.scheduleTypeName}
+            </span>
+          )}
+        </div>
+        <button onClick={onClose} className="text-muted-foreground">
+          ✕
+        </button>
+      </div>
+      
+      {/* Time */}
+      <div className="text-sm text-muted-foreground">
+        {formatDateRange(event.startDate, event.endDate)}
+      </div>
+      
+      {/* Description */}
+      {event.description && (
+        <p className="text-sm">{event.description}</p>
+      )}
+      
+      {/* Participants */}
+      {details?.participants?.length > 0 && (
+        <div className="flex -space-x-2">
+          {details.participants.map((p) => (
+            <img 
+              key={p.id} 
+              src={p.avatar} 
+              alt={p.name}
+              className="w-8 h-8 rounded-full border-2 border-white"
+            />
+          ))}
+        </div>
+      )}
+      
+      {/* Actions */}
+      <div className="flex gap-2 pt-3 border-t">
+        <button 
+          onClick={() => handleEdit(event)}
+          className="flex-1 px-3 py-1.5 text-sm border rounded hover:bg-muted"
+        >
+          Edit
+        </button>
+        <button 
+          onClick={() => handleDelete(event)}
+          className="px-3 py-1.5 text-sm text-destructive border border-destructive rounded hover:bg-destructive/10"
+        >
+          Delete
+        </button>
+      </div>
+    </div>
+  );
+}
+
+// Usage
+<InnoCalendar
+  events={events}
+  renderPopover={({ event, onClose }) => (
+    <CustomPopover event={event} onClose={onClose} />
+  )}
+/>
+```
+
+---
+
+## Working Hours Configuration
+
+```tsx
+// Default working hours
+const DEFAULT_WORKING_HOURS: TWorkingHours = {
+  0: { enabled: false, from: 8, to: 17 }, // Sunday - disabled
+  1: { enabled: true, from: 8, to: 17 },  // Monday
+  2: { enabled: true, from: 8, to: 17 },  // Tuesday
+  3: { enabled: true, from: 8, to: 17 },  // Wednesday
+  4: { enabled: true, from: 8, to: 17 },  // Thursday
+  5: { enabled: true, from: 8, to: 17 },  // Friday
+  6: { enabled: true, from: 8, to: 12 },  // Saturday - half day
+};
+
+// Pass to calendar
+<InnoCalendar
+  events={events}
+  preferencesConfig={{
+    defaults: {
+      workingHours: DEFAULT_WORKING_HOURS,
+      showWorkingHoursOnly: false,
+    },
+  }}
+/>
+```
+
+---
+
+## Preferences Configuration
+
+```tsx
+interface IPreferencesConfig {
+  defaults?: {
+    badgeVariant?: 'dot' | 'colored' | 'mixed';
+    slotDuration?: 15 | 30 | 60;
+    visibleHours?: { start: number; end: number };
+    workingHours?: TWorkingHours;
+    showWorkingHoursOnly?: boolean;
+  };
+  locked?: {
+    badgeVariant?: boolean;
+    slotDuration?: boolean;
+    visibleHours?: boolean;
+    workingHours?: boolean;
+    showWorkingHoursOnly?: boolean;
+  };
+}
+
+// Example: Lock certain settings
+<InnoCalendar
+  events={events}
+  preferencesConfig={{
+    defaults: {
+      badgeVariant: 'colored',
+      slotDuration: 30,
+    },
+    locked: {
+      badgeVariant: true,  // Users cannot change
+      slotDuration: false, // Users can change
+    },
+  }}
+/>
+```
+
+---
+
+## CSS Custom Properties
+
+The package uses CSS custom properties for theming. Override in your styles:
+
+```css
+:root {
+  /* Core colors */
+  --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;
+}
+
+/* Dark mode */
+.dark {
+  --inno-border-color: #374151;
+  --inno-background: #111827;
+  --inno-foreground: #f9fafb;
+  --inno-muted: #1f2937;
+  --inno-muted-foreground: #9ca3af;
+}
+```
+
+---
+
+## Complete Implementation Example
+
+```tsx
+// features/agenda/components/agenda-page.tsx
+import { useDialog } from '@/hooks/use-dialog';
+import { useCurrentUser } from '@/hooks/use-current-user';
+import { getRouteApi } from '@tanstack/react-router';
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import dayjs from 'dayjs';
+
+import {
+  InnoCalendar,
+  type CalendarEvent,
+  type ISelectionResult,
+  type TCalendarView,
+  type IDropResult,
+  type IScheduleType,
+} from '@innosolutions/inno-calendar';
+import '@innosolutions/inno-calendar/styles';
+
+import { transformApiEvents, transformParticipants } from '../transformers';
+import { getViewDateRange, formatDateForApi } from '../helpers';
+import { EventPopover } from './event-popover';
+import { EventForm } from '../forms/event-form';
+import { CalendarSettings } from './calendar-settings';
+import { UserSelect, ScheduleTypeSelect } from './filters';
+
+const routeApi = getRouteApi('/_protectedLayout/agenda/');
+
+export function AgendaPage() {
+  const { t } = useTranslation();
+  const { initialize } = useDialog();
+  const navigate = routeApi.useNavigate();
+  const searchParams = routeApi.useSearch();
+
+  // Role-based access
+  const { user } = useCurrentUser();
+  const isAdmin = user?.roles?.some(
+    (r) => r.name === 'Admin' || r.name === 'Super Admin'
+  );
+
+  // Route data
+  const loaderData = routeApi.useLoaderData();
+  const rawEvents = loaderData?.data?.data ?? [];
+  const rawParticipants = loaderData?.participants?.data ?? [];
+  const rawScheduleTypes = loaderData?.scheduleTypes?.data ?? [];
+
+  // Transform data
+  const calendarEvents = useMemo(
+    () => transformApiEvents(rawEvents, rawScheduleTypes),
+    [rawEvents, rawScheduleTypes]
+  );
+
+  const calendarUsers = useMemo(
+    () => transformParticipants(rawParticipants),
+    [rawParticipants]
+  );
+
+  const scheduleTypes = useMemo(
+    () => rawScheduleTypes.map((st) => ({
+      id: st.id,
+      name: st.resourceKey ?? st.code ?? `Type ${st.id}`,
+      color: st.colorHex,
+    })) as IScheduleType[],
+    [rawScheduleTypes]
+  );
+
+  // Parse URL params
+  const initialDate = useMemo(() => {
+    if (searchParams.selectedDate) {
+      const parsed = new Date(searchParams.selectedDate);
+      if (!Number.isNaN(parsed.getTime())) return parsed;
+    }
+    return new Date();
+  }, [searchParams.selectedDate]);
+
+  const initialView = searchParams.view as TCalendarView | undefined;
+
+  // Handlers
+  const handleSlotSelect = useCallback(
+    (selection: ISelectionResult) => {
+      initialize({
+        title: t('actionText.addAgenda'),
+        children: (
+          <EventForm
+            startDate={dayjs(selection.startDate).format('YYYY-MM-DDTHH:mm:ss')}
+            endDate={dayjs(selection.endDate).format('YYYY-MM-DDTHH:mm:ss')}
+          />
+        ),
+        classes: { content: 'max-w-3xl !h-fit' },
+      });
+    },
+    [initialize, t]
+  );
+
+  const handleSlotClick = useCallback(
+    (date: Date, hour?: number) => {
+      const startDate = new Date(date);
+      if (typeof hour === 'number') {
+        startDate.setHours(hour, 0, 0, 0);
+      }
+      const endDate = new Date(startDate);
+      endDate.setHours(endDate.getHours() + 1);
+      handleSlotSelect({ startDate, endDate });
+    },
+    [handleSlotSelect]
+  );
+
+  const handleAddEvent = useCallback(() => {
+    handleSlotClick(new Date());
+  }, [handleSlotClick]);
+
+  const handleEventDrop = useCallback(
+    (result: IDropResult) => {
+      initialize({
+        title: t('forms.agenda.editMeeting'),
+        children: (
+          <EventForm
+            id={result.event.id}
+            startDate={dayjs(result.newStartDate).format('YYYY-MM-DDTHH:mm:ss')}
+            endDate={dayjs(result.newEndDate).format('YYYY-MM-DDTHH:mm:ss')}
+          />
+        ),
+        classes: { content: 'max-w-3xl !h-fit' },
+      });
+    },
+    [initialize, t]
+  );
+
+  const handleDateChange = useCallback(
+    (newDate: Date, view: TCalendarView) => {
+      const { startDate, endDate } = getViewDateRange(newDate, view);
+      navigate({
+        search: (prev) => ({
+          ...prev,
+          selectedDate: dayjs(newDate).format('YYYY-MM-DD'),
+          startDate: formatDateForApi(startDate),
+          endDate: formatDateForApi(endDate),
+        }),
+        replace: true,
+      });
+    },
+    [navigate]
+  );
+
+  const handleViewChange = useCallback(
+    (newView: TCalendarView) => {
+      const { startDate, endDate } = getViewDateRange(initialDate, newView);
+      navigate({
+        search: (prev) => ({
+          ...prev,
+          view: newView,
+          startDate: formatDateForApi(startDate),
+          endDate: formatDateForApi(endDate),
+        }),
+        replace: true,
+      });
+    },
+    [navigate, initialDate]
+  );
+
+  const renderPopover = useCallback(
+    ({ event, onClose }: { event: CalendarEvent; onClose: () => void }) => (
+      <EventPopover eventId={event.id} onClose={onClose} />
+    ),
+    []
+  );
+
+  return (
+    <div className="h-full">
+      <InnoCalendar
+        events={calendarEvents}
+        users={calendarUsers}
+        scheduleTypes={scheduleTypes}
+        initialView={initialView}
+        initialDate={initialDate}
+        initialWorkingHoursView={searchParams.workingHoursView ?? 'default'}
+        renderPopover={renderPopover}
+        onSlotSelect={handleSlotSelect}
+        onSlotClick={handleSlotClick}
+        onAddEvent={handleAddEvent}
+        onEventDrop={handleEventDrop}
+        onDateChange={handleDateChange}
+        onViewChange={handleViewChange}
+        settingsContent={isAdmin ? <CalendarSettings /> : undefined}
+        filterContent={
+          <div className="flex items-center gap-2">
+            {calendarUsers.length > 0 && <UserSelect />}
+            {scheduleTypes.length > 0 && <ScheduleTypeSelect />}
+          </div>
+        }
+      />
+    </div>
+  );
+}
+```
+
+---
+
+## Migration from FullCalendar
+
+```tsx
+// Before (FullCalendar)
+import FullCalendar from '@fullcalendar/react';
+import dayGridPlugin from '@fullcalendar/daygrid';
+import timeGridPlugin from '@fullcalendar/timegrid';
+
+<FullCalendar
+  plugins={[dayGridPlugin, timeGridPlugin]}
+  initialView="timeGridWeek"
+  events={events}
+  eventClick={(info) => handleClick(info.event)}
+  slotMinTime="08:00:00"
+  slotMaxTime="18:00:00"
+  businessHours={{ daysOfWeek: [1,2,3,4,5], startTime: '09:00', endTime: '17:00' }}
+/>
+
+// After (@inno/calendar)
+import { InnoCalendar } from '@innosolutions/inno-calendar';
+import '@innosolutions/inno-calendar/styles';
+
+<InnoCalendar
+  events={transformedEvents}
+  initialView="week"
+  onEventClick={(event) => handleClick(event)}
+  preferencesConfig={{
+    defaults: {
+      visibleHours: { start: 8, end: 18 },
+      workingHours: {
+        0: { enabled: false, from: 9, to: 17 },
+        1: { enabled: true, from: 9, to: 17 },
+        2: { enabled: true, from: 9, to: 17 },
+        3: { enabled: true, from: 9, to: 17 },
+        4: { enabled: true, from: 9, to: 17 },
+        5: { enabled: true, from: 9, to: 17 },
+        6: { enabled: false, from: 9, to: 17 },
+      },
+    },
+  }}
+/>
+```
+
+---
+
+## Exports Reference
+
+```tsx
+// Main component
+export { InnoCalendar } from '@innosolutions/inno-calendar';
+
+// Provider & hooks
+export {
+  InnoCalendarProvider,
+  useInnoCalendar,
+  useOptionalInnoCalendar,
+} from '@innosolutions/inno-calendar';
+
+// View components
+export {
+  DayView,
+  WeekView,
+  MonthView,
+  YearView,
+  AgendaView,
+  TimelineView,
+} from '@innosolutions/inno-calendar';
+
+// Header & settings
+export {
+  CalendarHeader,
+  SlotDurationSetting,
+  VisibleHoursSetting,
+  BadgeVariantSetting,
+  WorkingHoursSetting,
+} from '@innosolutions/inno-calendar';
+
+// Filters
+export {
+  UserFilter,
+  ScheduleTypeFilter,
+} from '@innosolutions/inno-calendar';
+
+// Types
+export type {
+  CalendarEvent,
+  TCalendarView,
+  TEventColor,
+  TBadgeVariant,
+  TWorkingHours,
+  IWorkingHoursDay,
+  TSlotDuration,
+  ICalendarUser,
+  IScheduleType,
+  ISelectionResult,
+  IDropResult,
+  IVisibleHours,
+  IPreferencesConfig,
+} from '@innosolutions/inno-calendar';
+```
+
+---
+
+## Troubleshooting
+
+### Styles not applying
+
+Ensure you import the styles:
+
+```tsx
+import '@innosolutions/inno-calendar/styles';
+```
+
+### Working hours striped pattern not showing
+
+The `.bg-calendar-disabled-hour` class requires CSS custom properties. Import styles or add:
+
+```css
+.bg-calendar-disabled-hour {
+  background-image: repeating-linear-gradient(
+    -60deg,
+    var(--inno-border-color, #e5e7eb) 0 0.5px,
+    transparent 0.5px 8px
+  );
+}
+```
+
+### TypeScript errors with custom event data
+
+Use the generic parameter:
+
+```tsx
+import type { CalendarEvent } from '@innosolutions/inno-calendar';
+
+interface MyData {
+  customField: string;
+}
+
+const events: CalendarEvent<MyData>[] = [...];
+
+<InnoCalendar<MyData>
+  events={events}
+  onEventClick={(event) => {
+    // event.data is typed as MyData | undefined
+    console.log(event.data?.customField);
+  }}
+/>
+```
+
+### Events not filtering
+
+Ensure you're using `filteredEvents` from context, not the raw `events`:
+
+```tsx
+const { filteredEvents } = useInnoCalendar();
+// Use filteredEvents for rendering, not the original events prop
+```