calendar-simple 1.2.0 → 2.0.0-beta.1

package/dist/src/hooks/useMonthGrid.d.ts

@@ -0,0 +1,44 @@
+import { DateType } from '../utils/date';
+import { CalendarEvent, EventListType } from '../types';
+/**
+ * Represents the information for a single day in the calendar grid.
+ */
+interface CalendarDayInfo {
+    /** The full date object */
+    currentDate: DateType;
+    /** Whether the day belongs to the currently selected month (for styling) */
+    isCurrentMonth: boolean;
+    /** The day number to display (1-31) */
+    displayDay: number;
+    /** List of events or spacers for this day's slots */
+    events: (EventListType | null)[];
+    /** Total number of events on this day (including hidden ones) */
+    totalEvents: number;
+    /** Whether this day is today */
+    isToday: boolean;
+}
+/**
+ * 2D array representing the calendar grid: [week][day]
+ */
+type CalendarMatrix = CalendarDayInfo[][];
+/**
+ * Generates the grid of days and events for the monthly view.
+ *
+ * This function handles:
+ * 1. Grid Generation: Calculates the days for each week, handling previous/next month overlap.
+ * 2. Event Processing: Filters events for each week and sorts them.
+ * 3. Slot Assignment: Uses a "tetris-like" algorithm to stack overlapping events into available vertical slots.
+ * 4. Data Preparation: Formats the data for the UI, including calculating event continuity across days.
+ *
+ * @param selectedDate - The currently selected date (determining the month to show)
+ * @returns A structured matrix of weeks and days with assigned events
+ */
+export interface UseMonthGridOptions {
+    enableEnrichedEvents?: boolean;
+    enrichedEventsByDate?: Record<string, CalendarEvent[]>;
+    eventsAreSorted?: boolean;
+    isEventOrderingEnabled?: boolean;
+    sortedMonthView?: boolean | ((a: CalendarEvent, b: CalendarEvent) => number);
+}
+export default function useMonthGrid(selectedDate: DateType, events: CalendarEvent[], weekStartsOn: number, weekEndsOn: number, options?: UseMonthGridOptions): CalendarMatrix;
+export {};

package/dist/src/hooks/useMonthGrid.test.d.ts

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

package/dist/src/hooks/useResizeObserver.d.ts

@@ -0,0 +1,13 @@
+import { RefObject } from 'react';
+/**
+ * Hook to observe the size of an element.
+ *
+ * @param ref - React ref object attached to the element to observe.
+ * @param notNeeded - Optional flag to bypass the observer. Useful for performance
+ *                    if the observer is conditionally required.
+ * @returns An object containing the observed `width` and `height`.
+ */
+export default function useResizeObserver(ref: RefObject<HTMLElement | null>, notNeeded?: boolean): {
+    width: number;
+    height: number;
+};

package/dist/src/hooks/useResizeObserver.test.d.ts

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

package/dist/src/hooks/useScheduleView.d.ts

@@ -0,0 +1,24 @@
+import { CalendarEvent } from '../types';
+/**
+ * Properties for configuring the schedule view hook.
+ */
+interface UseScheduleViewProps {
+    events: CalendarEvent[];
+    autoScrollToCurrentTime?: boolean;
+    is12Hour?: boolean;
+    locale?: string;
+}
+/**
+ * Hook to process calendar events into grouped daily lists for the Schedule agenda.
+ *
+ * @param props - Configuration properties { events, autoScrollToCurrentTime, is12Hour }
+ * @returns Object with a ref to attach to "today", the grouped event map, and formatters.
+ */
+export default function useScheduleView({ events, autoScrollToCurrentTime, is12Hour, locale, }: UseScheduleViewProps): {
+    todayRef: import('react').RefObject<HTMLDivElement | null>;
+    containerRef: import('react').RefObject<HTMLDivElement | null>;
+    groupedEvents: Record<string, CalendarEvent[]>;
+    renderEventTime: (event: CalendarEvent, dateKey: string) => string;
+    renderEventTitle: (event: CalendarEvent, dateKey: string) => string;
+};
+export {};

package/dist/src/hooks/useScheduleView.test.d.ts

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

package/dist/src/index.d.ts

@@ -0,0 +1,13 @@
+import { default as Calendar } from './Calendar';
+export { EDayType, ECalendarViewType } from './types';
+export type { CalendarProps, CalendarEvent, CalendarContentProps, ColorScheme, CalendarTheme, ThemeScheme, } from './types';
+export type { HeaderProps } from './components/layout/Header';
+export type { ViewProps } from './components/views/View';
+export type { MonthViewProps } from './components/views/month_view/MonthView';
+export type { WeekViewProps } from './components/views/week_view/WeekView';
+export type { DayViewProps } from './components/views/day_view/DayView';
+export type { ScheduleViewProps } from './components/views/schedule_view/ScheduleView';
+export type { CustomViewProps } from './components/views/custom_days_view/CustomDaysView';
+export { CalendarProvider, useCalendar } from './context/CalendarContext';
+export { CALENDAR_ACTIONS } from './constants';
+export default Calendar;

package/dist/src/stories/Accessibility.stories.d.ts

@@ -0,0 +1,10 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { default as Calendar } from '../';
+declare const meta: Meta<typeof Calendar>;
+export default meta;
+type Story = StoryObj<typeof Calendar>;
+export declare const MonthViewKeyboardNav: Story;
+export declare const WeekViewKeyboardNav: Story;
+export declare const DayViewCreatableSlots: Story;
+export declare const ScheduleViewKeyboardNav: Story;
+export declare const PopoverFocusTrap: Story;

package/dist/src/stories/CustomDayView.stories.d.ts

@@ -0,0 +1,10 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { default as Calendar } from '../';
+declare const meta: Meta<typeof Calendar>;
+export default meta;
+type Story = StoryObj<typeof Calendar>;
+export declare const Default: Story;
+export declare const WithEvents: Story;
+export declare const FiveDays: Story;
+export declare const OneDay: Story;
+export declare const TenDays: Story;

package/dist/src/stories/Customization.stories.d.ts

@@ -0,0 +1,29 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { default as Calendar } from '../';
+declare const meta: Meta<typeof Calendar>;
+export default meta;
+type Story = StoryObj<typeof Calendar>;
+export declare const EventStyle: Story;
+export declare const EventClassNames: Story;
+export declare const ScheduleViewCustomization: Story;
+export declare const CustomRenderers: Story;
+export declare const PagerResets: Story;
+export declare const ConcurrentEventStacking: Story;
+export declare const ScheduleViewCustomSeparator: Story;
+/** Forces the light palette regardless of OS preference. */
+export declare const ColorSchemeLight: Story;
+/** Forces the dark palette regardless of OS preference. */
+export declare const ColorSchemeDark: Story;
+/**
+ * Auto mode (default): follows the OS `prefers-color-scheme` preference.
+ * To verify the live-update behavior, change the OS theme (or use Chrome DevTools →
+ * Rendering → "Emulate CSS prefers-color-scheme") and watch the calendar reflow.
+ */
+export declare const ColorSchemeAuto: Story;
+/** Month view in dark mode — verifies grid borders, week number column, and adjacent-month cells. */
+export declare const ColorSchemeDarkMonth: Story;
+/** Schedule view in dark mode — verifies date number, event row, and divider colors. */
+export declare const ColorSchemeDarkSchedule: Story;
+/** Per-scheme theme overrides: dark mode uses a different selected/today color than light mode. */
+export declare const ColorSchemePerSchemTheme: Story;
+export declare const HideAllDayRow: Story;

package/dist/src/stories/DayView.stories.d.ts

@@ -0,0 +1,11 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { default as Calendar } from '../';
+declare const meta: Meta<typeof Calendar>;
+export default meta;
+type Story = StoryObj<typeof Calendar>;
+export declare const Default: Story;
+export declare const WithEvents: Story;
+export declare const OverlappingEvents: Story;
+export declare const Format12Hour: Story;
+export declare const AutoScrollToCurrentTime: Story;
+export declare const WithTimeLimits: Story;

package/dist/src/stories/Features.stories.d.ts

@@ -0,0 +1,25 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { default as Calendar } from '../';
+declare const meta: Meta<typeof Calendar>;
+export default meta;
+type Story = StoryObj<typeof Calendar>;
+export declare const TimeFormat12Hour: Story;
+export declare const TimeFormat24Hour: Story;
+export declare const InteractiveEvents: Story;
+export declare const InteractiveDates: Story;
+export declare const NavigationCallback: Story;
+export declare const MaxEventsOverflowLimit: Story;
+export declare const CustomTheming: Story;
+export declare const AutoScrollToCurrentTime: Story;
+export declare const ShowAdjacentMonthsEnabled: Story;
+export declare const ShowAdjacentMonthsDisabled: Story;
+export declare const ClickToCreateTimeGrid: Story;
+export declare const ClickToCreateMonth: Story;
+export declare const ClickToCreateWithSelectable: Story;
+export declare const CompoundComponentPattern: Story;
+export declare const LoadingSkeletonMonth: Story;
+export declare const LoadingSkeletonWeek: Story;
+export declare const LoadingSkeletonDay: Story;
+export declare const LoadingSkeletonSchedule: Story;
+export declare const LoadingWithExistingEvents: Story;
+export declare const LoadingCustomRenderer: Story;

package/dist/src/stories/Localization.stories.d.ts

@@ -0,0 +1,22 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { default as Calendar } from '../';
+declare const meta: Meta<typeof Calendar>;
+export default meta;
+type Story = StoryObj<typeof Calendar>;
+export declare const DynamicLocale: Story;
+export declare const French: Story;
+/**
+ * Arabic locale auto-derives `direction: "rtl"`. The calendar layout flips:
+ * navigation arrows mirror, time column moves to the right, day columns flow right-to-left.
+ */
+export declare const ArabicRTL: Story;
+/**
+ * Arabic content with explicit LTR layout — proves the `direction` prop overrides
+ * the locale auto-fallback.
+ */
+export declare const ArabicLTR: Story;
+/** Hebrew locale auto-derives RTL; shows month view flipped. */
+export declare const HebrewRTL: Story;
+export declare const WeekStartSaturday: Story;
+export declare const JapaneseSchedule: Story;
+export declare const CustomMessagesFull: Story;

package/dist/src/stories/MonthView.stories.d.ts

@@ -0,0 +1,13 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { default as Calendar } from '../';
+declare const meta: Meta<typeof Calendar>;
+export default meta;
+type Story = StoryObj<typeof Calendar>;
+export declare const Default: Story;
+export declare const WithEvents: Story;
+export declare const ManyEventsOverflow: Story;
+export declare const ReadOnly: Story;
+export declare const FullDayNames: Story;
+export declare const CustomWeekStartEnd: Story;
+export declare const ShowWeekNumbers: Story;
+export declare const SortedMonthView: Story;

package/dist/src/stories/QA/EdgeCases.stories.d.ts

@@ -0,0 +1,12 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { default as Calendar } from '../../index';
+declare const meta: Meta<typeof Calendar>;
+export default meta;
+type Story = StoryObj<typeof Calendar>;
+export declare const AbsoluteOverlap: Story;
+export declare const ConcurrentStress: Story;
+export declare const NestedOverlaps: Story;
+export declare const LayoutOverlapOffset: Story;
+export declare const DurationOddities: Story;
+export declare const MultiDayOvernight: Story;
+export declare const MissingDataFields: Story;

package/dist/src/stories/QA/Interactions.stories.d.ts

@@ -0,0 +1,8 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { default as Calendar } from '../../index';
+declare const meta: Meta<typeof Calendar>;
+export default meta;
+type Story = StoryObj<typeof Calendar>;
+export declare const CallbacksAndSelectable: Story;
+export declare const DisabledSelectable: Story;
+export declare const ControlledState: Story;

package/dist/src/stories/QA/LayoutLimits.stories.d.ts

@@ -0,0 +1,11 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { default as Calendar } from '../../index';
+declare const meta: Meta<typeof Calendar>;
+export default meta;
+type Story = StoryObj<typeof Calendar>;
+export declare const AllDayBannerConstraints: Story;
+export declare const HideAllDayRow: Story;
+export declare const AdjacentMonthsHidden: Story;
+export declare const WorkWeekBoundaries: Story;
+export declare const TimeRangeLimits: Story;
+export declare const PastFutureYearBounds: Story;

package/dist/src/stories/QA/Performance.stories.d.ts

@@ -0,0 +1,9 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { default as Calendar } from '../../index';
+declare const meta: Meta<typeof Calendar>;
+export default meta;
+type Story = StoryObj<typeof Calendar>;
+export declare const BaselineUnoptimized3000: Story;
+export declare const SortedEventsBypass: Story;
+export declare const FastUnorderedPlacement: Story;
+export declare const EnrichedDictionaryFastPath: Story;

package/dist/src/stories/QA/TimeFormatting.stories.d.ts

@@ -0,0 +1,11 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { default as Calendar } from '../../index';
+declare const meta: Meta<typeof Calendar>;
+export default meta;
+type Story = StoryObj<typeof Calendar>;
+export declare const TwelveHourFormat: Story;
+export declare const TwentyFourHourFormat: Story;
+export declare const ShowCurrentTimeIndicator: Story;
+export declare const HideCurrentTimeIndicator: Story;
+export declare const AutoScrollEnabled: Story;
+export declare const AutoScrollDisabled: Story;

package/dist/src/stories/QA/Views.stories.d.ts

@@ -0,0 +1,10 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { default as Calendar } from '../../index';
+declare const meta: Meta<typeof Calendar>;
+export default meta;
+type Story = StoryObj<typeof Calendar>;
+export declare const MonthViewTest: Story;
+export declare const WeekViewTest: Story;
+export declare const DayViewTest: Story;
+export declare const CustomDaysTest: Story;
+export declare const ScheduleViewTest: Story;

package/dist/src/stories/ScheduleView.stories.d.ts

@@ -0,0 +1,10 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { default as Calendar } from '../';
+declare const meta: Meta<typeof Calendar>;
+export default meta;
+type Story = StoryObj<typeof Calendar>;
+export declare const Default: Story;
+export declare const WithEvents: Story;
+export declare const Format12Hour: Story;
+export declare const CustomTheme: Story;
+export declare const AutoScrollToCurrentTime: Story;

package/dist/src/stories/WeekView.stories.d.ts

@@ -0,0 +1,14 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { default as Calendar } from '../';
+declare const meta: Meta<typeof Calendar>;
+export default meta;
+type Story = StoryObj<typeof Calendar>;
+export declare const Default: Story;
+export declare const WithEvents: Story;
+export declare const OverlappingEvents: Story;
+export declare const Format12Hour: Story;
+export declare const FullDayNames: Story;
+export declare const AutoScrollToCurrentTime: Story;
+export declare const WithTimeLimits: Story;
+export declare const CustomWeekStartEnd: Story;
+export declare const MultiDayArrowTest: Story;

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

@@ -0,0 +1,213 @@
+import { ReactNode } from 'react';
+import { CalendarEvent } from './events';
+import { CalendarTheme, CalendarClassNames } from './theme';
+/** Color palette modes accepted by `CalendarProps.colorScheme`. */
+export type ColorScheme = "light" | "dark" | "auto";
+/**
+ * Makes a specific subset of keys required while leaving the rest unchanged.
+ * Used to enforce that `CalendarContentProps` always has defaults applied.
+ */
+export type RequiredSome<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+/**
+ * Available calendar view modes.
+ * Use as values for the `view` prop or `onViewChange` callback.
+ */
+export declare const ECalendarViewType: {
+    readonly month: "month";
+    readonly week: "week";
+    readonly day: "day";
+    readonly schedule: "schedule";
+    readonly customDays: "customDays";
+};
+export type ECalendarViewType = (typeof ECalendarViewType)[keyof typeof ECalendarViewType];
+/**
+ * Controls how much of the day is shown in the time grid.
+ * `full` shows all 24 hours; `half` shows 12 hours (combined with `minHour`/`maxHour`).
+ */
+export declare const EDayType: {
+    readonly full: "full";
+    readonly half: "half";
+};
+export type EDayType = (typeof EDayType)[keyof typeof EDayType];
+/**
+ * Props passed to the `renderHeader` custom renderer.
+ * Provides the current navigation state and handlers to build a fully custom header.
+ */
+export interface RenderHeaderProps {
+    /** The currently displayed date (first day of the visible period). */
+    currentDate: Date;
+    /** The active view mode. */
+    view: ECalendarViewType;
+    /** Call with a target date to programmatically navigate the calendar. */
+    onNavigate: (date: Date) => void;
+    /** Call to switch the active view. */
+    onViewChange: (view: ECalendarViewType) => void;
+}
+/**
+ * Props passed to the `renderDateCell` custom renderer in Month view.
+ * Allows replacing the default date number with a fully custom cell.
+ */
+export interface RenderDateCellProps {
+    /** The date this cell represents. */
+    date: Date;
+    /** Whether this cell is today's date. */
+    isToday: boolean;
+    /** Whether this cell is the currently selected date. */
+    isSelected?: boolean;
+    /** Whether this date belongs to the currently displayed month (false for adjacent-month cells). */
+    isCurrentMonth?: boolean;
+}
+/**
+ * Top-level props for the `<Calendar>` component.
+ */
+export interface CalendarProps {
+    /** Child components rendered inside the calendar layout (e.g. custom header). */
+    children?: ReactNode;
+    /** Events to display. Each must have at minimum `startDate` and `title`. */
+    events?: CalendarEvent[];
+    /** Initially selected date. Defaults to today if omitted. */
+    selectedDate?: Date;
+    /** Active view mode. Defaults to `month`. */
+    view?: ECalendarViewType;
+    /** `data-testid` attribute placed on the root element for testing. */
+    testId?: string;
+    /**
+     * When `true`, activates loading mode. Behaviour depends on whether events are present:
+     * - **No events:** replaces the calendar body with a skeleton (or `renderLoading()` if provided).
+     * - **Events present:** keeps the calendar visible but wraps it in a non-interactive overlay
+     *   so existing data stays on screen during a background refresh (DI-3).
+     */
+    isLoading?: boolean;
+    /**
+     * Custom loading indicator renderer. Called only when `isLoading=true` and no events are
+     * present. Falls back to a built-in view-specific skeleton when omitted.
+     */
+    renderLoading?: () => ReactNode;
+    /** Use 12-hour clock format (AM/PM) in time grids. Defaults to `false`. */
+    is12Hour?: boolean;
+    /** Allow date cells to be clicked and selected. Defaults to `true`. */
+    selectable?: boolean;
+    /** Maximum number of events shown per day cell before a "+N more" overflow link appears. */
+    maxEvents?: number;
+    /** Controls time-grid range. `full` = all 24 h; `half` = respects `minHour`/`maxHour`. */
+    dayType?: EDayType;
+    /** Number of years before today available in the year picker. */
+    pastYearLength?: number;
+    /** Number of years after today available in the year picker. */
+    futureYearLength?: number;
+    /** Show a line indicating the current time in Week / Day views. */
+    showCurrentTime?: boolean;
+    /** Scroll the time grid to the current time on initial render. */
+    autoScrollToCurrentTime?: boolean;
+    /** Earliest hour shown in the time grid (0–23). */
+    minHour?: number;
+    /** Latest hour shown in the time grid (0–23). */
+    maxHour?: number;
+    /** First day of the week: 0 = Sunday, 1 = Monday … 6 = Saturday. */
+    weekStartsOn?: number;
+    /** Last day of the week: 0–6, must be after `weekStartsOn`. */
+    weekEndsOn?: number;
+    /** Show dates from the previous / next month in the month grid. */
+    showAdjacentMonths?: boolean;
+    /** Show ISO week numbers in the leftmost column of the month grid. */
+    showWeekNumbers?: boolean;
+    /** Number of days shown in the CustomDays view. */
+    customDays?: number;
+    /** Reset the selected date to today when switching views. */
+    resetDateOnViewChange?: boolean;
+    /** Show the all-day event banner row in Week / Day views. */
+    showAllDayRow?: boolean;
+    /** Custom renderer for the date separator in Schedule view. */
+    renderScheduleSeparator?: (date: Date) => ReactNode;
+    /** Pixel offset added between overlapping events in the time grid to keep them readable. */
+    eventOverlapOffset?: number;
+    /** CSS width of the calendar container (number = px, string = any CSS value). */
+    width?: number | string;
+    /** CSS height of the calendar container (number = px, string = any CSS value). */
+    height?: number | string;
+    /** Called when a date cell is clicked. */
+    onDateClick?: (date: Date) => void;
+    /** Called when an event chip is clicked. */
+    onEventClick?: (event: CalendarEvent) => void;
+    /** Called when the "+N more" overflow link is clicked. Receives the date and the hidden events. */
+    onMoreClick?: (date: Date, hiddenEvents?: CalendarEvent[]) => void;
+    /** Called when the calendar navigates to a different date. */
+    onNavigate?: (date: Date) => void;
+    /** Called when the user switches views. */
+    onViewChange?: (view: ECalendarViewType) => void;
+    /** Allow clicking empty time slots to create new events. */
+    creatable?: boolean;
+    /** Called when an empty time slot is clicked; receives the slot's start and end date. */
+    onSlotClick?: (startDate: Date, endDate: Date) => void;
+    /** Color theme overrides for selected, today, and default states. */
+    theme?: CalendarTheme;
+    /** CSS class name overrides for individual calendar elements. */
+    classNames?: CalendarClassNames;
+    /** Replaces the default event chip with a fully custom renderer. */
+    renderEvent?: (event: CalendarEvent) => ReactNode;
+    /** Replaces the entire header bar with a custom renderer. */
+    renderHeader?: (props: RenderHeaderProps) => ReactNode;
+    /** Replaces the default hour label in the time grid left column. */
+    renderHourCell?: (date: Date) => ReactNode;
+    /** Replaces the default date number in Month view cells. */
+    renderDateCell?: (props: RenderDateCellProps) => ReactNode;
+    /** Pre-built O(1) lookup map of events keyed by date string. Avoids re-filtering on each render. */
+    enrichedEventsByDate?: Record<string, CalendarEvent[]>;
+    /** Enable O(1) event lookup via `enrichedEventsByDate`. */
+    enableEnrichedEvents?: boolean;
+    /**
+     * Skip internal validation when events are already sorted by `startDate` ascending.
+     *
+     * **Known caveat:** the library does not re-sort the array. If unsorted events are
+     * passed with this flag set to `true`, they will render in the order provided.
+     * Only set this flag when the input is guaranteed to be sorted.
+     */
+    eventsAreSorted?: boolean;
+    /** Maintain stable visual ordering of overlapping events across re-renders. */
+    isEventOrderingEnabled?: boolean;
+    /** Sort events within Month view cells. Pass `true` for default sort or a comparator for custom order. */
+    sortedMonthView?: boolean | ((a: CalendarEvent, b: CalendarEvent) => number);
+    /** Luxon locale code (e.g. `'en'`, `'fr'`, `'es-MX'`). Controls date formatting language. */
+    locale?: string;
+    /**
+     * Layout direction. When omitted, falls back to `'rtl'` if `locale` is in the RTL locale list
+     * (ar, he, fa, ur, ps, sd, ckb, yi); otherwise `'ltr'`.
+     */
+    direction?: "ltr" | "rtl";
+    /**
+     * Controls the color palette of the calendar.
+     * - `'auto'` (default): follows the OS `prefers-color-scheme` preference and updates live
+     *   when the user toggles their OS theme.
+     * - `'light'` / `'dark'`: forces the palette regardless of OS preference.
+     *
+     * The resolved scheme is applied as `data-color-scheme="light"|"dark"` on the calendar root,
+     * which switches the CSS custom-property palette via attribute-selector overrides in
+     * `src/styles/variables.css`. The `theme` prop (per-event inline color overrides) still wins.
+     */
+    colorScheme?: ColorScheme;
+    /** Overrides for built-in UI strings (navigation buttons, view names, etc.). */
+    localeMessages?: {
+        today?: string;
+        day?: string;
+        week?: string;
+        month?: string;
+        schedule?: string;
+        /** Label suffix in the custom days dropdown (e.g. `'Days'` → "3 Days"). */
+        days?: string;
+    };
+}
+/**
+ * Internal props type used by all view components after defaults have been applied.
+ * Extends `CalendarProps` with a required subset of keys so views never need to null-check defaults.
+ */
+export interface CalendarContentProps extends RequiredSome<CalendarProps, "events" | "view" | "is12Hour" | "selectable" | "creatable" | "dayType" | "pastYearLength" | "futureYearLength" | "showCurrentTime" | "autoScrollToCurrentTime" | "minHour" | "maxHour" | "weekStartsOn" | "weekEndsOn" | "showAdjacentMonths" | "showWeekNumbers" | "resetDateOnViewChange" | "showAllDayRow" | "width" | "height" | "theme" | "classNames" | "eventOverlapOffset" | "enableEnrichedEvents" | "eventsAreSorted" | "isEventOrderingEnabled" | "sortedMonthView" | "testId" | "locale" | "localeMessages"> {
+}
+/**
+ * A month entry used in the month picker dropdown.
+ */
+export interface MonthListType {
+    /** Localized month name (e.g. "January"). */
+    label: string;
+    /** 1-based month number (1 = January … 12 = December). */
+    value: number;
+}

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

@@ -0,0 +1,34 @@
+import { CSSProperties } from 'react';
+/**
+ * Represents a single calendar event.
+ */
+export interface CalendarEvent {
+    /** Unique identifier for the event. Used for deduplication and React keying. */
+    id?: string;
+    /** ISO 8601 start date. Use `YYYY-MM-DD` for all-day events, `YYYY-MM-DDTHH:mm:ss` for timed events. */
+    startDate: string;
+    /**
+     * ISO 8601 end date. Omit for single-day events; set to a later date for multi-day
+     * spanning events. If set to a date before `startDate`, the event is silently filtered
+     * by `useEvents` (negative-duration guard, C-TC3).
+     */
+    endDate?: string;
+    /** Display title shown on the event chip. */
+    title: string;
+    /** Inline styles applied directly to the event element. */
+    style?: CSSProperties;
+    /** Allows arbitrary custom fields to be attached and accessed in custom renderers. */
+    [key: string]: unknown;
+}
+/**
+ * Internal enriched event type used by layout algorithms.
+ * Extends `CalendarEvent` with week-boundary clipping fields, or marks the slot as a spacer
+ * to preserve grid positions when events overflow the visible row limit.
+ */
+export type EventListType = (CalendarEvent & {
+    startDateWeek: string;
+    endDateWeek?: string;
+    isSpacer?: false;
+}) | (CalendarEvent & {
+    isSpacer: true;
+});

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

@@ -0,0 +1,3 @@
+export * from './events';
+export * from './calendar';
+export * from './theme';