@innosolutions/inno-calendar 1.0.33 → 1.0.34

package/AGENT.md

@@ -1,15 +1,17 @@
 # @innosolutions/inno-calendar — AI Agent Reference
 
-> **Version**: 1.0.27 · **Runtime**: React 18+ / TypeScript · **Build**: Vite (library mode) + vite-plugin-dts
+> **Version**: 1.0.33 · **Runtime**: React 18+ / TypeScript · **Build**: Vite (library mode) + vite-plugin-dts
 > **Published as**: `@innosolutions/inno-calendar` on npm (public)
 
-This document gives an AI coding agent all the context it needs to work in this repo correctly. Treat it as the single source of truth for types, props, exports, patterns, and integration.
+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.
 
 ---
 
 ## 1. What This Package Is
 
-A headless-first, fully customizable React calendar package extracted from **brick-erp-v2's agenda-v2 module**. It provides:
+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
@@ -20,99 +22,17 @@ A headless-first, fully customizable React calendar package extracted from **bri
 - 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.)
 
-### Consumer App: PromoSport ERP
-
-The primary consumer is `promosport-erp` (Next.js + tRPC). Its calendar-v2 module lives in:
-```
-promosport-erp/src/app/[locale]/(protected)/calendar-v2/_components/
-```
-
-Key files in the consumer:
-| File | Purpose |
-|------|---------|
-| `calendar-v2.main.tsx` | Wires InnoCalendar to tRPC queries, URL state (nuqs), filters |
-| `transformers.ts` | API data → `CalendarEvent<CalendarEventData>[]` transforms |
-| `calendar-filters.tsx` | Server-side filter panel (Sites/Events/Participants) via nuqs |
-| `event-popover.tsx` | Custom popover content rendered via `renderPopover` prop |
-| `create-drawer.tsx` | Header dropdown for creating event types |
-| `event-type-selector.tsx` | Dialog shown on slot select to choose event type |
-| `helpers.ts` | Date range computation per view for API fetch alignment |
-| `settings.tsx` | Calendar settings panel (slot duration, working hours, visible hours) |
-| `filter-colors.ts` | Color palette for event-linked filter contributions |
-
----
-
-## 2. Package Structure
-
-```
-src/
-  index.ts                          # Main barrel export
-  utils.ts                          # cn() helper re-export
-
-  core/                             # Headless core — NO UI dependencies
-    index.ts                        # Core barrel export
-    types.ts                        # ALL type definitions (~1140 lines)
-    constants.ts                    # Defaults, view configs, color maps
-    context/
-      calendar-context.tsx          # Base CalendarProvider
-      inno-calendar-provider.tsx    # Full provider with filtering/prefs
-      drag-drop-context.tsx         # Drag & drop state
-      slot-selection-context.tsx    # Drag-to-select state
-    hooks/
-      use-calendar.ts              # Main calendar state hook
-      use-calendar-time-config.ts  # Time grid config hook
-      use-preferences.ts           # User preferences hook
-      use-slot-selection.ts        # Slot selection hook
-    preferences/                    # Advanced preferences with locking
-    utils/
-      date-utils.ts                # Pure date functions (native Date API)
-      event-utils.ts               # Event filtering/sorting
-      grid-utils.ts                # View title, date range, navigation
-      position-utils.ts            # Event overlap/stacking
-
-  components/                       # UI Components
-    inno-calendar.tsx              # Main <InnoCalendar> component (~520 lines)
-    calendar.tsx                    # Lower-level <Calendar> component
-    integrated-calendar.tsx         # Legacy alias
-    event/
-      event-card.tsx               # EventCard, EventBlock, MultiDayEventBar (~1220 lines)
-      event-popover.tsx            # Built-in popover (overridable via renderPopover)
-    header/
-      calendar-header.tsx          # Navigation, view switcher, settings
-      components/
-        date-navigator.tsx         # Prev/Today/Next buttons
-        today-button.tsx           # Today button
-    views/
-      day-view.tsx                 # Single-day time grid
-      week-view.tsx                # 7-day time grid
-      month-view.tsx               # Month grid with overflow
-      year-view.tsx                # Year overview
-      agenda-view.tsx              # Flat event list grouped by day
-      timeline-view.tsx            # Resource timeline (rows per user)
-    primitives/
-      selectable-slot.tsx          # Drag-to-select time slot
-      multi-day-banner.tsx         # All-day / multi-day event strip
-      calendar-timeline.tsx        # Timeline grid primitives
-    filters/                        # Built-in filter sidebar components
-    settings/                       # Preference controls (slot duration, etc.)
-    widget/
-      agenda-widget.tsx            # Dashboard calendar widget
-      agenda-dropdown.tsx          # Dropdown variant of widget
-    ui/                            # Shadcn-style base components (button, tooltip, popover, etc.)
-
-  presets/                          # Pre-built configurations
-    default/                        # DefaultCalendar
-    tailwind/                       # TailwindCalendar
-
-  styles/
-    index.css                       # Base CSS entry
-    calendar.css                    # Calendar-specific styles
-```
+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.).
 
 ---
 
-## 3. npm Scripts
+## 2. npm Scripts
 
 ```bash
 npm run dev          # Vite dev server
@@ -124,30 +44,31 @@ npm run format       # Biome format
 
 ---
 
-## 4. Package Exports
+## 3. Package Exports
 
 ```jsonc
 {
-  ".":            "dist/index.{mjs,cjs,d.ts}",   // Full API
-  "./core":       "dist/core/index.{mjs,cjs}",    // Headless core only
+  ".": "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
+  "./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
 }
 ```
 
-Consumer imports:
+Typical consumer imports:
+
 ```tsx
-import { InnoCalendar, type CalendarEvent } from '@innosolutions/inno-calendar';
-import '@innosolutions/inno-calendar/styles';
+import { InnoCalendar, type CalendarEvent } from "@innosolutions/inno-calendar";
+import "@innosolutions/inno-calendar/styles";
 ```
 
 ---
 
-## 5. Core Types (types.ts)
+## 4. Core Types (types.ts)
 
 ### CalendarEvent\<TData\>
 
@@ -163,39 +84,57 @@ interface CalendarEvent<TData = Record<string, unknown>> extends IBaseEvent {
 
   // Optional display fields
   description?: string;
-  color?: TEventColor;        // 'blue' | 'green' | 'red' | 'yellow' | 'purple' | 'orange' | 'pink' | 'teal' | 'gray' | 'indigo'
-  hexColor?: string;           // Hex override (takes precedence over color)
+  color?: TEventColor; // 'blue' | 'green' | 'red' | ... | 'indigo'
+  hexColor?: string; // Hex override (takes precedence over color)
   isAllDay?: boolean;
   isMultiDay?: boolean;
   isCanceled?: boolean;
   isRecurring?: boolean;
-  resourceId?: string;         // For resource/timeline views
-  data?: TData;                // Consumer's custom data bag
-
-  // Deprecated (migrate to data.*)
-  meetingTookPlace?: boolean;
-  scheduleTypeId?: number;
-  scheduleTypeName?: string;
-  scheduleTypeCode?: string;
-  cancelReason?: string | null;
-  isAccepted?: boolean;
-  companyId?: number;
-  opportunityId?: number | null;
-  propertyId?: number | null;
-  projectId?: number | null;
-  contactId?: number | null;
-  participants?: ICalendarUser[];
-  user?: ICalendarUser | null;
+  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;
 }
 ```
 
+**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.
+
 ### TCalendarView
 
 ```typescript
 type TCalendarView =
-  | 'day' | 'week' | 'month' | 'year' | 'agenda'
-  | 'resource-day' | 'resource-week'
-  | 'timeline-day' | 'timeline-3day' | 'timeline-week';
+  | "day"
+  | "week"
+  | "month"
+  | "year"
+  | "agenda"
+  | "resource-day"
+  | "resource-week"
+  | "timeline-day"
+  | "timeline-3day"
+  | "timeline-week";
 ```
 
 ### ICalendarUser
@@ -204,7 +143,7 @@ type TCalendarView =
 interface ICalendarUser<TData = Record<string, unknown>> {
   id: string;
   name: string;
-  email?: string;    // Optional — employees endpoint does NOT return email
+  email?: string;
   avatar?: string;
   data?: TData;
 }
@@ -234,21 +173,21 @@ interface IScheduleType<TData = Record<string, unknown>> {
 interface ISelectionResult {
   startDate: Date;
   endDate: Date;
-  resourceId?: string;   // Set when selecting in resource/timeline views
+  resourceId?: string; // Set when selecting in resource/timeline views
 }
 ```
 
 ### TBadgeVariant
 
 ```typescript
-type TBadgeVariant = 'dot' | 'colored' | 'mixed';
+type TBadgeVariant = "dot" | "colored" | "mixed";
 ```
 
 ---
 
-## 6. InnoCalendar Props
+## 5. InnoCalendar Props
 
-The main `<InnoCalendar>` component (inno-calendar.tsx) accepts:
+The main `<InnoCalendar>` component accepts:
 
 ```typescript
 interface InnoCalendarProps<TEventData> {
@@ -258,12 +197,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: today
+  initialSelectedUserId?: string | "all";
   initialScheduleTypeIds?: number[];
   initialParticipantIds?: string[];
-  initialWorkingHoursView?: 'default' | 'enabled' | 'disabled';
+  initialWorkingHoursView?: "default" | "enabled" | "disabled";
   initialSearchQuery?: string;
 
   // === PREFERENCES ===
@@ -280,27 +219,30 @@ interface InnoCalendarProps<TEventData> {
 
   // === UI OPTIONS ===
   className?: string;
-  showHeader?: boolean;                  // default: true
-  minSelectionMinutes?: number;          // default: 30
-  showMoreEventsInPopover?: boolean;     // default: false — "+N more" opens popover vs day view
+  showHeader?: boolean; // default: true
+  minSelectionMinutes?: number; // default: 30
+  showMoreEventsInPopover?: boolean; // default: false
 
   // === CUSTOM RENDERING ===
-  renderPopover?: (props: { event: CalendarEvent<TEventData>; onClose: () => void }) => ReactNode;
+  renderPopover?: (props: {
+    event: CalendarEvent<TEventData>;
+    onClose: () => void;
+  }) => ReactNode;
 
   // === EXTENSIBILITY ===
   slots?: ICalendarSlots<TEventData>;
   classNames?: ICalendarClassNames;
 
   // === CUSTOM CONTENT SLOTS ===
-  settingsContent?: ReactNode;           // Settings panel content
-  filterContent?: ReactNode;             // Filter sidebar content
-  headerActions?: ReactNode;             // Replaces default add button in header
+  settingsContent?: ReactNode;
+  filterContent?: ReactNode;
+  headerActions?: ReactNode;
 }
 ```
 
 ---
 
-## 7. Slots System (ICalendarSlots)
+## 6. Slots System (ICalendarSlots)
 
 Every visual region can be replaced:
 
@@ -344,7 +286,7 @@ interface ICalendarSlots<TEventData, TScheduleTypeData, TResourceData> {
 
 ---
 
-## 8. ClassNames API (ICalendarClassNames)
+## 7. ClassNames API (ICalendarClassNames)
 
 Granular CSS class overrides merged via `cn()`:
 
@@ -400,177 +342,200 @@ interface ICalendarClassNames {
 
 ---
 
-## 9. EventBlock Rich Data Feature
+## 8. EventCard Rich Data Display
 
-The `EventBlock` component (used in day/week time grids) extracts and displays rich data from `event.data`:
+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:
 
 ```typescript
-// Fields extracted from event.data
+// Fields extracted from event.data (safe runtime access, then deprecated fallback)
 const eventData = event.data as Record<string, unknown> | undefined;
-const scheduleTypeName = event.scheduleTypeName || (eventData?.typeName as string);
+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 locationStr = [siteName, siteCity].filter(Boolean).join(", ");
 ```
 
 Display rules based on event duration:
-| Duration | Shows |
-|----------|-------|
-| < 25 min | Title only (centered) |
-| 25–44 min | Title + time (with ClockIcon) |
-| ≥ 45 min | Full details: title+type, product, participants, time, location |
+
+| Duration  | Shows                                                             |
+| --------- | ----------------------------------------------------------------- |
+| < 25 min  | Title only (centered)                                             |
+| 25–44 min | Title + time (with ClockIcon)                                     |
+| ≥ 45 min  | Full details: title + type, product, participants, time, location |
 
 The title line format: `{title}` + optional ` - {scheduleTypeName}` in lighter weight.
 
 ---
 
-## 10. PromoSport Integration Patterns
+## 9. Integration Guide
 
-### Data Flow
+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.
 
-```
-API (calendar/events) → tRPC router → React Query
-  ↓
-transformCalendarEvents() in transformers.ts
-  ↓
-CalendarEvent<CalendarEventData>[] → <InnoCalendar events={...} />
-```
+### 9.1 Transform API Data → CalendarEvent
 
-### CalendarEventData (PromoSport's TData)
+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.
 
 ```typescript
-interface CalendarEventData {
+// 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;
-  typeId: number;           // 2=Training, 3=Vacation, 4=Group, 5=Intern, 7=Private, 8=Absence
-  typeName: string;
-  groupId?: number;
-  groupTitle?: string;
-  productName?: string;
-  nrParticipant?: number;
-  monitors?: string[];
-  siteName?: string;
-  sitePostalCode?: string;
-  siteCity?: string;
-  siteStreet?: string;
-  holdingConfirmed?: boolean;
+  agendaTypeId: number;
+  agendaTypeName: string;
+  companyId: number;
+  meetingTookPlace: boolean;
+  isAccepted: boolean;
   cancelReason?: string;
+  participantNames: string[];
 }
-```
-
-### Event Type Color Map
 
-```typescript
-const eventTypeColorMap: Record<number, TEventColor> = {
-  2: 'blue',    // Training Session
-  3: 'purple',  // Vacation
-  4: 'green',   // Event Group Session
-  5: 'orange',  // Intern Meet
-  7: 'red',     // Private Event
-  8: 'pink',    // Absence
-};
+/**
+ * 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),
+    ),
+
+    // 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) ?? [],
+    },
+  }));
+}
 ```
 
-### Monitor Resolution
-
-The API returns monitor names as strings (`"John Doe"`). The calendar needs user IDs for timeline views. The flow:
+### 9.2 Filtering Strategies
 
-1. `getEventParticipants` tRPC endpoint calls `data/employees` → returns `Options[]` with `{ id, name }` (no email)
-2. `buildMonitorLookup(participants)` builds `Map<string, string>` (lowercased name → id)
-3. `transformCalendarEvents()` resolves each monitor name to an ID via the lookup
-4. Fallback: slugified name if no match (`"john-doe"`)
+The package supports **two** filtering approaches — pick whichever fits:
 
-### Filtering Architecture
+| 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 |
 
-PromoSport uses **server-side filtering via URL params** (not InnoCalendar's built-in client-side filtering):
+For server-side filtering, build a filter panel as a regular form component and
+pass it via `filterContent`:
 
-```
-nuqs URL state (?sites=1,2&events=5&participants=42)
-  ↓
-calendar-v2.main.tsx reads filterParams
-  ↓
-tRPC query key includes filter params → API returns filtered data
-  ↓
-InnoCalendar renders the already-filtered events
+```tsx
+<InnoCalendar
+  events={filteredEventsFromApi}
+  filterContent={<MyFilterPanel />}
+/>
 ```
 
-The `<CalendarFilters>` component is passed via `filterContent` prop and writes to URL state independently.
+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.
 
-### Event Popover
+### 9.3 Custom Event Popover
 
-Custom popover content is passed via `renderPopover`:
+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`:
 
 ```tsx
 <InnoCalendar
   renderPopover={({ event, onClose }) => (
-    <EventPopoverContent event={event} onClose={onClose} />
+    <MyEventPopover event={event} onClose={onClose} />
   )}
 />
 ```
 
-The popover:
-1. Fetches full event details via `getCalendarEventById` (list endpoint has minimal data)
-2. Shows type-specific details (vacation: employee + dates; group: participants, monitors, site, time)
-3. **Excludes monitors from the participants list** (case-insensitive name match filtering)
-4. Shows action buttons based on type + state (Cancel, Edit, Confirm Held)
+A custom popover typically:
 
-### Header Actions
+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.)
 
-Custom create dropdown replaces the default add button:
+### 9.4 Custom Header Actions
+
+Replace the default "Add Event" button with your own header actions (dropdown
+menus, multiple create buttons per event type, etc.):
 
 ```tsx
-<InnoCalendar headerActions={<CreateDrawer />} />
+<InnoCalendar headerActions={<MyCreateDropdown />} />
 ```
 
-### Slot Selection → Event Type Dialog
+### 9.5 Slot Selection → Event Creation
 
-When a user drags a time slot, `onSlotSelect` opens a dialog with event type buttons:
+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:
 
 ```tsx
 onSlotSelect={(selection) => {
-  dialog.initialize({
-    title: t('buttons.create'),
-    children: <EventTypeSelector startDate={selection.startDate} endDate={selection.endDate} />,
-  });
+  // Option A: open a create form directly with pre-filled dates
+  openCreateForm({ startDate: selection.startDate, endDate: selection.endDate });
+
+  // Option B: show an event type picker first, then route to the right form
+  openEventTypePicker(selection);
 }}
 ```
 
----
-
-## 11. API Endpoints Used by PromoSport
+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.
 
-| tRPC Procedure | Backend Endpoint | Returns | Notes |
-|----------------|------------------|---------|-------|
-| `calendarRouter.getCalendarEvents` | `calendar/events` | `CalendarEvents[]` | Main event list, filtered by date/sites/participants/events |
-| `calendarRouter.getCalendarEventById` | `calendar/events/{id}` | `CalendarEventById` | Full details for popover |
-| `calendarRouter.getEventTypes` | `calendar/events/types` | `Options[]` | Event type categories |
-| `calendarRouter.getEventParticipants` | `data/employees` | `Options[]` | Employee list (`{ id, name }`, no email) |
-| `dataRouter.getSites` | `data/sites` | Sites with address | For filter sidebar |
-| `dataRouter.getEvents` | `data/events` | Events with monitors/sites | For event filter with contribution tracking |
+### 9.6 Settings Panel
 
-### EventParticipants Interface
+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:
 
-```typescript
-// Matches the employees endpoint response shape
-interface EventParticipants {
-  id: number;
-  name: string;           // Full name ("Aaron CIMANGA")
-  description?: string;   // Always null from employees endpoint
-  isArchived?: boolean;
-}
+```tsx
+<InnoCalendar settingsContent={<MySettingsPanel />} />
 ```
 
-**Important**: No `firstName`, `lastName`, or `email` fields. Always use `name` directly.
-
----
+Most apps will customize this to include project-specific preferences or
+integrate with a persistence layer that saves settings per user.
 
-## 12. Working Hours & Disabled Slots
+### 9.7 Working Hours & Disabled Slots
 
-Non-working-hour time slots get a CSS hatching pattern. The consumer provides this via CSS:
+Non-working-hour time slots receive the CSS class `inno-calendar-disabled-hour`.
+The consumer provides the hatching/dimming style:
 
 ```css
-/* In promosport-erp/calendar-v2.css */
 .inno-calendar-disabled-hour,
 .bg-calendar-disabled-hour {
   background-image: repeating-linear-gradient(
@@ -581,11 +546,12 @@ Non-working-hour time slots get a CSS hatching pattern. The consumer provides th
 }
 ```
 
-Working hours are configurable per day via the settings panel (CalendarSettingsContent).
+Working hours are configurable per day via the built-in settings controls or
+programmatically via `useInnoCalendar().setWorkingHours()`.
 
 ---
 
-## 13. Context Hooks
+## 10. Context Hooks
 
 ### useInnoCalendar\<TEventData\>()
 
@@ -625,24 +591,26 @@ The main context hook. Returns:
 
 ---
 
-## 14. File Naming Conventions
+## 11. File Naming Conventions
+
+All files use **kebab-case** naming:
 
-All files use **kebab-case** naming (NOT PascalCase — the copilot-instructions.md is aspirational, the actual codebase uses kebab-case):
+| 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`                             |
 
-| 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` |
+Folders also use kebab-case: `core/`, `components/`, `presets/`.
 
 ---
 
-## 15. Styling
+## 12. Styling
 
 - **TailwindCSS 4+** with `cn()` helper (clsx + tailwind-merge)
 - **class-variance-authority (CVA)** for component variants
@@ -652,7 +620,7 @@ All files use **kebab-case** naming (NOT PascalCase — the copilot-instructions
 
 ---
 
-## 16. Biome Configuration
+## 13. Biome Configuration
 
 - Tabs for indentation
 - Single quotes
@@ -664,15 +632,15 @@ Run before commits: `npm run format && npm run lint && npm run typecheck`
 
 ---
 
-## 17. Critical Rules
+## 14. Critical Rules
 
 1. **Never add external dependencies to `core/`** — only React and native APIs
-2. **`event-card.tsx` must match brick-erp-v2/agenda-v2 styling** — it's the source of truth
-3. **Rich data in EventBlock reads from `event.data.*`** — not top-level deprecated fields
-4. **Employee data has NO email** — the `data/employees` endpoint returns `{ id, name }` only
-5. **Monitors and participants are separate** — in popovers, filter monitors out of participants by case-insensitive name match
-6. **Consumers handle data fetching** — this package never calls APIs
-7. **URL-based filtering is the consumer's responsibility** — InnoCalendar just renders what it receives
-8. **All public APIs need JSDoc** with `@example` blocks
-9. **Use section separators** (`// ====... TYPES ====...`) to organize code
-10. **Run `npm run typecheck` before committing** — the consumer project also typechecks against this package
+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