calendar-simple 1.2.0 → 2.0.0-beta.1

package/dist/src/types/theme.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @file Theme and CSS class name customization types for the calendar.
+ */
+/**
+ * CSS class name overrides for individual calendar elements.
+ * Each key targets a specific DOM element; assign a custom class to override default styles.
+ */
+export interface CalendarClassNames {
+    /** Root calendar container. */
+    root?: string;
+    /** Header bar containing navigation controls and view switcher. */
+    header?: string;
+    /** Month view table grid. */
+    table?: string;
+    /** Day-of-week header row in the month grid. */
+    tableHeader?: string;
+    /** Individual date cell in the month grid. */
+    tableDate?: string;
+    /** Week number label in the leftmost column (requires `showWeekNumbers`). */
+    weekNumber?: string;
+    /** Event chip element — applies across all views. */
+    event?: string;
+    /** Date cell or event marked as currently selected. */
+    selected?: string;
+    /** Date cell or event representing today. */
+    today?: string;
+    /** Date column header in Week / Day views. */
+    dayHeader?: string;
+    /** Day name label (e.g. "Mon") inside the column header. */
+    dayName?: string;
+    /** Day number label inside the column header. */
+    dayNumber?: string;
+    /** Left-side time label column in the time grid. */
+    timeColumn?: string;
+    /** Individual hour row in the time grid. */
+    timeSlot?: string;
+    /** Vertical day column in the time grid. */
+    dayColumn?: string;
+    /** Date group header row in Schedule view. */
+    scheduleDateGroup?: string;
+    /** Date number within the Schedule view group header. */
+    scheduleDateNumber?: string;
+    /** Sub-info text (day name / relative label) in the Schedule group header. */
+    scheduleDateSubInfo?: string;
+    /** Time label on a Schedule event row. */
+    scheduleTime?: string;
+    /** Title label on a Schedule event row. */
+    scheduleTitle?: string;
+}
+/**
+ * A color pair (text + background) used for theme state overrides.
+ */
+export interface ThemeStyle {
+    /** Text / foreground color (any valid CSS color value). */
+    color?: string;
+    /** Background color (any valid CSS color value). */
+    bgColor?: string;
+}
+/**
+ * Per-state color overrides for a single color scheme.
+ */
+export interface ThemeScheme {
+    /** Colors for standard, unselected, non-today date cells. */
+    default?: ThemeStyle;
+    /** Colors for the currently selected date. */
+    selected?: ThemeStyle;
+    /** Colors for today's date cell. */
+    today?: ThemeStyle;
+}
+/**
+ * Color overrides applied to key calendar states.
+ * Flat keys apply to both schemes unless overridden.
+ * `dark` / `light` sub-objects take precedence over flat keys
+ * when the resolved color scheme matches.
+ */
+export interface CalendarTheme extends ThemeScheme {
+    /** Overrides applied only when the resolved scheme is "dark". */
+    dark?: ThemeScheme;
+    /** Overrides applied only when the resolved scheme is "light". */
+    light?: ThemeScheme;
+}

package/dist/src/utils/common.d.ts

@@ -0,0 +1,48 @@
+import { KeyboardEvent } from 'react';
+import { CalendarEvent } from '../types';
+import { DateType } from './date';
+/**
+ * Calculates the maximum number of events that can be displayed in a cell based on the calendar height.
+ *
+ * @param height - The total height of the calendar
+ * @returns The maximum number of events to display
+ */
+export declare function calculateMaxEvents(height: number, rowsInView: number): number;
+/**
+ * Helper to determine if an event is an all-day event.
+ * An event is considered "all-day" if its start and end date strings
+ * contain only a date (e.g. yyyy-MM-dd) and no time component (no 'T' or space).
+ *
+ * @param event - The calendar event to check.
+ * @returns True if the event has no time payload.
+ */
+export declare function isAllDayEvent(event: CalendarEvent): boolean;
+/**
+ * Helper to determine if an event spans across multiple distinct calendar days.
+ * Compares the start of the day for both startDate and endDate.
+ *
+ * @param event - The calendar event to check.
+ * @returns True if the event starts and ends on different days.
+ */
+export declare function isMultiDay(event: CalendarEvent): boolean;
+/**
+ * Calculates the overlap duration in hours of an event with a specific calendar day boundary (00:00 to 23:59).
+ *
+ * @param event - The calendar event.
+ * @param date - The day to check the overlap against.
+ * @returns The overlap duration in hours (e.g., 2.5). Returns 24 for all-day events.
+ */
+export declare function getEventOverlapInHours(event: CalendarEvent, date: DateType): number;
+/**
+ * Resolves layout direction. Explicit `direction` prop wins; otherwise infers from
+ * the locale's primary subtag. Defaults to `'ltr'` when both are undefined.
+ */
+export declare function resolveDirection(direction: "ltr" | "rtl" | undefined, locale: string | undefined): "ltr" | "rtl";
+/**
+ * Wraps a handler so it only fires on Enter or Space — the standard keyboard activation keys.
+ * Prevents default and stops propagation to avoid scroll or form submission side effects.
+ *
+ * @param handler - The callback to invoke on activation.
+ * @returns A keyboard event handler suitable for `onKeyDown`.
+ */
+export declare function handleKeyboardActivation(handler: (e: KeyboardEvent) => void): (e: KeyboardEvent) => void;

package/dist/src/utils/common.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/utils/contrast.d.ts

@@ -0,0 +1,18 @@
+import { CalendarTheme, ThemeScheme } from '../types';
+/**
+ * Determines the best contrast color (black or white) for a given background color.
+ * Follows WCAG 2.1 standards for readability.
+ *
+ * @param bgColor - The CSS background color (Hex, RGB, or named color).
+ * @returns "#FFFFFF" or "#212529" (a very dark gray, softer than pure black).
+ */
+export declare function getContrastColor(bgColor?: string): string;
+/**
+ * Merges flat CalendarTheme values with the scheme-specific sub-object.
+ * Scheme-specific values win on a per-field basis.
+ *
+ * @param theme  - Raw theme from CalendarProps (may be undefined or {}).
+ * @param scheme - Resolved color scheme ("light" | "dark") from context.
+ * @returns A flat ThemeScheme with no nested keys.
+ */
+export declare function resolveTheme(theme: CalendarTheme | undefined, scheme: "light" | "dark"): ThemeScheme;

package/dist/src/utils/contrast.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/utils/date.d.ts

@@ -0,0 +1,55 @@
+import { DateTime } from 'luxon';
+export type DateType = DateTime;
+export type DateInputType = Date | DateTime | string | number;
+/**
+ * Normalizes various date inputs into a Luxon DateTime object.
+ */
+export declare function dateFn(date?: DateInputType): DateTime;
+export declare function getStartOfDay(date: DateInputType): DateType;
+export declare function getStartOfMonth(date: DateType): DateType;
+export declare function addDays(date: DateType, days: number): DateType;
+export declare function subDays(date: DateType, days: number): DateType;
+export declare function getDiffDays(date1: DateInputType, date2: DateInputType): number;
+export declare function setDate(date: DateType, day: number): DateType;
+export declare function setMonth(date: DateType, month: number): DateType;
+export declare function setYear(date: DateType, year: number): DateType;
+export declare function getDate(date: DateType): number;
+export declare function getMonth(date: DateType): number;
+export declare function getYear(date: DateType): number;
+export declare function isBeforeDate(date1: DateInputType, date2: DateInputType): boolean;
+export declare function isAfterDate(date1: DateInputType, date2: DateInputType): boolean;
+export declare function isSameDate(date1: DateInputType, date2: DateInputType): boolean;
+export declare function formatDate(date: DateInputType, format: string, locale?: string): string;
+export declare function convertToDate(luxonDate: DateType): Date;
+/**
+ * Determines the day of the week (0-6)
+ *
+ * @param date - A DateType representing the target date.
+ * @returns The numeric index of the day (0 = Sunday, 1 = Monday, etc.).
+ */
+export declare function getDayOfWeek(date: DateType): number;
+/**
+ * Determines the day of the week (0-6) on which a given month starts.
+ *
+ * @param date - A DateType representing the target month.
+ * @returns The numeric index of the starting day (0 = Sunday, 1 = Monday, etc.).
+ */
+export declare function getMonthStartingDay(date: DateType): number;
+/**
+ * Checks whether a specific numeric date within a targeted month matches today's date.
+ *
+ * @param selectedDate - The base month/year context.
+ * @param dates - The specific numeric day of the month (1-31).
+ * @returns True if the assembled date is the exact current calendar day.
+ */
+export declare function checkIsToday(selectedDate: DateType, dates: number): boolean;
+/**
+ * Generates an array of years centered around or including the `selectedYear`.
+ * Useful for populating year-selection dropdowns or pickers.
+ *
+ * @param pastLength - Number of historical years to include from the current date.
+ * @param futureLength - Number of future years to include from the current date.
+ * @param selectedYear - Ensures this year is included in the array if it falls outside the requested bounds.
+ * @returns An array of numeric years.
+ */
+export declare function getYearList(pastLength: number, futureLength: number, selectedYear: number): number[];

package/dist/src/utils/date.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/utils/formatting.d.ts

@@ -0,0 +1,21 @@
+import { CalendarEvent, ECalendarViewType, EDayType, MonthListType } from '../types';
+/**
+ * Generates the tooltip text for an event based on the view type.
+ * Adapts the formatting (whether to include explicit dates, times, or both)
+ * dynamically based on if it's month/week view, or all-day vs timed.
+ *
+ * @param event - The calendar event hovering over.
+ * @param viewType - The current enum view mode of the calendar.
+ * @param is12Hour - Boolean indicating if the user is employing a 12-hour clock.
+ * @returns A formatted string ready for tooltip display.
+ */
+export declare function generateTooltipText(event: CalendarEvent, viewType: ECalendarViewType, is12Hour?: boolean, locale?: string): string;
+/**
+ * Returns a formatted GMT offset string based on the user's local timezone.
+ * Useful for displaying timezone indicators on the calendar grid.
+ *
+ * @returns A formatted string like "GMT+05:30" or "GMT-08".
+ */
+export declare function getGmtOffset(): string;
+export declare function getDayListNames(dayType: EDayType, locale?: string): string[];
+export declare function getMonthList(locale?: string): MonthListType[];

package/dist/src/utils/formatting.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/utils/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @file index.ts
+ * @description Barrel file exporting all shared utility functions to abstract away
+ * internal file structures from consumers.
+ */
+export * from './date';
+export * from './common';
+export * from './formatting';
+export * from './contrast';