trud-calendar-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,471 @@
+/** ISO 8601 date string (YYYY-MM-DD) */
+type DateString = string;
+/** ISO 8601 datetime string (YYYY-MM-DDTHH:mm:ss) */
+type DateTimeString = string;
+/** Calendar view types */
+type CalendarView = "month" | "week" | "day" | "agenda";
+type RecurrenceFrequency = "daily" | "weekly" | "monthly" | "yearly";
+type RecurrenceDay = "MO" | "TU" | "WE" | "TH" | "FR" | "SA" | "SU";
+interface RecurrenceRule {
+    /** Frequency of recurrence */
+    freq: RecurrenceFrequency;
+    /** Interval between occurrences (default 1) */
+    interval?: number;
+    /** Max number of occurrences */
+    count?: number;
+    /** End date (inclusive) */
+    until?: DateString;
+    /** Days of the week (for weekly/monthly) */
+    byDay?: RecurrenceDay[];
+    /** Days of the month (for monthly, 1-31) */
+    byMonthDay?: number[];
+    /** Position within the month (e.g. 1 = first, -1 = last, for "first Monday") */
+    bySetPos?: number;
+}
+/** A calendar event */
+interface CalendarEvent {
+    /** Unique identifier */
+    id: string;
+    /** Event title */
+    title: string;
+    /** Start date/time as ISO 8601 string */
+    start: DateTimeString;
+    /** End date/time as ISO 8601 string */
+    end: DateTimeString;
+    /** Whether this is an all-day event */
+    allDay?: boolean;
+    /** Event color (CSS color value) */
+    color?: string;
+    /** Recurrence rule */
+    recurrence?: RecurrenceRule;
+    /** Dates excluded from recurrence (YYYY-MM-DD) */
+    exDates?: DateString[];
+    /** ID of the parent recurring event (set on expanded instances) */
+    recurringEventId?: string;
+    /** Original date of this recurring instance (YYYY-MM-DD) */
+    originalDate?: DateString;
+    /** Arbitrary metadata */
+    [key: string]: unknown;
+}
+/** Positioned event for rendering in a time grid */
+interface PositionedEvent {
+    event: CalendarEvent;
+    /** Column index (0-based) within overlap group */
+    column: number;
+    /** Total number of columns in the overlap group */
+    totalColumns: number;
+    /** Top position as percentage of day (0-100) */
+    top: number;
+    /** Height as percentage of day */
+    height: number;
+    /** Whether this is the first segment of a multi-day timed event */
+    isSegmentStart?: boolean;
+    /** Whether this is the last segment of a multi-day timed event */
+    isSegmentEnd?: boolean;
+}
+/** A segment of a multi-day timed event for week/day view rendering */
+interface TimedEventSegment {
+    event: CalendarEvent;
+    /** The date this segment falls on */
+    day: DateString;
+    /** Start fractional hour for this segment */
+    startHour: number;
+    /** End fractional hour for this segment */
+    endHour: number;
+    /** Whether this is the first day of the event */
+    isStart: boolean;
+    /** Whether this is the last day of the event */
+    isEnd: boolean;
+}
+/** A segment of a multi-day event clipped to a single day */
+interface EventSegment {
+    event: CalendarEvent;
+    /** The date this segment falls on */
+    date: DateString;
+    /** Whether this is the first day of the event */
+    isStart: boolean;
+    /** Whether this is the last day of the event */
+    isEnd: boolean;
+}
+type ComponentType<P = any> = (props: P) => any;
+/** Slot component overrides */
+interface CalendarSlots {
+    toolbar?: ComponentType<ToolbarSlotProps>;
+    event?: ComponentType<EventSlotProps>;
+    dayCell?: ComponentType<DayCellSlotProps>;
+    timeEvent?: ComponentType<TimeEventSlotProps>;
+    allDayEvent?: ComponentType<AllDayEventSlotProps>;
+    popover?: ComponentType<PopoverSlotProps>;
+    agendaEvent?: ComponentType<AgendaEventSlotProps>;
+}
+interface ToolbarSlotProps {
+    currentDate: DateString;
+    view: CalendarView;
+    onPrev: () => void;
+    onNext: () => void;
+    onToday: () => void;
+    onViewChange: (view: CalendarView) => void;
+    formattedDate: string;
+}
+interface EventSlotProps {
+    event: CalendarEvent;
+}
+interface DayCellSlotProps {
+    date: DateString;
+    isToday: boolean;
+    isCurrentMonth: boolean;
+    events: CalendarEvent[];
+}
+interface TimeEventSlotProps {
+    event: CalendarEvent;
+    positioned: PositionedEvent;
+}
+interface AllDayEventSlotProps {
+    event: CalendarEvent;
+    segment: EventSegment;
+}
+interface PopoverSlotProps {
+    event: CalendarEvent;
+    onClose: () => void;
+}
+interface AgendaEventSlotProps {
+    event: CalendarEvent;
+}
+/** UI label strings — provide your own for i18n */
+interface CalendarLabels {
+    today: string;
+    month: string;
+    week: string;
+    day: string;
+    agenda: string;
+    allDay: string;
+    noEvents: string;
+    more: (count: number) => string;
+}
+/** Locale configuration */
+interface CalendarLocale {
+    /** BCP 47 locale string (e.g., "en-US", "es-ES") */
+    locale: string;
+    /** First day of week: 0 = Sunday, 1 = Monday */
+    weekStartsOn: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    /** UI labels for buttons, views, etc. */
+    labels?: Partial<CalendarLabels>;
+}
+/** Calendar configuration */
+interface CalendarConfig {
+    /** Events to display */
+    events: CalendarEvent[];
+    /** Initial or controlled date */
+    date?: DateString;
+    /** Initial or controlled view */
+    view?: CalendarView;
+    /** Default view when uncontrolled */
+    defaultView?: CalendarView;
+    /** Default date when uncontrolled */
+    defaultDate?: DateString;
+    /** Locale settings */
+    locale?: Partial<CalendarLocale>;
+    /** Slot overrides */
+    slots?: Partial<CalendarSlots>;
+    /** Callback when an event is clicked */
+    onEventClick?: (event: CalendarEvent) => void;
+    /** Callback when an empty slot is clicked */
+    onSlotClick?: (date: DateTimeString) => void;
+    /** Callback when date changes */
+    onDateChange?: (date: DateString) => void;
+    /** Callback when view changes */
+    onViewChange?: (view: CalendarView) => void;
+    /** Hour the time grid starts (0-23), default 0 */
+    dayStartHour?: number;
+    /** Hour the time grid ends (0-24), default 24 */
+    dayEndHour?: number;
+    /** Callback when an event is dropped on a new time slot (drag & drop) */
+    onEventDrop?: (event: CalendarEvent, newStart: DateTimeString, newEnd: DateTimeString) => void;
+    /** Callback when an event is resized (drag bottom edge) */
+    onEventResize?: (event: CalendarEvent, newStart: DateTimeString, newEnd: DateTimeString) => void;
+    /** Callback when a time range is selected by dragging on empty slots */
+    onSlotSelect?: (start: DateTimeString, end: DateTimeString) => void;
+    /** Enable drag and drop */
+    enableDnD?: boolean;
+    /** Enable multi-select events (Ctrl+click, Shift+click, Ctrl+A) */
+    enableMultiSelect?: boolean;
+    /** Callback when selected events are deleted (Delete/Backspace key) */
+    onEventsDelete?: (events: CalendarEvent[]) => void;
+    /** Enable virtual scrolling for time grid events (opt-in, default false) */
+    enableVirtualization?: boolean;
+}
+/** Calendar state */
+interface CalendarState {
+    currentDate: DateString;
+    view: CalendarView;
+}
+/** Calendar action types */
+type CalendarAction = {
+    type: "NAVIGATE_PREV";
+} | {
+    type: "NAVIGATE_NEXT";
+} | {
+    type: "NAVIGATE_TODAY";
+} | {
+    type: "SET_DATE";
+    payload: DateString;
+} | {
+    type: "SET_VIEW";
+    payload: CalendarView;
+};
+
+declare const DEFAULT_LABELS: CalendarLabels;
+declare const DEFAULT_LOCALE: CalendarLocale;
+declare const DEFAULT_VIEW: CalendarView;
+declare const HOURS_IN_DAY = 24;
+declare const MINUTES_IN_HOUR = 60;
+declare const MINUTES_IN_DAY: number;
+declare const VIEWS: CalendarView[];
+declare const DEFAULT_DAY_START_HOUR = 0;
+declare const DEFAULT_DAY_END_HOUR = 24;
+
+/** Parse an ISO string into a Date object (local time) */
+declare function parseDate(iso: DateString | DateTimeString): Date;
+/** Format a Date object as YYYY-MM-DD */
+declare function toDateString(date: Date): DateString;
+/** Format a Date object as ISO datetime string */
+declare function toDateTimeString(date: Date): DateTimeString;
+/** Add N days to a date string, returns a DateString */
+declare function addDays(date: DateString | DateTimeString, days: number): DateString;
+/** Add N months to a date string */
+declare function addMonths(date: DateString, months: number): DateString;
+/** Add N weeks to a date string */
+declare function addWeeks(date: DateString, weeks: number): DateString;
+/** Get the start of the week for a given date */
+declare function startOfWeek(date: DateString, weekStartsOn?: number): DateString;
+/** Get the start of the month */
+declare function startOfMonth(date: DateString): DateString;
+/** Get the end of the month */
+declare function endOfMonth(date: DateString): DateString;
+/** Check if two date strings represent the same day */
+declare function isSameDay(a: DateString | DateTimeString, b: DateString | DateTimeString): boolean;
+/** Check if two date strings are in the same month */
+declare function isSameMonth(a: DateString, b: DateString): boolean;
+/** Check if a date is today */
+declare function isToday(date: DateString): boolean;
+/** Check if date a is before date b */
+declare function isBefore(a: DateString | DateTimeString, b: DateString | DateTimeString): boolean;
+/** Check if date a is after date b */
+declare function isAfter(a: DateString | DateTimeString, b: DateString | DateTimeString): boolean;
+/** Check if two date ranges overlap */
+declare function rangesOverlap(startA: DateTimeString, endA: DateTimeString, startB: DateTimeString, endB: DateTimeString): boolean;
+/** Check if a date falls within a range (inclusive start, exclusive end) */
+declare function dateInRange(date: DateString, rangeStart: DateString, rangeEnd: DateString): boolean;
+/** Get the number of days between two dates */
+declare function daysBetween(a: DateString, b: DateString): number;
+/** Generate an array of DateStrings from start to end (inclusive) */
+declare function eachDayOfRange(start: DateString, end: DateString): DateString[];
+/** Get the array of 7 day headers for a given week start */
+declare function getWeekDays(weekStart: DateString): DateString[];
+/** Get the visible date range for the month view (includes padding days) */
+declare function getMonthViewRange(date: DateString, weekStartsOn?: number): {
+    start: DateString;
+    end: DateString;
+};
+/** Get the visible date range for the week view */
+declare function getWeekViewRange(date: DateString, weekStartsOn?: number): {
+    start: DateString;
+    end: DateString;
+};
+/** Get the visible date range for a given view */
+declare function getVisibleRange(date: DateString, view: "month" | "week" | "day" | "agenda", weekStartsOn?: number): {
+    start: DateString;
+    end: DateString;
+};
+/** Get the fractional hour from a datetime string (e.g., "2024-01-01T14:30:00" -> 14.5) */
+declare function getTimeOfDay(datetime: DateTimeString): number;
+/** Get the duration in hours between two datetime strings */
+declare function getDurationHours(start: DateTimeString, end: DateTimeString): number;
+/** Generate time slot labels for a day (e.g., ["12 AM", "1 AM", ...]) */
+declare function getHourLabels(startHour?: number, endHour?: number, locale?: string): string[];
+
+/** Format a date for the toolbar title based on view */
+declare function formatToolbarTitle(date: DateString, view: CalendarView, locale?: string): string;
+/** Format a date as a short weekday name (Mon, Tue, ...) */
+declare function formatWeekdayShort(date: DateString, locale?: string): string;
+/** Format a date as a narrow weekday name (M, T, ...) */
+declare function formatWeekdayNarrow(date: DateString, locale?: string): string;
+/** Format a day number */
+declare function formatDayNumber(date: DateString, locale?: string): string;
+/** Format a time (e.g., "2:30 PM") */
+declare function formatTime(datetime: DateTimeString, locale?: string): string;
+/** Format a time range */
+declare function formatTimeRange(start: DateTimeString, end: DateTimeString, locale?: string): string;
+/** Format a full date for agenda view */
+declare function formatAgendaDate(date: DateString, locale?: string): string;
+/** Format month + day for column headers */
+declare function formatMonthDay(date: DateString, locale?: string): string;
+
+declare function createInitialState(date?: string, view?: CalendarView): CalendarState;
+declare function calendarReducer(state: CalendarState, action: CalendarAction): CalendarState;
+
+/** Sort events by start time, then by duration (longest first) */
+declare function sortEvents(events: CalendarEvent[]): CalendarEvent[];
+/** Filter events that fall within a date range */
+declare function filterEventsInRange(events: CalendarEvent[], rangeStart: DateString, rangeEnd: DateString): CalendarEvent[];
+/** Get events for a specific day */
+declare function getEventsForDay(events: CalendarEvent[], date: DateString): CalendarEvent[];
+/** Check if an event spans multiple days */
+declare function isMultiDayEvent(event: CalendarEvent): boolean;
+/** Separate events into all-day and timed categories */
+declare function partitionEvents(events: CalendarEvent[]): {
+    allDay: CalendarEvent[];
+    timed: CalendarEvent[];
+};
+/** Break a multi-day event into per-day segments */
+declare function segmentMultiDayEvent(event: CalendarEvent, rangeStart: DateString, rangeEnd: DateString): EventSegment[];
+/** Get all event segments for a month view */
+declare function getEventSegments(events: CalendarEvent[], rangeStart: DateString, rangeEnd: DateString): EventSegment[];
+/**
+ * Segment a timed multi-day event into per-day segments for week/day view.
+ * Each segment has startHour/endHour appropriate for that day:
+ * - First day: event start time → dayEndHour
+ * - Middle days: dayStartHour → dayEndHour
+ * - Last day: dayStartHour → event end time
+ */
+declare function segmentTimedMultiDayEvent(event: CalendarEvent, days: DateString[], dayStartHour: number, dayEndHour: number): TimedEventSegment[];
+interface OverlapGroup {
+    events: CalendarEvent[];
+}
+/** Build overlap groups using a sweep-line approach */
+declare function buildOverlapGroups(events: CalendarEvent[]): OverlapGroup[];
+/** Assign columns to events within an overlap group (greedy leftmost available) */
+declare function assignColumns(group: OverlapGroup): {
+    event: CalendarEvent;
+    column: number;
+    totalColumns: number;
+}[];
+/** Compute positioned events for a single day in a time grid */
+declare function computeTimePositions(events: CalendarEvent[], dayStartHour?: number, dayEndHour?: number): PositionedEvent[];
+/** Group events by date for agenda view */
+declare function groupEventsByDate(events: CalendarEvent[], rangeStart: DateString, rangeEnd: DateString): Map<DateString, CalendarEvent[]>;
+
+/**
+ * Snap a fractional hour to the nearest increment.
+ * @param fractionalHour e.g. 9.73
+ * @param minutes snap increment in minutes (default 15)
+ * @returns snapped fractional hour e.g. 9.75
+ */
+declare function snapToIncrement(fractionalHour: number, minutes?: number): number;
+/**
+ * Convert a fractional hour on a given day to a DateTimeString.
+ * @param day date string (YYYY-MM-DD)
+ * @param fractionalHour e.g. 14.5 → "14:30:00"
+ */
+declare function fractionalHourToDateTime(day: DateString, fractionalHour: number): DateTimeString;
+/**
+ * Convert a mouse Y position relative to a column element to a fractional hour.
+ * @param clientY mouse clientY
+ * @param columnRect bounding rect of the day column
+ * @param dayStart start hour of the grid (e.g. 0)
+ * @param dayEnd end hour of the grid (e.g. 24)
+ * @returns fractional hour (e.g. 14.5)
+ */
+declare function yPositionToFractionalHour(clientY: number, columnRect: DOMRect, dayStart: number, dayEnd: number): number;
+/**
+ * Normalize a range so start <= end (swap if dragged upward).
+ */
+declare function normalizeRange(a: number, b: number): {
+    start: number;
+    end: number;
+};
+/**
+ * Compute new start/end DateTimeStrings from a drop/resize based on mouse Y.
+ * Extracted from WeekView's drop handler for shared use.
+ */
+declare function computeDropPosition(day: DateString, clientY: number, columnRect: DOMRect, dayStartHour: number, dayEndHour: number, durationMs: number): {
+    newStart: DateTimeString;
+    newEnd: DateTimeString;
+};
+
+/**
+ * Generate occurrence dates for a recurrence rule within a visible range.
+ * Returns an array of DateStrings where the event occurs.
+ */
+declare function generateOccurrences(rule: RecurrenceRule, eventStartDate: DateString, rangeStart: DateString, rangeEnd: DateString, exDates?: DateString[]): DateString[];
+/**
+ * Expand recurring events into individual instances within a visible range.
+ * Non-recurring events pass through unchanged.
+ * Instance IDs follow the pattern: `${parentId}::${YYYY-MM-DD}`
+ */
+declare function expandRecurringEvents(events: CalendarEvent[], rangeStart: DateString, rangeEnd: DateString): CalendarEvent[];
+/**
+ * Parse an RFC 5545 RRULE string into a RecurrenceRule.
+ * Supports: FREQ, INTERVAL, COUNT, UNTIL, BYDAY, BYMONTHDAY, BYSETPOS
+ * @example parseRRule("FREQ=WEEKLY;INTERVAL=2;BYDAY=MO,WE,FR")
+ */
+declare function parseRRule(rruleString: string): RecurrenceRule;
+/**
+ * Serialize a RecurrenceRule to an RFC 5545 RRULE string.
+ * @example toRRuleString({freq: "weekly", byDay: ["MO", "WE", "FR"]})
+ * // → "FREQ=WEEKLY;BYDAY=MO,WE,FR"
+ */
+declare function toRRuleString(rule: RecurrenceRule): string;
+
+interface VirtualRange {
+    startHour: number;
+    endHour: number;
+}
+/**
+ * Filter positioned events to only those visible in the viewport.
+ * Includes events within the viewport plus an overscan buffer.
+ *
+ * @param positioned - Events with top/height as percentages (0-100)
+ * @param viewportTop - Top edge of viewport as percentage (0-100)
+ * @param viewportBottom - Bottom edge of viewport as percentage (0-100)
+ * @param overscan - Extra percentage to render above/below (default 10)
+ */
+declare function filterVisibleEvents(positioned: PositionedEvent[], viewportTop: number, viewportBottom: number, overscan?: number): PositionedEvent[];
+/**
+ * Convert scroll position to viewport range in hours.
+ *
+ * @param scrollTop - Current scrollTop of the container
+ * @param containerHeight - Visible height of the scroll container
+ * @param totalHeight - Total scrollable height (scrollHeight)
+ * @param dayStartHour - First hour of the day grid
+ * @param dayEndHour - Last hour of the day grid
+ */
+declare function scrollToViewportRange(scrollTop: number, containerHeight: number, totalHeight: number, dayStartHour: number, dayEndHour: number): VirtualRange;
+
+/** Immutable undo/redo stack */
+interface UndoStack<T> {
+    past: T[];
+    present: T;
+    future: T[];
+}
+/**
+ * Create a new undo stack with an initial present state.
+ */
+declare function createUndoStack<T>(initial: T): UndoStack<T>;
+/**
+ * Push a new state onto the stack.
+ * - Moves current present to past
+ * - Clears future (branching erases redo history)
+ * - Caps past at `maxHistory` entries
+ */
+declare function pushState<T>(stack: UndoStack<T>, state: T, maxHistory?: number): UndoStack<T>;
+/**
+ * Undo: move present to future, restore most recent past as present.
+ * Returns the same stack if there is nothing to undo.
+ */
+declare function undo<T>(stack: UndoStack<T>): UndoStack<T>;
+/**
+ * Redo: move present to past, restore most recent future as present.
+ * Returns the same stack if there is nothing to redo.
+ */
+declare function redo<T>(stack: UndoStack<T>): UndoStack<T>;
+/**
+ * Whether the stack has past entries to undo.
+ */
+declare function canUndo<T>(stack: UndoStack<T>): boolean;
+/**
+ * Whether the stack has future entries to redo.
+ */
+declare function canRedo<T>(stack: UndoStack<T>): boolean;
+
+export { type AgendaEventSlotProps, type AllDayEventSlotProps, type CalendarAction, type CalendarConfig, type CalendarEvent, type CalendarLabels, type CalendarLocale, type CalendarSlots, type CalendarState, type CalendarView, DEFAULT_DAY_END_HOUR, DEFAULT_DAY_START_HOUR, DEFAULT_LABELS, DEFAULT_LOCALE, DEFAULT_VIEW, type DateString, type DateTimeString, type DayCellSlotProps, type EventSegment, type EventSlotProps, HOURS_IN_DAY, MINUTES_IN_DAY, MINUTES_IN_HOUR, type PopoverSlotProps, type PositionedEvent, type RecurrenceDay, type RecurrenceFrequency, type RecurrenceRule, type TimeEventSlotProps, type TimedEventSegment, type ToolbarSlotProps, type UndoStack, VIEWS, type VirtualRange, addDays, addMonths, addWeeks, assignColumns, buildOverlapGroups, calendarReducer, canRedo, canUndo, computeDropPosition, computeTimePositions, createInitialState, createUndoStack, dateInRange, daysBetween, eachDayOfRange, endOfMonth, expandRecurringEvents, filterEventsInRange, filterVisibleEvents, formatAgendaDate, formatDayNumber, formatMonthDay, formatTime, formatTimeRange, formatToolbarTitle, formatWeekdayNarrow, formatWeekdayShort, fractionalHourToDateTime, generateOccurrences, getDurationHours, getEventSegments, getEventsForDay, getHourLabels, getMonthViewRange, getTimeOfDay, getVisibleRange, getWeekDays, getWeekViewRange, groupEventsByDate, isAfter, isBefore, isMultiDayEvent, isSameDay, isSameMonth, isToday, normalizeRange, parseDate, parseRRule, partitionEvents, pushState, rangesOverlap, redo, scrollToViewportRange, segmentMultiDayEvent, segmentTimedMultiDayEvent, snapToIncrement, sortEvents, startOfMonth, startOfWeek, toDateString, toDateTimeString, toRRuleString, undo, yPositionToFractionalHour };