@ilamy/calendar 0.1.10 → 0.2.0

package/README.md

@@ -1,4 +1,4 @@
-# Ilamy Calendar
+# ilamy Calendar
 
 A powerful, full-featured React calendar component library built with TypeScript, Tailwind CSS, and modern React patterns. Features multiple calendar views, drag-and-drop support, recurring events, and comprehensive internationalization.
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import React2 from "react";
+import React3 from "react";
 import dayjs from "dayjs";
 import "dayjs/locale/af";
 import "dayjs/locale/am";
@@ -143,36 +143,27 @@ 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;
+import { Options } from "rrule";
+/**
+* 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 = {
 	/**
-	* 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
+	* The frequency of the event. Must be one of the following: DAILY, WEEKLY, MONTHLY, etc.
 	*/
-	daysOfWeek?: number[];
+	freq: Options["freq"]
 	/**
-	* Specific dates to exclude from the recurrence pattern
-	* Useful for holidays or one-off cancellations
+	* 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.
 	*/
-	exceptions?: dayjs.Dayjs[];
-}
+	dtstart: Date
+} & Partial<Omit<Options, "freq" | "dtstart">>;
 /**
 * Core calendar event interface representing a single calendar event.
 * This is the primary data structure for calendar events.
@@ -182,16 +173,6 @@ interface CalendarEvent {
 	id: string | number;
 	/** Display title of the event */
 	title: string;
-	/**
-	* 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 */
@@ -216,25 +197,33 @@ interface CalendarEvent {
 	*/
 	allDay?: boolean;
 	/**
-	* Recurrence configuration for repeating events
-	* If present, this event will repeat according to the specified pattern
+	* 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') }
 	*/
-	recurrence?: EventRecurrence;
+	rrule?: RRuleOptions;
 	/**
-	* Whether this event is part of a recurring series
-	* @internal Set automatically by the calendar system
+	* 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']
 	*/
-	isRecurring?: boolean;
+	exdates?: string[];
 	/**
-	* Reference to the parent event ID for recurring event instances
-	* @internal Used to link recurring instances to their parent
+	* 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
 	*/
-	parentEventId?: string | number;
+	recurrenceId?: string;
 	/**
-	* Whether this is a modified instance of a recurring event
-	* @internal Used to track exceptions in recurring series
+	* UID for iCalendar compatibility
+	* Unique identifier across calendar systems
 	*/
-	isException?: boolean;
+	uid?: string;
 	/**
 	* Custom data associated with the event
 	* Use this to store additional metadata specific to your application
@@ -242,41 +231,29 @@ interface CalendarEvent {
 	*/
 	data?: Record<string, any>;
 }
-interface IlamyCalendarEventRecurrence extends Omit<EventRecurrence, "endDate"> {
-	/** How often the event repeats */
-	endDate?: dayjs.Dayjs | Date | string;
-}
-interface IlamyCalendarEvent extends Omit<CalendarEvent, "start" | "end" | "recurrence" | "originalStart" | "originalEnd"> {
-	/** Start date and time of the event */
-	start: dayjs.Dayjs | Date | string;
-	/** End date and time of the event */
-	end: dayjs.Dayjs | Date | string;
-	/**
-	* Original start date for recurring events (used for tracking modifications)
-	* @internal
-	*/
-	originalStart?: dayjs.Dayjs | Date | string;
-	/**
-	* Original end date for recurring events (used for tracking modifications)
-	* @internal
-	*/
-	originalEnd?: dayjs.Dayjs | Date | string;
-	/**
-	* Recurrence configuration for repeating events
-	* If present, this event will repeat according to the specified pattern
-	*/
-	recurrence?: IlamyCalendarEventRecurrence;
-}
 /**
 * 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 CalendarProps {
+import React2 from "react";
+/**
+* This interface extends the base CalendarEvent but allows more flexible date types
+* for the start and end properties. The component will automatically convert these
+* to dayjs objects internally for consistent date handling.
+*
+* @interface IlamyCalendarPropEvent
+* @extends {Omit<CalendarEvent, 'start' | 'end'>}
+*/
+interface IlamyCalendarPropEvent extends Omit<CalendarEvent, "start" | "end"> {
+	start: dayjs.Dayjs | Date | string;
+	end: dayjs.Dayjs | Date | string;
+}
+interface IlamyCalendarProps {
 	/**
 	* Array of events to display in the calendar.
 	*/
-	events?: IlamyCalendarEvent[];
+	events?: IlamyCalendarPropEvent[];
 	/**
 	* The first day of the week to display in the calendar.
 	* Can be 'sunday', 'monday', etc. Defaults to 'sunday'.
@@ -296,7 +273,7 @@ interface CalendarProps {
 	* 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;
+	onCellClick?: (start: dayjs.Dayjs, end: dayjs.Dayjs) => void;
 	/**
 	* Callback when the calendar view changes (month, week, day, year).
 	* Useful for syncing with external state or analytics.
@@ -344,30 +321,40 @@ interface CalendarProps {
 	*/
 	headerComponent?: React2.ReactNode;
 }
-declare const IlamyCalendar: React2.FC<CalendarProps>;
+declare const IlamyCalendar: React3.FC<IlamyCalendarProps>;
 /**
 * Simplified calendar context type for external use
 * Contains only the most commonly used calendar operations
 */
-type UseIlamyCalendarContextReturn = {
-	readonly currentDate: dayjs.Dayjs
-	readonly view: "month" | "week" | "day" | "year"
-	readonly events: CalendarEvent[]
-	readonly isEventFormOpen: boolean
-	readonly selectedEvent: CalendarEvent | null
-	readonly selectedDate: dayjs.Dayjs | null
-	readonly firstDayOfWeek: number
-	readonly setCurrentDate: (date: dayjs.Dayjs) => void
-	readonly selectDate: (date: dayjs.Dayjs) => void
-	readonly setView: (view: "month" | "week" | "day" | "year") => void
-	readonly nextPeriod: () => void
-	readonly prevPeriod: () => void
-	readonly today: () => void
-	readonly addEvent: (event: CalendarEvent) => void
-	readonly updateEvent: (eventId: string | number, event: Partial<CalendarEvent>) => void
-	readonly deleteEvent: (eventId: string | number) => void
-	readonly openEventForm: (date?: dayjs.Dayjs) => void
-	readonly closeEventForm: () => void
-};
+interface UseIlamyCalendarContextReturn {
+	readonly currentDate: dayjs.Dayjs;
+	readonly view: "month" | "week" | "day" | "year";
+	readonly events: CalendarEvent[];
+	readonly isEventFormOpen: boolean;
+	readonly selectedEvent: CalendarEvent | null;
+	readonly selectedDate: dayjs.Dayjs | null;
+	readonly firstDayOfWeek: number;
+	readonly setCurrentDate: (date: dayjs.Dayjs) => void;
+	readonly selectDate: (date: dayjs.Dayjs) => void;
+	readonly setView: (view: "month" | "week" | "day" | "year") => void;
+	readonly nextPeriod: () => void;
+	readonly prevPeriod: () => void;
+	readonly today: () => void;
+	readonly addEvent: (event: CalendarEvent) => void;
+	readonly updateEvent: (eventId: string | number, event: Partial<CalendarEvent>) => void;
+	readonly deleteEvent: (eventId: string | number) => void;
+	readonly openEventForm: (date?: dayjs.Dayjs) => void;
+	readonly closeEventForm: () => void;
+}
 declare const useIlamyCalendarContext: () => UseIlamyCalendarContextReturn;
-export { useIlamyCalendarContext, WeekDays, UseIlamyCalendarContextReturn, IlamyCalendar, IlamyCalendarEventRecurrence as EventRecurrence, IlamyCalendarEvent as CalendarEvent };
+declare const isRecurringEvent: (event: CalendarEvent) => boolean;
+interface GenerateRecurringEventsProps {
+	event: CalendarEvent;
+	currentEvents: CalendarEvent[];
+	startDate: dayjs.Dayjs;
+	endDate: dayjs.Dayjs;
+}
+declare const generateRecurringEvents: ({ event, currentEvents, startDate, endDate }: GenerateRecurringEventsProps) => CalendarEvent[];
+import { Frequency, Weekday } from "rrule";
+import { RRule } from "rrule";
+export { useIlamyCalendarContext, isRecurringEvent, generateRecurringEvents, Weekday, WeekDays, UseIlamyCalendarContextReturn, RRuleOptions, RRule, IlamyCalendarProps, IlamyCalendar, Frequency, CalendarEvent };