@ilamy/calendar 1.0.2 → 1.1.1

package/README.md

@@ -41,3 +41,10 @@ A powerful, full-featured React calendar component library built with TypeScript
 ## Documentation
 
 For comprehensive documentation, examples, and interactive demos, visit [ilamy.dev](https://ilamy.dev)
+
+## Code Example
+
+Check out the [examples directory](./examples) for complete project setups:
+
+- [Next.js Example](./examples/nextjs) - Full-featured Next.js integration
+- [Astro Example](./examples/astro) - Static site integration with Astro

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import React3 from "react";
+import { Frequency, Weekday } from "rrule";
+import { RRule } from "rrule";
 import { Options } from "rrule";
 /**
 * Re-rrule.js Options with practical TypeScript interface.
@@ -20,6 +21,9 @@ type RRuleOptions = {
 	*/
 	dtstart: Date;
 } & Partial<Omit<Options, "freq" | "dtstart">>;
+import React4 from "react";
+import React3 from "react";
+import dayjs2 from "dayjs";
 /**
 * Core calendar event interface representing a single calendar event.
 * This is the primary data structure for calendar events.
@@ -30,9 +34,9 @@ interface CalendarEvent {
 	/** Display title of the event */
 	title: string;
 	/** Start date and time of the event */
-	start: dayjs.Dayjs;
+	start: dayjs2.Dayjs;
 	/** End date and time of the event */
-	end: dayjs.Dayjs;
+	end: dayjs2.Dayjs;
 	/**
 	* Color for the event (supports CSS color values, hex, rgb, hsl, or CSS class names)
 	* @example "#3b82f6", "blue-500", "rgb(59, 130, 246)"
@@ -80,6 +84,10 @@ interface CalendarEvent {
 	* Unique identifier across calendar systems
 	*/
 	uid?: string;
+	/** Single resource assignment */
+	resourceId?: string | number;
+	/** Multiple resource assignment (cross-resource events) */
+	resourceIds?: (string | number)[];
 	/**
 	* Custom data associated with the event
 	* Use this to store additional metadata specific to your application
@@ -92,7 +100,35 @@ interface CalendarEvent {
 * Used for setting the first day of the week and other week-related settings.
 */
 type WeekDays = "sunday" | "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday";
-import React2 from "react";
+/**
+* Configuration for business hours.
+* Defines the working hours to be highlighted on the calendar.
+*/
+interface BusinessHours {
+	/**
+	* Days of the week to apply business hours to.
+	* @default ['monday', 'tuesday', 'wednesday', 'thursday', 'friday']
+	*/
+	daysOfWeek?: WeekDays[];
+	/**
+	* Start time for business hours in 24-hour format (0-24).
+	* @default 9
+	*/
+	startTime?: number;
+	/**
+	* End time for business hours in 24-hour format (0-24).
+	* @default 17
+	*/
+	endTime?: number;
+}
+interface EventFormProps {
+	open?: boolean;
+	selectedEvent?: CalendarEvent | null;
+	onAdd?: (event: CalendarEvent) => void;
+	onUpdate?: (event: CalendarEvent) => void;
+	onDelete?: (event: CalendarEvent) => void;
+	onClose: () => void;
+}
 interface Translations {
 	today: string;
 	create: string;
@@ -197,6 +233,23 @@ type TranslatorFunction = (key: TranslationKey | string) => string;
 */
 type CalendarView = "month" | "week" | "day" | "year";
 /**
+* Time format options for displaying times in the calendar.
+*/
+type TimeFormat = "12-hour" | "24-hour";
+/**
+* Custom class names for calendar styling.
+* Allows users to override default styles for various calendar elements.
+*/
+interface CalendarClassesOverride {
+	/**
+	* Class name for disabled cells (non-business hours).
+	* Replaces the DISABLED_CELL_CLASSNAME constant.
+	* @default "bg-secondary text-muted-foreground pointer-events-none"
+	* @example "bg-gray-100 text-gray-400 cursor-not-allowed"
+	*/
+	disabledCell?: string;
+}
+/**
 * 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.
@@ -205,8 +258,20 @@ type CalendarView = "month" | "week" | "day" | "year";
 * @extends {Omit<CalendarEvent, 'start' | 'end'>}
 */
 interface IlamyCalendarPropEvent extends Omit<CalendarEvent, "start" | "end"> {
-	start: dayjs.Dayjs | Date | string;
-	end: dayjs.Dayjs | Date | string;
+	start: dayjs2.Dayjs | Date | string;
+	end: dayjs2.Dayjs | Date | string;
+}
+/**
+* Information passed to the onCellClick callback.
+* Uses named properties for extensibility.
+*/
+interface CellClickInfo {
+	/** Start date/time of the clicked cell */
+	start: dayjs2.Dayjs;
+	/** End date/time of the clicked cell */
+	end: dayjs2.Dayjs;
+	/** Resource ID if clicking on a resource calendar cell (optional) */
+	resourceId?: string | number;
 }
 interface IlamyCalendarProps {
 	/**
@@ -227,12 +292,12 @@ interface IlamyCalendarProps {
 	* The initial date to display when the calendar loads.
 	* If not provided, the calendar will default to today's date.
 	*/
-	initialDate?: dayjs.Dayjs | Date | string;
+	initialDate?: dayjs2.Dayjs | Date | string;
 	/**
 	* Custom render function for calendar events.
 	* If provided, it will override the default event rendering.
 	*/
-	renderEvent?: (event: CalendarEvent) => React2.ReactNode;
+	renderEvent?: (event: CalendarEvent) => React3.ReactNode;
 	/**
 	* Callback when an event is clicked.
 	* Provides the clicked event object.
@@ -240,9 +305,9 @@ interface IlamyCalendarProps {
 	onEventClick?: (event: CalendarEvent) => void;
 	/**
 	* Callback when a calendar cell is clicked.
-	* Provides the start and end date of the clicked cell.
+	* Provides cell information including start/end dates and optional resourceId.
 	*/
-	onCellClick?: (start: dayjs.Dayjs, end: dayjs.Dayjs) => void;
+	onCellClick?: (info: CellClickInfo) => void;
 	/**
 	* Callback when the calendar view changes (month, week, day, year).
 	* Useful for syncing with external state or analytics.
@@ -267,7 +332,7 @@ interface IlamyCalendarProps {
 	* Callback when the current date changes (navigation).
 	* Provides the new current date.
 	*/
-	onDateChange?: (date: dayjs.Dayjs) => void;
+	onDateChange?: (date: dayjs2.Dayjs) => void;
 	/**
 	* Locale to use for formatting dates and times.
 	* If not provided, the default locale will be used.
@@ -310,6 +375,13 @@ interface IlamyCalendarProps {
 	*/
 	dayMaxEvents?: number;
 	/**
+	* Vertical spacing between stacked events in pixels.
+	* Controls the gap between events when multiple events are displayed in the same view.
+	* Defaults to 1 pixel if not specified.
+	* Recommended range: 1-8 pixels for optimal readability.
+	*/
+	eventSpacing?: number;
+	/**
 	* Whether to stick the view header to the top of the calendar.
 	* Useful for keeping the header visible while scrolling.
 	*/
@@ -323,15 +395,73 @@ interface IlamyCalendarProps {
 	* Custom header component to replace the default calendar header.
 	* Useful for adding custom branding or additional controls.
 	*/
-	headerComponent?: React2.ReactNode;
+	headerComponent?: React3.ReactNode;
 	/**
 	* Custom class name for the calendar header.
 	* Useful for applying custom styles to the header.
 	*/
 	headerClassName?: string;
+	/**
+	* Configuration for business hours.
+	* Defines the working hours to be highlighted on the calendar.
+	* Can be a single BusinessHours object (applies to all specified days)
+	* or an array of BusinessHours objects (for different hours on different days).
+	*/
+	businessHours?: BusinessHours | BusinessHours[];
+	/**
+	* Custom render function for the event form.
+	* If provided, it will override the default event form component.
+	* The function receives EventFormProps and should return a React node.
+	*/
+	renderEventForm?: (props: EventFormProps) => React3.ReactNode;
+	/**
+	* Time format for displaying times in the calendar.
+	* - "12-hour": Times displayed as "1:00 PM" (default)
+	* - "24-hour": Times displayed as "13:00"
+	*/
+	timeFormat?: TimeFormat;
+	/**
+	* Custom class names for overriding default calendar element styles.
+	* Allows fine-grained control over the appearance of different calendar elements.
+	* @example { disabledCell: "bg-gray-100 text-gray-400" }
+	*/
+	classesOverride?: CalendarClassesOverride;
 }
-declare const IlamyCalendar: React3.FC<IlamyCalendarProps>;
-import React4 from "react";
+declare const IlamyCalendar: React4.FC<IlamyCalendarProps>;
+declare const isRecurringEvent: (event: CalendarEvent) => boolean;
+interface GenerateRecurringEventsProps {
+	event: CalendarEvent;
+	currentEvents: CalendarEvent[];
+	startDate: dayjs2.Dayjs;
+	endDate: dayjs2.Dayjs;
+}
+declare const generateRecurringEvents: ({ event, currentEvents, startDate, endDate }: GenerateRecurringEventsProps) => CalendarEvent[];
+/**
+* Simplified calendar context type for external use
+* Contains only the most commonly used calendar operations
+*/
+interface UseIlamyCalendarContextReturn {
+	readonly currentDate: dayjs2.Dayjs;
+	readonly view: CalendarView;
+	readonly events: CalendarEvent[];
+	readonly isEventFormOpen: boolean;
+	readonly selectedEvent: CalendarEvent | null;
+	readonly selectedDate: dayjs2.Dayjs | null;
+	readonly firstDayOfWeek: number;
+	readonly setCurrentDate: (date: dayjs2.Dayjs) => void;
+	readonly selectDate: (date: dayjs2.Dayjs) => void;
+	readonly setView: (view: CalendarView) => 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: (eventData?: Partial<CalendarEvent>) => void;
+	readonly closeEventForm: () => void;
+	readonly businessHours?: BusinessHours | BusinessHours[];
+}
+declare const useIlamyCalendarContext: () => UseIlamyCalendarContextReturn;
 /**
 * Public-facing resource calendar event interface with flexible date types.
 * Similar to IlamyCalendarPropEvent but with resource assignment fields.
@@ -375,59 +505,16 @@ interface Resource {
 	/** Optional position for resource display */
 	position?: number;
 }
-/**
-* Resource calendar event interface extending CalendarEvent with resource assignment
-*/
-interface ResourceCalendarEvent extends CalendarEvent {
-	/** Single resource assignment */
-	resourceId?: string | number;
-	/** Multiple resource assignment (cross-resource events) */
-	resourceIds?: (string | number)[];
-}
-declare const IlamyResourceCalendar: React4.FC<IlamyResourceCalendarProps>;
-/**
-* Simplified calendar context type for external use
-* Contains only the most commonly used calendar operations
-*/
-interface UseIlamyCalendarContextReturn {
-	readonly currentDate: dayjs.Dayjs;
-	readonly view: CalendarView;
-	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: CalendarView) => 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;
+import React5 from "react";
+declare const IlamyResourceCalendar: React5.FC<IlamyResourceCalendarProps>;
 /**
 * Simplified resource calendar context type for external use
 */
 interface UseIlamyResourceCalendarContextReturn extends UseIlamyCalendarContextReturn {
-	readonly events: ResourceCalendarEvent[];
+	readonly events: CalendarEvent[];
 	readonly resources: Resource[];
-	readonly getEventsForResource: (resourceId: string | number) => ResourceCalendarEvent[];
+	readonly getEventsForResource: (resourceId: string | number) => CalendarEvent[];
 }
 declare const useIlamyResourceCalendarContext: () => UseIlamyResourceCalendarContextReturn;
-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";
 declare const defaultTranslations: Translations;
-export { useIlamyResourceCalendarContext, useIlamyCalendarContext, isRecurringEvent, generateRecurringEvents, defaultTranslations, Weekday, WeekDays, UseIlamyResourceCalendarContextReturn, UseIlamyCalendarContextReturn, TranslatorFunction, Translations, TranslationKey, ResourceCalendarEvent, Resource, RRuleOptions, RRule, IlamyResourceCalendarProps, IlamyResourceCalendar, IlamyCalendarProps, IlamyCalendar, Frequency, CalendarView, CalendarEvent };
+export { useIlamyResourceCalendarContext, useIlamyCalendarContext, isRecurringEvent, generateRecurringEvents, defaultTranslations, Weekday, WeekDays, UseIlamyResourceCalendarContextReturn, UseIlamyCalendarContextReturn, TranslatorFunction, Translations, TranslationKey, TimeFormat, Resource, RRuleOptions, RRule, IlamyResourceCalendarProps, IlamyResourceCalendar, IlamyCalendarProps, IlamyCalendar, Frequency, EventFormProps, CellClickInfo, CalendarView, CalendarEvent };