@loke/design-system/dist/components/calendar/calendar.d.ts

A design system with individually importable components

import { type RefObject } from "react";
type DateRange = {
    /**
     * The start date of the selected range.
     * Always required when using date range selection.
     */
    from: Date;
    /**
     * The end date of the selected range.
     * Optional - if not provided, the range is considered incomplete,
     * with only the start date selected.
     */
    to?: Date;
};
type CaptionProps = {
    /**
     * The date representing the month being displayed.
     * Typically the first day of the month.
     */
    date: Date;
    /**
     * Callback function triggered when the user navigates to a different month
     * using the previous or next buttons.
     */
    onMonthChange: (month: Date) => void;
    /**
     * Accessibility label for the next month navigation button.
     * Used for screen readers and tooltips.
     */
    nextLabel?: string;
    /**
     * Accessibility label for the previous month navigation button.
     * Used for screen readers and tooltips.
     */
    prevLabel?: string;
    /**
     * Whether the next month navigation button should be disabled.
     * Typically true when:
     * - There are multiple months displayed and this isn't the last one
     * - The current month is at the maximum allowed date limit
     */
    nextDisabled?: boolean;
    /**
     * Whether the previous month navigation button should be disabled.
     * Typically true when:
     * - The current month is at the minimum allowed date limit
     */
    prevDisabled?: boolean;
    /**
     * Whether the next month navigation button should be hidden.
     * Typically true when:
     * - There are multiple months displayed and this isn't the last one
     */
    nextHidden?: boolean;
    /**
     * Whether the previous month navigation button should be disabled.
     * Typically true when:
     * - There are multiple months displayed and this isn't the first one
     */
    prevHidden?: boolean;
    /**
     * Whether to show the ability to select a year.
     */
    showYearSelector?: boolean;
};
type YearSelectorProps = {
    /**
     * The date representing the currently displayed month/year.
     * Used to determine which year should be highlighted as selected.
     */
    date: Date;
    /**
     * Callback function triggered when a year is selected from the dropdown.
     * Receives the selected year as a number parameter.
     */
    onYearChange: (year: number) => void;
};
type WeekdayProps = {
    /**
     * The numeric day of the week (0-6), where:
     * 0 = Sunday, 1 = Monday, 2 = Tuesday, etc.
     */
    weekday: number;
    /**
     * Function to format the weekday name for display.
     * Default implementation returns a narrow weekday name based on locale.
     */
    format?: (date: Date) => string;
};
type DayProps = {
    /**
     * The date represented by this specific day cell.
     */
    date: Date;
    /**
     * The month currently being displayed in the calendar.
     * Used to determine if this day is part of the current month or an outside day.
     */
    displayMonth: Date;
    /**
     * Callback function triggered when the day is clicked.
     * Not called if the day is disabled or hidden.
     */
    onClick?: (date: Date) => void;
    /**
     * Whether this day is currently selected.
     * The visual appearance will change based on this state.
     */
    selected?: boolean;
    /**
     * Whether this day is disabled and cannot be selected.
     * Disabled days remain visible but cannot be interacted with.
     */
    disabled?: boolean;
    /**
     * Whether this day should be hidden entirely.
     * Typically used for outside days when showOutsideDays is false.
     */
    hidden?: boolean;
    /**
     * Whether this day represents the current date.
     * Usually highlighted with a different style.
     */
    today?: boolean;
    /**
     * Whether this day belongs to a month other than the one being displayed.
     * These are days from the previous or next month that appear to complete weeks.
     */
    isOutside?: boolean;
    /**
     * Whether this day is the first day in a selected date range.
     * Only applicable when using range selection mode.
     */
    isRangeStart?: boolean;
    /**
     * Whether this day is within a selected date range, but not the start or end.
     * Only applicable when using range selection mode.
     */
    isRangeMiddle?: boolean;
    /**
     * Whether this day is the last day in a selected date range.
     * Only applicable when using range selection mode.
     */
    isRangeEnd?: boolean;
    /**
     * Custom modifiers applied to this specific day.
     * Each key is a modifier name, and the boolean value indicates if it's active.
     */
    modifiers?: Record<string, boolean>;
    /**
     * CSS class names to apply for each active modifier.
     * Maps modifier names to CSS class names.
     */
    modifiersClassNames?: Record<string, string>;
    /**
     * Ref to be attached to the day button element.
     * Used for programmatic focus control.
     */
    dayRef?: RefObject<HTMLButtonElement | null>;
};
type CalendarBaseProps = {
    /**
     * The earliest date that can be selected in the calendar.
     * Dates before this will be automatically disabled.
     */
    minDate?: Date;
    /**
     * The latest date that can be selected in the calendar.
     * Dates after this will be automatically disabled.
     */
    maxDate?: Date;
    /**
     * The number of consecutive months to display in the calendar view.
     * Useful for date range selection or for providing a broader view.
     * Default is 1.
     */
    numberOfMonths?: number;
    /**
     * The initial month to display when the calendar first renders.
     * Only used when the calendar is uncontrolled (no 'month' prop).
     * Default is the current month.
     */
    defaultMonth?: Date;
    /**
     * The currently displayed month in controlled mode.
     * When provided, the calendar will not manage its own month state.
     */
    month?: Date;
    /**
     * Callback function triggered when the displayed month changes,
     * either through navigation buttons or when a date from another month is selected.
     */
    onMonthChange?: (month: Date) => void;
    /**
     * Custom formatting functions for textual elements in the calendar.
     * Override the default formatters to support localization or custom display formats.
     */
    formatters?: {
        formatWeekdayName?: (date: Date) => string;
        formatMonthCaption?: (date: Date) => string;
    };
    /**
     * Specify dates that should be disabled in the calendar.
     * Can be either:
     * - An array of specific dates to disable
     * - A function that returns true for dates that should be disabled
     */
    disabled?: Date[] | ((date: Date) => boolean);
    /**
     * Custom CSS class names to override the default styling.
     * Allows for targeted styling of different calendar elements.
     */
    classNames?: {
        root?: string;
        month?: string;
        caption?: string;
        weekday?: string;
        day?: string;
        selected?: string;
        disabled?: string;
        today?: string;
        range?: string;
        rangeStart?: string;
        rangeMiddle?: string;
        rangeEnd?: string;
    };
    /**
     * Whether to display the week number at the beginning of each week row.
     * Week numbers are calculated based on ISO 8601 standard.
     */
    showWeekNumber?: boolean;
    /**
     * Defines which day is considered the first day of the week.
     * 0 = Sunday, 1 = Monday, and so on.
     */
    firstDayOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
    /**
     * Whether to display days from the previous and next months
     * to fill out complete weeks in the calendar view.
     * When false, days outside the current month will be hidden.
     */
    showOutsideDays?: boolean;
    /**
     * Whether to always show 6 weeks in the calendar, regardless of the current month.
     * When true, creates a consistent calendar height across months.
     * When false, the calendar shrinks or grows based on how many weeks are needed.
     */
    fixedWeeks?: boolean;
    /**
     * Custom modifiers to apply to specific days, which can be used for styling or behavior.
     * Each key represents a modifier name, and the value can be:
     * - An array of specific dates to apply the modifier to
     * - A function that returns true for dates that should have the modifier applied
     */
    modifiers?: Record<string, Date[] | ((date: Date) => boolean)>;
    /**
     * CSS class names to apply to days that match the corresponding modifiers.
     * The keys should match those defined in the modifiers prop.
     */
    modifiersClassNames?: Record<string, string>;
    /**
     * Additional CSS class name to apply to the root calendar element.
     * Allows for custom styling when used within different contexts.
     */
    className?: string;
    /**
     * When true, the calendar will focus the first selected day (if selected)
     * or today's date (if not disabled) when the component mounts.
     * Improves accessibility after user actions like opening a date picker.
     */
    initialFocus?: boolean;
    /**
     * Props to pass to the underlying Caption component.
     * Allows customization of the calendar's appearance and behavior.
     */
    captionProps?: Omit<CaptionProps, "date" | "onMonthChange" | "nextDisabled" | "nextHidden" | "prevDisabled" | "prevHidden">;
};
type CalendarSingleProps = CalendarBaseProps & {
    /**
     * The selection mode for the calendar:
     * - 'single': Select a single date
     * - 'multiple': Select multiple individual dates
     * - 'range': Select a continuous range of dates
     */
    mode?: "single";
    /**
     * The selected date(s), which can be:
     * - A single Date object when mode is 'single'
     * - An array of Date objects when mode is 'multiple'
     * - A DateRange object containing 'from' and optional 'to' dates when mode is 'range'
     */
    selected?: Date;
    /**
     * Callback function triggered when a date is selected or deselected.
     * The argument passed will match the format specified by the current mode:
     * - Single Date object in 'single' mode
     * - Array of Date objects in 'multiple' mode
     * - DateRange object in 'range' mode
     */
    onSelect?: (date?: Date) => void;
};
type CalendarMultipleProps = CalendarBaseProps & {
    /**
     * The selection mode for the calendar:
     * - 'single': Select a single date
     * - 'multiple': Select multiple individual dates
     * - 'range': Select a continuous range of dates
     */
    mode: "multiple";
    /**
     * The selected date(s), which can be:
     * - A single Date object when mode is 'single'
     * - An array of Date objects when mode is 'multiple'
     * - A DateRange object containing 'from' and optional 'to' dates when mode is 'range'
     */
    selected?: Date[];
    /**
     * Callback function triggered when a date is selected or deselected.
     * The argument passed will match the format specified by the current mode:
     * - Single Date object in 'single' mode
     * - Array of Date objects in 'multiple' mode
     * - DateRange object in 'range' mode
     */
    onSelect?: (date: Date[]) => void;
};
type CalendarRangeProps = CalendarBaseProps & {
    /**
     * The selection mode for the calendar:
     * - 'single': Select a single date
     * - 'multiple': Select multiple individual dates
     * - 'range': Select a continuous range of dates
     */
    mode: "range";
    /**
     * The selected date(s), which can be:
     * - A single Date object when mode is 'single'
     * - An array of Date objects when mode is 'multiple'
     * - A DateRange object containing 'from' and optional 'to' dates when mode is 'range'
     */
    selected?: DateRange;
    /**
     * Callback function triggered when a date is selected or deselected.
     * The argument passed will match the format specified by the current mode:
     * - Single Date object in 'single' mode
     * - Array of Date objects in 'multiple' mode
     * - DateRange object in 'range' mode
     */
    onSelect?: (date?: DateRange) => void;
};
type CalendarProps = CalendarSingleProps | CalendarMultipleProps | CalendarRangeProps;
type DatePickerProps = {
    /**
     * The currently selected date or date range.
     * - Use a Date object for single date selection
     * - Use a DateRange object for range selection
     */
    value?: Date | DateRange;
    /**
     * Callback function triggered when the selected date changes.
     * The argument will be the newly selected date or date range.
     */
    onChange?: (date?: Date | DateRange) => void;
    /**
     * Whether the entire date picker is disabled.
     * When true, the date picker becomes non-interactive.
     */
    disabled?: boolean;
    /**
     * Props to pass to the underlying Calendar component.
     * Allows customization of the calendar's appearance and behavior.
     * The 'selected' and 'onSelect' props are managed by the DatePicker.
     */
    calendarProps?: Omit<CalendarProps, "selected" | "onSelect">;
    /**
     * Additional CSS class name to apply to the root date picker element.
     * Allows for custom styling when used within different contexts.
     */
    className?: string;
};
/**
 * Generates a matrix of dates representing all weeks in a month.
 * Each inner array represents one week, containing 7 Date objects.
 */
export declare function getWeeksInMonth(date: Date, firstDayOfWeek?: number, fixedWeeks?: boolean): Date[][];
/**
 * Calendar component for displaying and selecting dates.
 *
 * Features:
 * - Support for single date, multiple date, or date range selection
 * - Month navigation with optional constraints (min/max dates)
 * - Custom day rendering and styling
 * - Weekday and week number display options
 * - Customizable first day of week
 * - Support for disabled dates
 * - Outside days display control
 * - Initial focus on selected date or today's date for improved accessibility
 *
 * The component can be controlled (using the month prop) or uncontrolled (using defaultMonth).
 */
declare const Calendar: import("react").ForwardRefExoticComponent<CalendarProps & import("react").RefAttributes<HTMLDivElement>>;
export { Calendar };
export type { CalendarProps, CalendarSingleProps, CalendarMultipleProps, CalendarRangeProps, CaptionProps, DatePickerProps, DateRange, DayProps, WeekdayProps, YearSelectorProps, };