@ilamy/calendar 0.1.6 → 0.1.7

package/dist/index.d.ts

@@ -143,58 +143,205 @@ import "dayjs/locale/zh-cn";
 import "dayjs/locale/zh-hk";
 import "dayjs/locale/zh-tw";
 import "dayjs/locale/zh";
+interface EventRecurrence {
+	/** How often the event repeats */
+	frequency: "daily" | "weekly" | "monthly" | "yearly";
+	/**
+	* Interval between repetitions (e.g., every 2 weeks = interval: 2, frequency: 'weekly')
+	* @default 1
+	*/
+	interval: number;
+	/**
+	* Optional end date for the recurrence pattern
+	* If not provided, the event repeats indefinitely
+	*/
+	endDate?: dayjs.Dayjs;
+	/**
+	* Optional maximum number of occurrences
+	* If provided, takes precedence over endDate
+	*/
+	count?: number;
+	/**
+	* Days of the week for weekly recurrence (0 = Sunday, 6 = Saturday)
+	* Only used when frequency is 'weekly'
+	* @example [1, 3, 5] for Monday, Wednesday, Friday
+	*/
+	daysOfWeek?: number[];
+	/**
+	* Specific dates to exclude from the recurrence pattern
+	* Useful for holidays or one-off cancellations
+	*/
+	exceptions?: dayjs.Dayjs[];
+}
+/**
+* Core calendar event interface representing a single calendar event.
+* This is the primary data structure for calendar events.
+*/
 interface CalendarEvent {
-	id: string;
+	/** Unique identifier for the event */
+	id: string | number;
+	/** Display title of the event */
 	title: string;
-	start: dayjs.Dayjs;
+	/**
+	* Original start date for recurring events (used for tracking modifications)
+	* @internal
+	*/
 	originalStart?: dayjs.Dayjs;
+	/**
+	* Original end date for recurring events (used for tracking modifications)
+	* @internal
+	*/
 	originalEnd?: dayjs.Dayjs;
+	/** Start date and time of the event */
+	start: dayjs.Dayjs;
+	/** End date and time of the event */
 	end: dayjs.Dayjs;
+	/**
+	* Color for the event (supports CSS color values, hex, rgb, hsl, or CSS class names)
+	* @example "#3b82f6", "blue-500", "rgb(59, 130, 246)"
+	*/
 	color?: string;
+	/**
+	* Background color for the event (supports CSS color values, hex, rgb, hsl, or CSS class names)
+	* @example "#dbeafe", "blue-100", "rgba(59, 130, 246, 0.1)"
+	*/
 	backgroundColor?: string;
+	/** Optional description or notes for the event */
 	description?: string;
+	/** Optional location where the event takes place */
 	location?: string;
-	height?: number;
+	/**
+	* Whether this is an all-day event
+	* @default false
+	*/
 	allDay?: boolean;
-	recurrence?: {
-		frequency: "daily" | "weekly" | "monthly" | "yearly"
-		interval: number
-		endDate?: dayjs.Dayjs
-		count?: number
-		daysOfWeek?: number[]
-		exceptions?: dayjs.Dayjs[]
-	};
+	/**
+	* Recurrence configuration for repeating events
+	* If present, this event will repeat according to the specified pattern
+	*/
+	recurrence?: EventRecurrence;
+	/**
+	* Whether this event is part of a recurring series
+	* @internal Set automatically by the calendar system
+	*/
 	isRecurring?: boolean;
-	parentEventId?: string;
+	/**
+	* Reference to the parent event ID for recurring event instances
+	* @internal Used to link recurring instances to their parent
+	*/
+	parentEventId?: string | number;
+	/**
+	* Whether this is a modified instance of a recurring event
+	* @internal Used to track exceptions in recurring series
+	*/
 	isException?: boolean;
 	/**
 	* Custom data associated with the event
+	* Use this to store additional metadata specific to your application
+	* @example { meetingType: 'standup', attendees: ['john', 'jane'] }
 	*/
 	data?: Record<string, any>;
 }
+/**
+* Extended calendar event interface with calculated positioning properties.
+* Used internally by the calendar rendering engine to position events on the grid.
+*
+* @internal This interface is used by the calendar layout system and should not be used directly
+*/
 interface ProcessedCalendarEvent extends CalendarEvent {
+	/** Left position as a percentage of the container width (0-100) */
 	left: number;
+	/** Width as a percentage of the container width (0-100) */
 	width: number;
+	/** Top position as a percentage of the container height (0-100) */
 	top: number;
+	/** Height as a percentage of the container height (0-100) */
 	height: number;
 }
+/**
+* Supported days of the week for calendar configuration.
+* Used for setting the first day of the week and other week-related settings.
+*/
 type WeekDays = "sunday" | "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday";
+interface CalendarEvents extends Omit<CalendarEvent, "start" | "end" | "recurrence" | "originalStart" | "originalEnd"> {
+	start: dayjs.Dayjs | Date | string;
+	end: dayjs.Dayjs | Date | string;
+	originalStart?: dayjs.Dayjs | Date | string;
+	originalEnd?: dayjs.Dayjs | Date | string;
+	recurrence?: EventRecurrence;
+}
 interface CalendarProps {
-	events?: CalendarEvent[];
+	/**
+	* Array of events to display in the calendar.
+	*/
+	events?: CalendarEvents[];
+	/**
+	* The first day of the week to display in the calendar.
+	* Can be 'sunday', 'monday', etc. Defaults to 'sunday'.
+	*/
 	firstDayOfWeek?: WeekDays;
+	/**
+	* Custom render function for calendar events.
+	* If provided, it will override the default event rendering.
+	*/
 	renderEvent?: (event: CalendarEvent) => React2.ReactNode;
+	/**
+	* Callback when an event is clicked.
+	* Provides the clicked event object.
+	*/
 	onEventClick?: (event: CalendarEvent) => void;
+	/**
+	* Callback when a calendar cell is clicked.
+	* Provides the start and end date of the clicked cell.
+	*/
 	onCellClick?: (startDate: dayjs.Dayjs, endDate: dayjs.Dayjs) => void;
+	/**
+	* Callback when the calendar view changes (month, week, day, year).
+	* Useful for syncing with external state or analytics.
+	*/
 	onViewChange?: (view: "month" | "week" | "day" | "year") => void;
+	/**
+	* Locale to use for formatting dates and times.
+	* If not provided, the default locale will be used.
+	*/
 	locale?: string;
+	/**
+	* Timezone to use for displaying dates and times.
+	* If not provided, the local timezone will be used.
+	*/
 	timezone?: string;
+	/**
+	* Whether to disable click events on calendar cells.
+	* Useful for read-only views or when cell clicks are not needed.
+	*/
 	disableCellClick?: boolean;
+	/**
+	* Whether to disable click events on calendar events.
+	* Useful for read-only views or when event clicks are not needed.
+	*/
 	disableEventClick?: boolean;
+	/**
+	* Whether to disable drag-and-drop functionality for calendar events.
+	* Useful for read-only views or when drag-and-drop is not needed.
+	*/
 	disableDragAndDrop?: boolean;
 	dayMaxEvents?: number;
+	/**
+	* Whether to stick the view header to the top of the calendar.
+	* Useful for keeping the header visible while scrolling.
+	*/
 	stickyViewHeader?: boolean;
+	/**
+	* Custom class name for the view header.
+	* Useful for applying custom styles or themes.
+	*/
 	viewHeaderClassName?: string;
+	/**
+	* Custom header component to replace the default calendar header.
+	* Useful for adding custom branding or additional controls.
+	*/
+	headerComponent?: React2.ReactNode;
 }
 declare const IlamyCalendar: React2.FC<CalendarProps>;
 declare const usePublicCalendarContext: () => {};
-export { usePublicCalendarContext as useIlamyCalendarContext, WeekDays, ProcessedCalendarEvent, IlamyCalendar, CalendarEvent };
+export { usePublicCalendarContext as useIlamyCalendarContext, WeekDays, ProcessedCalendarEvent, IlamyCalendar, EventRecurrence, CalendarEvent };