@ilamy/calendar 1.8.1 → 2.0.0

package/dist/index.d.ts

@@ -1,27 +1,5 @@
-import { Weekday } from "rrule";
-import { RRule } from "rrule";
-import { Options } from "rrule";
-import { Dayjs } from "dayjs";
-/**
-* Re-rrule.js Options with practical TypeScript interface.
-* Makes all properties optional except freq and dtstart (which are required by RFC 5545).
-* This allows clean object creation without needing explicit null values.
-*
-* @see https://tools.ietf.org/html/rfc5545 - RFC 5545 iCalendar specification
-* @see https://github.com/jakubroztocil/rrule - rrule.js library documentation
-*/
-type RRuleOptions = {
-	/**
-	* The frequency of the event. Must be one of the following: DAILY, WEEKLY, MONTHLY, etc.
-	*/
-	freq: Options["freq"];
-	/**
-	* The start date of the recurrence rule. This defines when the recurrence pattern begins.
-	* Required for proper RRULE functionality according to RFC 5545.
-	* @important Same as the event start date.
-	*/
-	dtstart: Date;
-} & Partial<Omit<Options, "freq" | "dtstart">>;
+import { ComponentType, ReactNode as ReactNode2 } from "react";
+import { Dayjs as Dayjs2, ManipulateType as ManipulateType2 } from "dayjs";
 /**
 * Core calendar event interface representing a single calendar event.
 * This is the primary data structure for calendar events.
@@ -32,9 +10,9 @@ interface CalendarEvent {
 	/** Display title of the event */
 	title: string;
 	/** Start date and time of the event */
-	start: Dayjs;
+	start: Dayjs2;
 	/** End date and time of the event */
-	end: Dayjs;
+	end: Dayjs2;
 	/**
 	* Color for the event (supports CSS color values, hex, rgb, hsl, or CSS class names)
 	* @example "#3b82f6", "blue-500", "rgb(59, 130, 246)"
@@ -55,29 +33,6 @@ interface CalendarEvent {
 	*/
 	allDay?: boolean;
 	/**
-	* Recurrence rule for recurring events (RFC 5545 standard)
-	*
-	* Uses TypeScript interface for better readability, type safety, and IDE support
-	* compared to RRULE string format. Converted to rrule.js format internally.
-	*
-	* @example { freq: 'WEEKLY', interval: 1, byweekday: ['MO', 'WE', 'FR'] }
-	* @example { freq: 'DAILY', interval: 1, count: 10 }
-	* @example { freq: 'MONTHLY', interval: 1, until: new Date('2025-12-31') }
-	*/
-	rrule?: RRuleOptions;
-	/**
-	* Exception dates (EXDATE) - dates to exclude from recurrence
-	* Uses ISO string format for storage and transmission
-	* @example ['2025-01-15T09:00:00.000Z', '2025-01-22T09:00:00.000Z']
-	*/
-	exdates?: string[];
-	/**
-	* Recurrence ID (RECURRENCE-ID) - identifies modified instances
-	* Points to the original occurrence date this event modifies
-	* Used for events that are modifications of recurring instances
-	*/
-	recurrenceId?: string;
-	/**
 	* UID for iCalendar compatibility
 	* Unique identifier across calendar systems
 	*/
@@ -91,7 +46,7 @@ interface CalendarEvent {
 	* Use this to store additional metadata specific to your application
 	* @example { meetingType: 'standup', attendees: ['john', 'jane'] }
 	*/
-	data?: Record<string, any>;
+	data?: Record<string, unknown>;
 }
 /**
 * Supported days of the week for calendar configuration.
@@ -119,50 +74,6 @@ interface BusinessHours {
 	*/
 	endTime?: number;
 }
-interface EventFormProps {
-	open?: boolean;
-	selectedEvent?: CalendarEvent | null;
-	onAdd?: (event: CalendarEvent) => void;
-	onUpdate?: (event: CalendarEvent) => void;
-	onDelete?: (event: CalendarEvent) => void;
-	onClose: () => void;
-}
-import React4 from "react";
-import React3 from "react";
-/**
-* Public-facing resource calendar event interface with flexible date types.
-* Similar to IlamyCalendarPropEvent but with resource assignment fields.
-* Dates can be provided as Dayjs, Date, or string and will be normalized internally.
-*
-* @interface IlamyResourceCalendarPropEvent
-* @extends {IlamyCalendarPropEvent}
-*/
-interface IlamyResourceCalendarPropEvent extends IlamyCalendarPropEvent {
-	/** Single resource assignment */
-	resourceId?: string | number;
-	/** Multiple resource assignment (cross-resource events) */
-	resourceIds?: (string | number)[];
-}
-interface IlamyResourceCalendarProps extends Omit<IlamyCalendarProps, "events"> {
-	/** Array of events to display */
-	events?: IlamyResourceCalendarPropEvent[];
-	/** Array of resources */
-	resources?: Resource[];
-	/** Custom render function for resources */
-	renderResource?: (resource: Resource) => React.ReactNode;
-	/**
-	* Orientation of the resource view.
-	* - "horizontal": Resources are rows, time is columns (default)
-	* - "vertical": Resources are columns, time is rows
-	*/
-	orientation?: "horizontal" | "vertical";
-	/**
-	* Granularity of time slots in the week view.
-	* - "hourly": Time slots are 1 hour (default)
-	* - "daily": Time slots are 1 day
-	*/
-	weekViewGranularity?: "hourly" | "daily";
-}
 /**
 * Resource interface representing a calendar resource (person, room, equipment, etc.)
 */
@@ -181,8 +92,6 @@ interface Resource {
 	* @example "#dbeafe", "blue-100", "rgba(59, 130, 246, 0.1)"
 	*/
 	backgroundColor?: string;
-	/** Optional position for resource display */
-	position?: number;
 	/**
 	* Configuration for resource-specific business hours.
 	* If provided, these will be used instead of the global business hours for this resource.
@@ -193,9 +102,266 @@ interface Resource {
 	* Use this to store additional metadata specific to your application
 	* @example { avatar: 'https://example.com/avatar.png', role: 'admin' }
 	*/
-	data?: Record<string, any>;
+	data?: Record<string, unknown>;
+}
+interface PluginDateRange {
+	start: Dayjs2;
+	end: Dayjs2;
+}
+interface PluginMutationArgs {
+	event: CalendarEvent;
+	updates?: Partial<CalendarEvent>;
+	currentEvents: CalendarEvent[];
+	scope: unknown;
+}
+/** Structured result from `applyEdit` when a mutation updates multiple stored rows. */
+interface PluginMutationResult {
+	events: CalendarEvent[];
+	/** Existing rows to persist via `onEventUpdate`. */
+	updated: CalendarEvent[];
+	/** New rows to persist via `onEventAdd`. */
+	added: CalendarEvent[];
+	/** Existing rows to persist via `onEventDelete`. */
+	deleted: CalendarEvent[];
+}
+/**
+* Calendar configuration handed to a view's `columns()`/`renderHeader()`.
+* Carries the resource axis (`resources`, `orientation`) so a resource-capable
+* view can compose both arrangements. `range()` receives only the
+* `firstDayOfWeek` slice (see its own signature).
+*/
+interface ViewConfig {
+	firstDayOfWeek: number;
+	hiddenDays?: Set<number>;
+	businessHours?: BusinessHours | BusinessHours[];
+	hideNonBusinessHours?: boolean;
+	/** The resource axis. Set only when the calendar renders resources. */
+	resources?: Resource[];
+	/**
+	* The calendar-level resource arrangement (the user's choice): where the
+	* resource axis goes. Only meaningful when `resources` is set.
+	*/
+	orientation?: "vertical" | "horizontal";
+	/**
+	* Week-view granularity when `resources` is set: 'hourly' (default) nests
+	* hour slots under each day; 'daily' shows one cell per day.
+	*/
+	weekViewGranularity?: "hourly" | "daily";
+}
+/**
+* One column of a 'vertical' view (time flows down the column).
+* Formalizes the calendar's existing VerticalGrid column input.
+*/
+interface VerticalColumnSpec {
+	/** Stable column id; drives testids and React keys. */
+	id: string;
+	/** The date this column represents; gutter/label columns leave it unset. */
+	day?: Dayjs2;
+	/** The cells of the column: hour slots (gridType 'hour') or dates ('day'). */
+	days: Dayjs2[];
+	gridType?: "day" | "hour";
+	className?: string;
+	/** Label-only column (e.g. the time gutter): renders no events. */
+	noEvents?: boolean;
+	renderCell?: (date: Dayjs2) => ReactNode2;
+	/**
+	* Resource-axis identity when the column belongs to one resource. The
+	* single carrier: consumers derive the id from `resource.id`.
+	*/
+	resource?: Resource;
+}
+/** One cell of a 'horizontal' row. */
+interface HorizontalCellSpec {
+	id: string;
+	day?: Dayjs2;
+	/** A grouped cell spanning several dates (nested-axis arrangements). */
+	days?: Dayjs2[];
+	gridType: "day" | "hour";
+	className?: string;
+}
+/**
+* One row of a 'horizontal' view (date cells flow across the row).
+* Formalizes the calendar's existing HorizontalGrid row input.
+*/
+interface HorizontalRowSpec {
+	/** Stable row id; drives testids and React keys (matches VerticalColumnSpec.id). */
+	id: string;
+	columns?: HorizontalCellSpec[];
+	className?: string;
+	showDayNumber?: boolean;
+	/** Resource-axis identity when the row belongs to one resource. */
+	resource?: Resource;
+}
+/** What a view's `columns()` returns; `layout` picks which engine consumes it. */
+type ColumnSpec = VerticalColumnSpec | HorizontalRowSpec;
+/** Context passed to a view's `renderHeader`. */
+interface ViewHeaderContext {
+	date: Dayjs2;
+	config: ViewConfig;
+}
+/**
+* Describes a view type — contributed by a plugin or built into the calendar
+* core (the four built-ins are themselves `PluginView` entries). A view either
+* declares `columns` + `layout` and renders through the shared grid engines,
+* or renders entirely through `component` (the escape hatch).
+*/
+interface PluginView {
+	/** Unique view id, e.g. 'resource-week'. */
+	name: string;
+	/** View-switcher label (or a translation key; unknown keys render as-is). */
+	label?: string;
+	/**
+	* View-switcher icon (a component taking `className`, e.g. a lucide icon).
+	* Always shown in the switcher; the label appears beside it only when the
+	* view is selected, and as a hover tooltip otherwise.
+	*/
+	icon: ComponentType<{
+		className?: string;
+	}>;
+	/**
+	* The escape hatch: renders the whole view when `columns`/`layout` are
+	* absent. Spec-driven views omit it. A view with neither renders nothing
+	* (dev builds log a warning).
+	*/
+	component?: ComponentType;
+	/** How far prev/next steps when `navigationStep` is absent ('week', 'month', …). */
+	navigationUnit?: ManipulateType2;
+	/**
+	* How far prev/next jumps; defaults to one `navigationUnit`. Custom-duration
+	* views (a 40-day grid, a 4-day vertical view) set `{ amount: 40, unit: 'day' }`
+	* so navigation moves a full window.
+	*
+	* This also selects the header title/date-picker form (the core derives it
+	* generically, never by view name): a single `day`/`week`/`month`/`year` step
+	* borrows that grid's picker and title; any other step (amount > 1, or a custom
+	* unit) shows the day picker over the view's `range`. A third-party view gets
+	* the right picker for free just by declaring how it navigates.
+	*/
+	navigationStep?: {
+		amount: number;
+		unit: ManipulateType2;
+	};
+	/**
+	* Visible range for navigation callbacks and the event pipeline. Views
+	* without `range` fall back to the month 6x7 grid range. Receives only the
+	* `firstDayOfWeek` slice of the config; the full axis config reaches
+	* `columns()`/`renderHeader()`.
+	*/
+	range?: (date: Dayjs2, config: Pick<ViewConfig, "firstDayOfWeek">) => {
+		start: Dayjs2;
+		end: Dayjs2;
+	};
+	/**
+	* Column/row specs for the shared renderer. Return `VerticalColumnSpec[]`
+	* when `layout` is 'vertical', `HorizontalRowSpec[]` when 'horizontal'.
+	* Omit (together with `layout`) to render `component` instead.
+	*/
+	columns?: (date: Dayjs2, config: ViewConfig) => VerticalColumnSpec[] | HorizontalRowSpec[];
+	/**
+	* The view's intrinsic shape (the author's choice): which engine renders it
+	* when the calendar has NO resources. 'vertical' = time flows down;
+	* 'horizontal' = date cells flow across in stacked rows. With resources on
+	* a resource-capable view, the calendar-level `orientation` wins instead:
+	* `engine = resources && supportsResources ? orientation : layout`.
+	*/
+	layout?: "vertical" | "horizontal";
+	/** Header row content rendered above the grid by the shared renderer. */
+	renderHeader?: (ctx: ViewHeaderContext) => ReactNode2;
+	/**
+	* Whether `columns()` composes the resource axis when `config.resources`
+	* is set. Defaults to false; the view switcher hides resource-incapable
+	* views on a resource calendar.
+	*/
+	supportsResources?: boolean;
+}
+/**
+* A calendar plugin contributes optional behavior and UI through generic hooks
+* named after pipeline moments and mount points, never after a feature. The
+* core stays agnostic of any specific plugin (e.g. recurrence).
+*
+* Hooks follow the Rollup/Vite execution kinds:
+* - `transformEvents` is sequential: each plugin receives the previous
+*   plugin's output, forming a transform chain.
+* - `managesEvent` is first-match: the first plugin whose managesEvent returns
+*   true owns its scoped mutations.
+* - `renderSlot` is additive: every plugin may contribute to a mount point.
+*
+* `slotName` is an opaque string identifier and `context` is opaque to the
+* core. The built-in slot names and their context shapes live in the calendar
+* core, which this contract does NOT depend on, so adding a slot never changes
+* this interface. A plugin narrows `context` by `slotName` at its boundary.
+*
+* `scope` is opaque to the core: the owner produces it (via the mutation-scope
+* slot) and consumes it in `applyEdit` / `applyDelete`. A plugin that provides
+* `applyEdit` / `applyDelete` should also render the mutation-scope slot so the
+* core can gather that scope before mutating.
+*/
+interface IlamyPlugin {
+	name: string;
+	transformEvents?: (events: CalendarEvent[], range: PluginDateRange) => CalendarEvent[];
+	managesEvent?: (event: CalendarEvent) => boolean;
+	applyEdit?: (args: PluginMutationArgs) => CalendarEvent[] | PluginMutationResult;
+	applyDelete?: (args: PluginMutationArgs) => CalendarEvent[] | PluginMutationResult;
+	renderSlot?: (slotName: string, context: unknown) => ReactNode2;
+	/**
+	* Contributes arbitrary data to a named point. Additive: all plugins may
+	* contribute to the same point; the runtime aggregates all results via
+	* `collect`. Parallel to `renderSlot` but for data rather than UI nodes.
+	*/
+	contribute?: (point: string, context: unknown) => unknown[];
+	/**
+	* Registers new view types that the calendar can switch to. Each entry in
+	* the array describes one view (id, component, navigation unit, …).
+	*/
+	views?: PluginView[];
+	/**
+	* Wraps the calendar subtree so the plugin's own React context is available
+	* to its views, slots, and components. Rendered as the outermost wrapper
+	* among all plugin providers.
+	*/
+	provider?: ComponentType<{
+		children: ReactNode2;
+	}>;
+}
+/** Context passed to the `event-form` slot (inside the create/edit form). */
+interface EventFormSlotContext {
+	event: CalendarEvent;
+	onChange: (updates: Partial<CalendarEvent>) => void;
+}
+/**
+* Context passed to the `event-mutation-scope` slot. The owning plugin renders
+* UI to gather its opaque `scope`, then calls `resolve(scope)` (or `cancel`).
+*/
+interface EventMutationScopeSlotContext {
+	event: CalendarEvent;
+	operation: "edit" | "delete";
+	resolve: (scope: unknown) => void;
+	cancel: () => void;
 }
-interface Translations {
+import dayjs from "dayjs";
+type Dayjs3 = dayjs.Dayjs3;
+type ManipulateType3 = dayjs.ManipulateType3;
+declare const _default: typeof dayjs;
+/**
+* The calendar's plugin mount points. These belong to the host (the components
+* that render them: the event form and the drag-and-drop flow), NOT to the
+* plugin kernel and NOT to any individual plugin. The kernel's `renderSlot`
+* takes a plain `slotName: string` and knows nothing about this list; the core
+* renders these named slots and any plugin may fill the ones it cares about.
+*/
+declare const SLOT_EVENT_FORM = "event-form";
+declare const SLOT_EVENT_MUTATION_SCOPE = "event-mutation-scope";
+interface EventFormProps {
+	open?: boolean;
+	selectedEvent?: CalendarEvent | null;
+	onAdd?: (event: CalendarEvent) => void;
+	onUpdate?: (event: CalendarEvent) => void;
+	onDelete?: (event: CalendarEvent) => void;
+	onClose: () => void;
+}
+import React4 from "react";
+import React3 from "react";
+declare const defaultTranslations: {
 	today: string;
 	create: string;
 	new: string;
@@ -203,6 +369,8 @@ interface Translations {
 	delete: string;
 	cancel: string;
 	export: string;
+	previous: string;
+	next: string;
 	event: string;
 	events: string;
 	newEvent: string;
@@ -226,6 +394,16 @@ interface Translations {
 	repeat: string;
 	repeats: string;
 	customRecurrence: string;
+	frequency: string;
+	everyWeekday: string;
+	weeklyOn: string;
+	monthlyOnDay: string;
+	monthlyOnThe: string;
+	first: string;
+	second: string;
+	third: string;
+	fourth: string;
+	last: string;
 	daily: string;
 	weekly: string;
 	monthly: string;
@@ -259,20 +437,27 @@ interface Translations {
 	week: string;
 	day: string;
 	year: string;
+	agenda: string;
+	agendaNoEvents: string;
 	more: string;
 	resources: string;
 	resource: string;
+	selectResource: string;
 	time: string;
 	date: string;
 	noResourcesVisible: string;
 	addResourcesOrShowExisting: string;
-}
+};
+/** All translation keys, derived from the canonical English dictionary in `default.ts`. */
+type Translations = Record<keyof typeof defaultTranslations, string>;
 type TranslationKey = keyof Translations;
 type TranslatorFunction = (key: TranslationKey | string) => string;
 /**
-* Available calendar view types.
+* Available calendar view types. The built-in views (day, week, month, year)
+* are `PluginView` specs in `features/calendar/components/views`; plugins may
+* contribute additional view names, so this is a broad `string`.
 */
-type CalendarView = "month" | "week" | "day" | "year";
+type CalendarView = string;
 /**
 * Time format options for displaying times in the calendar.
 */
@@ -305,38 +490,46 @@ interface CalendarClassesOverride {
 * @extends {Omit<CalendarEvent, 'start' | 'end'>}
 */
 interface IlamyCalendarPropEvent extends Omit<CalendarEvent, "start" | "end"> {
-	start: Dayjs | Date | string;
-	end: Dayjs | Date | string;
+	start: Dayjs3 | Date | string;
+	end: Dayjs3 | Date | string;
 }
 /**
 * Information passed to the onCellClick callback.
 * Uses named properties for extensibility.
 */
 interface DateRange {
-	start: Dayjs;
-	end: Dayjs;
+	start: Dayjs3;
+	end: Dayjs3;
 }
 interface CellInfo {
 	/** Start date/time of the cell */
-	start: Dayjs;
+	start: Dayjs3;
 	/** End date/time of the cell */
-	end: Dayjs;
+	end: Dayjs3;
 	/** Full resource object in resource calendars; undefined in a regular calendar */
 	resource?: Resource;
 	/** Whether this is an all-day cell (optional) */
 	allDay?: boolean;
 }
 /**
+* Input accepted by `openEventForm`. A partial event, optionally carrying the
+* full resource of the clicked cell (`CellInfo` is assignable as-is). When no
+* explicit `resourceId` is given, the carried resource's id is used.
+*/
+type OpenEventFormInput = Partial<CalendarEvent> & {
+	resource?: Resource;
+};
+/**
 * Props passed to the custom render function for the current time indicator.
 * Allows users to customize how the current time indicator is displayed.
 */
 interface RenderCurrentTimeIndicatorProps {
 	/** The current time as a dayjs object */
-	currentTime: Dayjs;
+	currentTime: Dayjs3;
 	/** The start of the visible time range */
-	rangeStart: Dayjs;
+	rangeStart: Dayjs3;
 	/** The end of the visible time range */
-	rangeEnd: Dayjs;
+	rangeEnd: Dayjs3;
 	/** Progress percentage (0-100) representing position in the range */
 	progress: number;
 	/**
@@ -379,7 +572,7 @@ interface IlamyCalendarProps {
 	* The initial date to display when the calendar loads.
 	* If not provided, the calendar will default to today's date.
 	*/
-	initialDate?: Dayjs | Date | string;
+	initialDate?: Dayjs3 | Date | string;
 	/**
 	* Custom render function for calendar events.
 	* If provided, it will override the default event rendering.
@@ -404,6 +597,12 @@ interface IlamyCalendarProps {
 	*/
 	isCellDisabled?: (info: CellInfo) => boolean;
 	/**
+	* Returns extra CSS classes for a cell based on custom logic (unavailability
+	* styling, on-call windows, etc.). Unlike `isCellDisabled`, this is purely
+	* visual — cells remain clickable and accept drag-drops.
+	*/
+	getCellClassName?: (info: CellInfo) => string;
+	/**
 	* Callback when the calendar view changes (month, week, day, year).
 	* Useful for syncing with external state or analytics.
 	*/
@@ -427,7 +626,7 @@ interface IlamyCalendarProps {
 	* Callback when the current date changes (navigation).
 	* Provides the new current date and the current visible range.
 	*/
-	onDateChange?: (date: Dayjs, range: DateRange) => void;
+	onDateChange?: (date: Dayjs3, range: DateRange) => void;
 	/**
 	* Locale to use for formatting dates and times.
 	* If not provided, the default locale will be used.
@@ -601,7 +800,7 @@ interface IlamyCalendarProps {
 	* Custom render function for the hour labels in the gutter/header.
 	* Receives a Dayjs object for the hour and should return a React node.
 	*/
-	renderHour?: (date: Dayjs) => React3.ReactNode;
+	renderHour?: (date: Dayjs3) => React3.ReactNode;
 	/**
 	* Granularity of the time grid in minutes for day, week, and resource hour views.
 	* Quarter-hour increments only: `15`, `30`, or `60`.
@@ -637,32 +836,66 @@ interface IlamyCalendarProps {
 	* ```
 	*/
 	scrollTime?: string;
+	/**
+	* Optional plugins that add behavior/UI (e.g. recurrence). The core ships
+	* with no plugins by default — pass `recurrencePlugin()` to enable recurring
+	* events.
+	*/
+	plugins?: IlamyPlugin[];
+	/**
+	* Resources (people, rooms, equipment) to display as a resource axis.
+	* When set: events are shown per matching resource (`resourceIds`, falling
+	* back to `resourceId`); events with no resource assignment are hidden; the
+	* year view is hidden from the view switcher.
+	*/
+	resources?: Resource[];
+	/** Custom render function for resource header cells. */
+	renderResource?: (resource: Resource) => React3.ReactNode;
+	/**
+	* How resources are arranged. Only applies when `resources` is set.
+	* - "horizontal": resources are rows, time is columns (default)
+	* - "vertical": resources are columns, time is rows
+	*/
+	orientation?: "horizontal" | "vertical";
+	/**
+	* Granularity of week-view time slots when `resources` is set.
+	* - "hourly": one column per hour (default)
+	* - "daily": one column per day. Note: `hiddenDays` is ignored in daily
+	*   mode (non-contiguous days would break multi-day event positioning).
+	*/
+	weekViewGranularity?: "hourly" | "daily";
 }
 declare const IlamyCalendar: React4.FC<IlamyCalendarProps>;
-declare const isRecurringEvent: (event: CalendarEvent) => boolean;
-interface GenerateRecurringEventsProps {
-	event: CalendarEvent;
-	currentEvents: CalendarEvent[];
-	startDate: Dayjs;
-	endDate: Dayjs;
-}
-declare const generateRecurringEvents: ({ event, currentEvents, startDate, endDate }: GenerateRecurringEventsProps) => CalendarEvent[];
 import React5 from "react";
+/**
+* @deprecated Since v2.0 `IlamyCalendar` accepts `resources`, `renderResource`,
+* `orientation`, and `weekViewGranularity` directly — use it instead. This
+* alias will be removed in the next major.
+*/
+type IlamyResourceCalendarProps = IlamyCalendarProps;
+/** @deprecated Since v2.0 — use `IlamyCalendar` with the `resources` prop. */
 declare const IlamyResourceCalendar: React5.FC<IlamyResourceCalendarProps>;
+import React6 from "react";
 /**
-* Publicly exposed calendar context properties.
+* The public calendar API surface exposed by useIlamyCalendarContext() — for consumers and plugin
+* components. The full internal context is intentionally not exported.
 */
-interface UseIlamyCalendarContextReturn {
-	readonly currentDate: Dayjs;
+interface IlamyCalendarApi {
+	readonly currentDate: Dayjs3;
+	/** The active view's current visible date range (what is on screen). */
+	readonly currentRange: DateRange;
 	readonly view: CalendarView;
 	readonly events: CalendarEvent[];
+	readonly rawEvents: CalendarEvent[];
 	readonly isEventFormOpen: boolean;
 	readonly selectedEvent: CalendarEvent | null;
-	readonly selectedDate: Dayjs | null;
+	readonly selectedDate: Dayjs3 | null;
 	readonly firstDayOfWeek: number;
 	readonly resources: Resource[];
-	readonly setCurrentDate: (date: Dayjs) => void;
-	readonly selectDate: (date: Dayjs) => void;
+	/** Axis the views lay out along: 'horizontal' (columns) or 'vertical' (rows). */
+	readonly orientation: "horizontal" | "vertical";
+	readonly setCurrentDate: (date: Dayjs3) => void;
+	readonly selectDate: (date: Dayjs3) => void;
 	readonly setView: (view: CalendarView) => void;
 	readonly nextPeriod: () => void;
 	readonly prevPeriod: () => void;
@@ -670,15 +903,42 @@ interface UseIlamyCalendarContextReturn {
 	readonly addEvent: (event: CalendarEvent) => void;
 	readonly updateEvent: (eventId: string | number, event: Partial<CalendarEvent>) => void;
 	readonly deleteEvent: (eventId: string | number) => void;
-	readonly openEventForm: (eventData?: Partial<CalendarEvent>) => void;
+	readonly openEventForm: (eventData?: OpenEventFormInput) => void;
 	readonly closeEventForm: () => void;
+	/**
+	* Handle a click on an existing event: runs the consumer's `onEventClick`
+	* callback if provided, otherwise opens the event for editing. Lets plugin
+	* views (e.g. agenda) handle event clicks identically to the built-in views.
+	*/
+	readonly onEventClick: (event: CalendarEvent) => void;
+	/**
+	* The consumer's custom current-time-indicator renderer, if provided. Lets
+	* plugin views (e.g. agenda) render the indicator consistently with the
+	* built-in views via the shared `@ilamy/ui` CurrentTimeIndicator.
+	*/
+	readonly renderCurrentTimeIndicator?: (props: RenderCurrentTimeIndicatorProps) => React6.ReactNode;
+	/**
+	* Events whose resource membership (`resourceIds`, falling back to
+	* `resourceId`) contains the given resource. On a calendar without
+	* resources this simply filters by the events' own resource fields.
+	*/
 	readonly getEventsForResource: (resourceId: string | number) => CalendarEvent[];
 	readonly businessHours?: BusinessHours | BusinessHours[];
+	readonly t: TranslatorFunction;
+	readonly timeFormat: TimeFormat;
+	readonly timezone?: string;
+	readonly currentLocale: string;
+	readonly getEventsForDateRange: (start: Dayjs3, end: Dayjs3) => CalendarEvent[];
+	readonly applyScopedEdit: (event: CalendarEvent, updates: Partial<CalendarEvent>, scope: unknown) => void;
+	readonly applyScopedDelete: (event: CalendarEvent, scope: unknown) => void;
+	readonly getEventManager: (event: CalendarEvent) => IlamyPlugin | undefined;
+	readonly renderSlot: (slotName: string, context: unknown) => React6.ReactNode[];
+	readonly collect: (point: string, context: unknown) => unknown[];
+	readonly getViews: () => PluginView[];
 }
 /**
 * Public hook exported for library users.
 * Returns a limited set of commonly used properties and methods.
 */
-declare function useIlamyCalendarContext(): UseIlamyCalendarContextReturn;
-declare const defaultTranslations: Translations;
-export { useIlamyCalendarContext, isRecurringEvent, generateRecurringEvents, defaultTranslations, Weekday, WeekDays, UseIlamyCalendarContextReturn, TranslatorFunction, Translations, TranslationKey, TimeFormat, SlotDuration, Resource, RenderCurrentTimeIndicatorProps, RRuleOptions, RRule, IlamyResourceCalendarProps, IlamyResourceCalendar, IlamyCalendarProps, IlamyCalendar, EventFormProps, CellInfo, CalendarView, CalendarEvent, BusinessHours };
+declare function useIlamyCalendarContext(): IlamyCalendarApi;
+export { useIlamyCalendarContext, defaultTranslations, _default as dayjs, WeekDays, ViewHeaderContext, ViewConfig, VerticalColumnSpec, TranslatorFunction, Translations, TranslationKey, TimeFormat, SlotDuration, SLOT_EVENT_MUTATION_SCOPE, SLOT_EVENT_FORM, Resource, RenderCurrentTimeIndicatorProps, PluginView, PluginMutationResult, PluginMutationArgs, PluginDateRange, OpenEventFormInput, ManipulateType3 as ManipulateType, IlamyResourceCalendarProps, IlamyResourceCalendar, IlamyPlugin, IlamyCalendarProps, IlamyCalendarApi, IlamyCalendar, HorizontalRowSpec, HorizontalCellSpec, EventMutationScopeSlotContext, EventFormSlotContext, EventFormProps, Dayjs3 as Dayjs, ColumnSpec, CellInfo, CalendarView, CalendarEvent, CalendarClassesOverride, BusinessHours };