@flikk/ui 1.0.0-beta.1

package/dist/components/core/Calendar/Calendar.js

@@ -0,0 +1,382 @@
+import { jsxs, jsx } from 'react/jsx-runtime';
+import React__default, { useState, useEffect, useMemo, useCallback } from 'react';
+import { useReducedMotion, motion } from 'motion/react';
+import { ChevronLeftIcon, ChevronRightIcon } from '@heroicons/react/24/outline';
+import { calendarTheme } from './Calendar.theme.js';
+import { calendarAnimations } from './Calendar.animations.js';
+import { cn } from '../../../utils/cn.js';
+import { Select } from '../../forms/Select/Select.js';
+import '../../forms/Select/Select.theme.js';
+import { getMonthName, isDateDisabled as isDateDisabled$1, isSameDay } from './calendar.utils.js';
+import { Button } from '../Button/Button.js';
+
+/**
+ * Constants for date utilities
+ */
+const DEFAULT_MONTHS = [
+    "January",
+    "February",
+    "March",
+    "April",
+    "May",
+    "June",
+    "July",
+    "August",
+    "September",
+    "October",
+    "November",
+    "December",
+];
+const ABBREVIATED_MONTHS = [
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+];
+/**
+ * Date range utility (specific to Calendar component)
+ */
+const isDateInRange = (date, start, end) => {
+    if (!start || !end)
+        return false;
+    const dateTime = date.getTime();
+    const startTime = start.getTime();
+    const endTime = end.getTime();
+    return dateTime > startTime && dateTime < endTime;
+};
+/**
+ * Wrapper for isDateDisabled to support custom disabled function
+ */
+const isDateDisabled = (date, minDate, maxDate, customDisabled) => {
+    // Use shared utility for min/max dates
+    if (isDateDisabled$1(date, minDate, maxDate))
+        return true;
+    // Add custom disabled function check
+    if (customDisabled && customDisabled(date))
+        return true;
+    return false;
+};
+/**
+ * Generate calendar days for a given month and year with range support
+ */
+const generateCalendarDays = (year, month, selectedValue, mode = 'single', today, minDate, maxDate, customDisabled) => {
+    const firstDayOfMonth = new Date(year, month, 1);
+    const lastDayOfMonth = new Date(year, month + 1, 0);
+    const startDate = new Date(firstDayOfMonth);
+    // Adjust to start from Monday (1) instead of Sunday (0)
+    const dayOfWeek = (firstDayOfMonth.getDay() + 6) % 7;
+    startDate.setDate(startDate.getDate() - dayOfWeek);
+    const days = [];
+    const currentDate = new Date(startDate);
+    // Calculate minimum weeks needed to show all days of the month
+    const endDate = new Date(lastDayOfMonth);
+    const endDayOfWeek = (endDate.getDay() + 6) % 7;
+    const daysAfterMonth = 6 - endDayOfWeek;
+    const totalDays = dayOfWeek + lastDayOfMonth.getDate() + daysAfterMonth;
+    const weeksNeeded = Math.ceil(totalDays / 7);
+    const daysToGenerate = weeksNeeded * 7;
+    // Determine selected date(s) based on mode
+    const selectedDate = mode === 'single' && selectedValue instanceof Date ? selectedValue : undefined;
+    const rangeStart = mode === 'range' && selectedValue && typeof selectedValue === 'object' && 'start' in selectedValue ? selectedValue.start : null;
+    const rangeEnd = mode === 'range' && selectedValue && typeof selectedValue === 'object' && 'end' in selectedValue ? selectedValue.end : null;
+    // Generate only the needed number of days to fill complete weeks
+    for (let i = 0; i < daysToGenerate; i++) {
+        const date = new Date(currentDate);
+        const isCurrentMonth = date.getMonth() === month;
+        const isToday = today ? isSameDay(date, today) : false;
+        const isSelected = mode === 'single' && selectedDate ? isSameDay(date, selectedDate) : false;
+        const disabled = isDateDisabled(date, minDate, maxDate, customDisabled);
+        // Range-specific properties
+        const isRangeStart = mode === 'range' && rangeStart ? isSameDay(date, rangeStart) : false;
+        const isRangeEnd = mode === 'range' && rangeEnd ? isSameDay(date, rangeEnd) : false;
+        const isInRange = mode === 'range' ? isDateInRange(date, rangeStart, rangeEnd) : false;
+        days.push({
+            date,
+            isCurrentMonth,
+            isToday,
+            isSelected,
+            isRangeStart,
+            isRangeEnd,
+            isInRange,
+            isDisabled: disabled,
+        });
+        currentDate.setDate(currentDate.getDate() + 1);
+    }
+    return days;
+};
+const Calendar = React__default.forwardRef(({ mode = 'single', value, defaultValue, onChange, minDate, maxDate, isDateDisabled: customIsDateDisabled, showToday = true, selectTodayByDefault = false, weekdays = ["M", "T", "W", "T", "F", "S", "S"], months, size = "md", headerMode, enableMonthDropdown = true, enableYearDropdown = true, yearRange, viewDate: externalViewDate, onViewDateChange, onNavigatePrev, onNavigateNext, className, ...props }, ref) => {
+    // Determine initial view date from value/defaultValue
+    const getInitialViewDate = () => {
+        if (value) {
+            if (value instanceof Date)
+                return value;
+            if (value.start)
+                return value.start;
+        }
+        if (defaultValue) {
+            if (defaultValue instanceof Date)
+                return defaultValue;
+            if (defaultValue.start)
+                return defaultValue.start;
+        }
+        return new Date();
+    };
+    // Internal state for current view (month/year) - use external if provided
+    const [internalViewDate, setInternalViewDate] = useState(getInitialViewDate);
+    const viewDate = externalViewDate || internalViewDate;
+    // Internal state for selected value (uncontrolled mode)
+    const [internalValue, setInternalValue] = useState(() => {
+        if (defaultValue)
+            return defaultValue;
+        if (selectTodayByDefault && !value && mode === 'single') {
+            const today = new Date();
+            if (!isDateDisabled(today, minDate, maxDate, customIsDateDisabled)) {
+                return today;
+            }
+        }
+        return undefined;
+    });
+    // Track range selection state (for range mode)
+    const [rangeSelectionState, setRangeSelectionState] = useState('start');
+    // Determine the selected value (controlled vs uncontrolled)
+    const selectedValue = value !== undefined ? value : internalValue;
+    // Keep range selection state in sync with current selection to avoid misinterpreting clicks
+    useEffect(() => {
+        if (mode !== 'range')
+            return;
+        const currentRange = selectedValue && typeof selectedValue === 'object' && 'start' in selectedValue
+            ? selectedValue
+            : { start: null, end: null };
+        if (currentRange.start && !currentRange.end) {
+            setRangeSelectionState('end');
+        }
+        else {
+            setRangeSelectionState('start');
+        }
+    }, [mode, selectedValue]);
+    // Current month and year being displayed
+    const currentYear = viewDate.getFullYear();
+    const currentMonth = viewDate.getMonth();
+    // Reduced motion support
+    const shouldReduceMotion = useReducedMotion();
+    // Resolve header display mode with backward compatibility
+    const resolvedHeaderMode = useMemo(() => {
+        // If headerMode is explicitly set, use it
+        if (headerMode)
+            return headerMode;
+        // Backward compatibility: infer from enableMonthDropdown and enableYearDropdown
+        if (!enableMonthDropdown && !enableYearDropdown)
+            return 'static';
+        if (enableMonthDropdown && enableYearDropdown)
+            return 'dropdown';
+        return 'mixed';
+    }, [headerMode, enableMonthDropdown, enableYearDropdown]);
+    // Navigation boundary detection - disable arrows when at min/max limits
+    const canNavigateToPrev = useMemo(() => {
+        if (!minDate)
+            return true;
+        const prevMonth = new Date(currentYear, currentMonth - 1, 1);
+        const minMonth = new Date(minDate.getFullYear(), minDate.getMonth(), 1);
+        return prevMonth >= minMonth;
+    }, [minDate, currentYear, currentMonth]);
+    const canNavigateToNext = useMemo(() => {
+        if (!maxDate)
+            return true;
+        const nextMonth = new Date(currentYear, currentMonth + 1, 1);
+        const maxMonth = new Date(maxDate.getFullYear(), maxDate.getMonth(), 1);
+        return nextMonth <= maxMonth;
+    }, [maxDate, currentYear, currentMonth]);
+    // Generate month options - filter based on minDate/maxDate
+    const monthNames = months || DEFAULT_MONTHS;
+    const monthOptions = useMemo(() => {
+        return monthNames
+            .map((monthName, index) => ({
+            id: index,
+            value: index.toString(),
+            label: monthName,
+        }))
+            .filter((option) => {
+            const monthIndex = parseInt(option.value, 10);
+            // Filter out months outside min/max range for the current year
+            if (minDate && currentYear === minDate.getFullYear()) {
+                const minMonth = minDate.getMonth();
+                if (monthIndex < minMonth) {
+                    return false;
+                }
+            }
+            if (maxDate && currentYear === maxDate.getFullYear()) {
+                const maxMonth = maxDate.getMonth();
+                if (monthIndex > maxMonth) {
+                    return false;
+                }
+            }
+            return true;
+        });
+    }, [monthNames, currentYear, minDate, maxDate]);
+    // Generate year options - filter based on minDate/maxDate
+    const currentDate = new Date();
+    const defaultYearRange = {
+        start: currentDate.getFullYear() - 50,
+        end: currentDate.getFullYear() + 50,
+    };
+    const actualYearRange = yearRange || defaultYearRange;
+    const yearOptions = useMemo(() => {
+        // Determine year range based on minDate/maxDate if provided
+        let startYear = actualYearRange.start;
+        let endYear = actualYearRange.end;
+        if (minDate) {
+            startYear = Math.max(startYear, minDate.getFullYear());
+        }
+        if (maxDate) {
+            endYear = Math.min(endYear, maxDate.getFullYear());
+        }
+        const options = [];
+        for (let year = startYear; year <= endYear; year++) {
+            options.push({
+                id: year,
+                value: year.toString(),
+                label: year.toString(),
+            });
+        }
+        return options;
+    }, [actualYearRange, minDate, maxDate]);
+    // Current abbreviated month for display
+    const currentAbbreviatedMonth = ABBREVIATED_MONTHS[currentMonth];
+    // Dropdown change handlers
+    const handleMonthChange = useCallback((monthValue) => {
+        const newMonth = parseInt(monthValue, 10);
+        const newDate = new Date(currentYear, newMonth, 1);
+        if (onViewDateChange) {
+            onViewDateChange(newDate);
+        }
+        else {
+            setInternalViewDate(newDate);
+        }
+    }, [currentYear, onViewDateChange]);
+    const handleYearChange = useCallback((yearValue) => {
+        const newYear = parseInt(yearValue, 10);
+        const newDate = new Date(newYear, currentMonth, 1);
+        if (onViewDateChange) {
+            onViewDateChange(newDate);
+        }
+        else {
+            setInternalViewDate(newDate);
+        }
+    }, [currentMonth, onViewDateChange]);
+    // Generate calendar days
+    const calendarDays = useMemo(() => generateCalendarDays(currentYear, currentMonth, selectedValue, mode, showToday ? new Date() : null, minDate, maxDate, customIsDateDisabled), [
+        currentYear,
+        currentMonth,
+        selectedValue,
+        mode,
+        showToday,
+        minDate,
+        maxDate,
+        customIsDateDisabled,
+    ]);
+    // Navigation handlers
+    const navigateToPreviousMonth = useCallback(() => {
+        if (onNavigatePrev === null)
+            return;
+        if (onNavigatePrev) {
+            onNavigatePrev();
+        }
+        else {
+            const newDate = new Date(viewDate.getFullYear(), viewDate.getMonth() - 1, 1);
+            if (onViewDateChange) {
+                onViewDateChange(newDate);
+            }
+            else {
+                setInternalViewDate(newDate);
+            }
+        }
+    }, [onNavigatePrev, viewDate, onViewDateChange]);
+    const navigateToNextMonth = useCallback(() => {
+        if (onNavigateNext === null)
+            return;
+        if (onNavigateNext) {
+            onNavigateNext();
+        }
+        else {
+            const newDate = new Date(viewDate.getFullYear(), viewDate.getMonth() + 1, 1);
+            if (onViewDateChange) {
+                onViewDateChange(newDate);
+            }
+            else {
+                setInternalViewDate(newDate);
+            }
+        }
+    }, [onNavigateNext, viewDate, onViewDateChange]);
+    // Date selection handler
+    const handleDateSelect = useCallback((date) => {
+        if (isDateDisabled(date, minDate, maxDate, customIsDateDisabled)) {
+            return;
+        }
+        // Auto-navigate to the selected date's month if it's different from current view
+        if (date.getMonth() !== currentMonth ||
+            date.getFullYear() !== currentYear) {
+            const newDate = new Date(date.getFullYear(), date.getMonth(), 1);
+            if (onViewDateChange) {
+                onViewDateChange(newDate);
+            }
+            else {
+                setInternalViewDate(newDate);
+            }
+        }
+        if (mode === 'single') {
+            // Single date selection
+            const newValue = date;
+            // Update internal state if uncontrolled
+            if (value === undefined) {
+                setInternalValue(newValue);
+            }
+            // Call onChange callback
+            onChange === null || onChange === void 0 ? void 0 : onChange(newValue);
+        }
+        else {
+            // Range selection
+            const currentRange = selectedValue && typeof selectedValue === 'object' && 'start' in selectedValue
+                ? selectedValue
+                : { start: null, end: null };
+            if (rangeSelectionState === 'start' || (currentRange.start && currentRange.end)) {
+                // Starting a new range selection
+                const newRange = { start: date, end: null };
+                if (value === undefined) {
+                    setInternalValue(newRange);
+                }
+                setRangeSelectionState('end');
+                onChange === null || onChange === void 0 ? void 0 : onChange(newRange);
+            }
+            else {
+                // Completing the range
+                const start = currentRange.start;
+                const end = date;
+                // Ensure start is before end
+                const newRange = start <= end
+                    ? { start, end }
+                    : { start: end, end: start };
+                if (value === undefined) {
+                    setInternalValue(newRange);
+                }
+                setRangeSelectionState('start');
+                onChange === null || onChange === void 0 ? void 0 : onChange(newRange);
+            }
+        }
+    }, [minDate, maxDate, customIsDateDisabled, currentMonth, currentYear, onViewDateChange, mode, value, onChange, selectedValue, rangeSelectionState]);
+    return (jsxs("div", { ref: ref, className: cn(calendarTheme.baseStyle, className), ...props, children: [jsxs("div", { className: calendarTheme.headerStyle, children: [onNavigatePrev !== null && (jsx(Button, { onClick: navigateToPreviousMonth, "aria-label": "Previous month", disabled: !canNavigateToPrev, iconOnly: true, variant: "link", color: "neutral", size: "sm", children: jsx(ChevronLeftIcon, { className: "size-4", strokeWidth: 2 }) })), onNavigatePrev === null && jsx("div", { className: "w-8" }), resolvedHeaderMode === 'static' ? (jsxs("h2", { className: calendarTheme.titleStyle, children: [getMonthName(viewDate, months), " ", currentYear] })) : (jsxs("div", { className: calendarTheme.headerDropdownsStyle, children: [(resolvedHeaderMode === 'dropdown' || (resolvedHeaderMode === 'mixed' && enableMonthDropdown)) && (jsx(Select, { value: currentMonth.toString(), onChange: handleMonthChange, options: monthOptions, displayValue: currentAbbreviatedMonth, size: "sm", className: "text-sm font-medium" })), (resolvedHeaderMode === 'dropdown' || (resolvedHeaderMode === 'mixed' && enableYearDropdown)) && (jsx(Select, { value: currentYear.toString(), onChange: handleYearChange, options: yearOptions, size: "sm", className: "text-sm font-medium" }))] })), onNavigateNext !== null && (jsx(Button, { onClick: navigateToNextMonth, "aria-label": "Next month", disabled: !canNavigateToNext, iconOnly: true, variant: "link", color: "neutral", size: "sm", children: jsx(ChevronRightIcon, { className: "size-4", strokeWidth: 2 }) })), onNavigateNext === null && jsx("div", { className: "w-8" })] }), jsx("div", { className: calendarTheme.weekdaysStyle, children: weekdays.map((day, index) => (jsx("div", { className: calendarTheme.weekdayStyle, children: day }, index))) }), jsx("div", { className: calendarTheme.daysGridStyle, children: calendarDays.map((day) => {
+                    var _a;
+                    const dayNumber = day.date.getDate();
+                    return (jsxs(motion.button, { type: "button", onClick: () => handleDateSelect(day.date), disabled: day.isDisabled, className: cn(calendarTheme.dayButtonStyle, (_a = calendarTheme.dayButtonSizes) === null || _a === void 0 ? void 0 : _a[size]), "data-selected": day.isSelected, "data-range-start": day.isRangeStart, "data-range-end": day.isRangeEnd, "data-in-range": day.isInRange, "data-today": day.isToday && !day.isSelected && !day.isRangeStart && !day.isRangeEnd, "data-disabled": day.isDisabled, "data-other-month": !day.isCurrentMonth, "aria-label": `Select ${day.date.toLocaleDateString()}`, variants: shouldReduceMotion ? {} : calendarAnimations.dayButton, whileHover: shouldReduceMotion ? undefined : (!day.isDisabled ? "hover" : undefined), whileTap: shouldReduceMotion ? undefined : (!day.isDisabled ? "tap" : undefined), children: [jsx("time", { dateTime: day.date.toISOString().split("T")[0], children: dayNumber }), day.isToday && (jsx(motion.span, { className: "absolute z-10 bottom-1 left-1/2 -translate-x-1/2 w-1 h-1 bg-[var(--color-primary)] rounded-full", variants: shouldReduceMotion ? {} : calendarAnimations.todayDot, initial: shouldReduceMotion ? undefined : "initial", animate: shouldReduceMotion ? undefined : "animate" }))] }, day.date.toISOString()));
+                }) })] }));
+});
+Calendar.displayName = "Calendar";
+
+export { Calendar };

package/dist/components/core/Calendar/Calendar.theme.d.ts

@@ -0,0 +1,6 @@
+import { CalendarTheme } from "./Calendar.types";
+/**
+ * Calendar component theme following flat structure pattern
+ * Uses design tokens and data-[state=*] selectors
+ */
+export declare const calendarTheme: CalendarTheme;

package/dist/components/core/Calendar/Calendar.theme.js

@@ -0,0 +1,54 @@
+/**
+ * Calendar component theme following flat structure pattern
+ * Uses design tokens and data-[state=*] selectors
+ */
+const calendarTheme = {
+    baseStyle: "select-none w-full max-w-fit bg-white dark:bg-[var(--color-neutral-900)]",
+    headerStyle: "flex items-center justify-between mb-4",
+    titleStyle: "text-base font-semibold text-[var(--color-text-primary)] cursor-pointer hover:text-[var(--color-primary)] transition-colors " +
+        "dark:text-[var(--color-neutral-200)] dark:hover:text-[var(--color-primary-400)]",
+    headerDropdownsStyle: "grid grid-cols-2 items-center gap-2 flex-1 justify-center mx-3",
+    navButtonStyle: "inline-flex items-center justify-center size-8 rounded-[calc(var(--radius-base)*0.75)] border-0 bg-transparent " +
+        "text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-primary-50)] " +
+        "focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] focus-visible:ring-offset-2 " +
+        "transition-colors disabled:opacity-50 disabled:cursor-not-allowed " +
+        // Dark mode
+        "dark:text-[var(--color-neutral-500)] dark:hover:text-[var(--color-neutral-200)] dark:hover:bg-[var(--color-neutral-800)] " +
+        "dark:focus-visible:ring-offset-[var(--color-neutral-900)]",
+    weekdaysStyle: "grid grid-cols-7 mb-2",
+    weekdayStyle: "flex items-center justify-center h-8 text-xs font-medium text-[var(--color-text-muted)] " +
+        "dark:text-[var(--color-neutral-500)]",
+    daysGridStyle: "grid grid-cols-7 gap-0.5",
+    dayButtonStyle: "relative flex items-center justify-center rounded-full border-0 bg-transparent font-medium cursor-pointer " +
+        "transition-all duration-200 focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] focus-visible:ring-offset-2 " +
+        // Base text color
+        "text-[var(--color-text-primary)] dark:text-[var(--color-neutral-200)] " +
+        // Hover state
+        "hover:bg-[var(--color-primary-50)] dark:hover:bg-[var(--color-neutral-800)] " +
+        // Selected state
+        "data-[selected=true]:bg-[var(--color-primary)] data-[selected=true]:text-white " +
+        "data-[selected=true]:hover:bg-[var(--color-primary-600)] data-[selected=true]:border-t data-[selected=true]:border-white/30 " +
+        // Today indicator
+        "data-[today=true]:text-[var(--color-primary)] dark:data-[today=true]:text-[var(--color-primary-400)] " +
+        // Disabled state
+        "data-[disabled=true]:text-[var(--color-text-muted)] data-[disabled=true]:opacity-50 " +
+        "data-[disabled=true]:cursor-not-allowed data-[disabled=true]:hover:bg-transparent " +
+        "dark:data-[disabled=true]:text-[var(--color-neutral-600)] " +
+        // Other month state
+        "data-[other-month=true]:text-[var(--color-text-muted)] data-[other-month=true]:opacity-60 " +
+        "dark:data-[other-month=true]:text-[var(--color-neutral-600)] " +
+        // Range mode states
+        "data-[range-start=true]:bg-[var(--color-primary)] data-[range-start=true]:text-white " +
+        "data-[range-end=true]:bg-[var(--color-primary)] data-[range-end=true]:text-white " +
+        "data-[in-range=true]:bg-[var(--color-primary-50)]/70 data-[in-range=true]:text-[var(--color-text-primary)] " +
+        "dark:data-[in-range=true]:bg-[var(--color-primary-900)]/50 dark:data-[in-range=true]:text-[var(--color-neutral-200)] " +
+        // Focus offset for dark mode
+        "dark:focus-visible:ring-offset-[var(--color-neutral-900)]",
+    dayButtonSizes: {
+        sm: "size-8 text-sm",
+        md: "size-10 text-sm",
+        lg: "size-12 text-base",
+    },
+};
+
+export { calendarTheme };

package/dist/components/core/Calendar/Calendar.types.d.ts

@@ -0,0 +1,124 @@
+import React from 'react';
+/**
+ * Size variants for the Calendar component
+ */
+export type CalendarSize = 'sm' | 'md' | 'lg';
+/**
+ * Selection mode for Calendar
+ */
+export type CalendarMode = 'single' | 'range';
+/**
+ * Header display mode for Calendar
+ * - 'dropdown': Show month and year as dropdowns (interactive)
+ * - 'static': Show month and year as static text (e.g., "October 2025")
+ * - 'mixed': Use enableMonthDropdown and enableYearDropdown for custom control
+ */
+export type CalendarHeaderMode = 'dropdown' | 'static' | 'mixed';
+/**
+ * Date range type for range selection
+ */
+export interface DateRange {
+    start: Date | null;
+    end: Date | null;
+}
+/**
+ * Calendar component props
+ * @property {Date | DateRange} value - The selected date or range (controlled mode)
+ * @property {Date | DateRange} defaultValue - Default selected date or range (uncontrolled mode)
+ * @property {function} onChange - Callback when date/range is selected
+ * @property {CalendarMode} mode - Selection mode (single or range)
+ * @property {Date} minDate - Minimum selectable date
+ * @property {Date} maxDate - Maximum selectable date
+ * @property {function} isDateDisabled - Function to determine if a date should be disabled
+ * @property {boolean} showToday - Whether to highlight today's date
+ * @property {boolean} selectTodayByDefault - Auto-select today's date when no value is provided (default: false)
+ * @property {string[]} weekdays - Custom weekday labels
+ * @property {string[]} months - Custom month names
+ * @property {CalendarSize} size - Size variant
+ * @property {boolean} enableMonthDropdown - Whether to show month dropdown (default: true)
+ * @property {boolean} enableYearDropdown - Whether to show year dropdown (default: true)
+ * @property {object} yearRange - Range of years to show in dropdown
+ */
+export interface CalendarProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'> {
+    /** Selection mode - single date or date range */
+    mode?: CalendarMode;
+    /** The selected date or range (controlled mode) */
+    value?: Date | DateRange;
+    /** Default selected date or range (uncontrolled mode) */
+    defaultValue?: Date | DateRange;
+    /** Callback fired when a date or range is selected */
+    onChange?: (value: Date | DateRange) => void;
+    /** Minimum selectable date */
+    minDate?: Date;
+    /** Maximum selectable date */
+    maxDate?: Date;
+    /** Function to determine if a specific date should be disabled */
+    isDateDisabled?: (date: Date) => boolean;
+    /** Whether to highlight today's date (default: true) */
+    showToday?: boolean;
+    /** Auto-select today's date when calendar opens without a value (default: false) */
+    selectTodayByDefault?: boolean;
+    /** Custom weekday labels (default: ['M', 'T', 'W', 'T', 'F', 'S', 'S']) */
+    weekdays?: string[];
+    /** Custom month names */
+    months?: string[];
+    /** Size variant */
+    size?: CalendarSize;
+    /** Header display mode - dropdown (default), static text, or mixed (default: 'dropdown') */
+    headerMode?: CalendarHeaderMode;
+    /** Whether to enable month dropdown instead of navigation arrows (default: true) */
+    enableMonthDropdown?: boolean;
+    /** Whether to enable year dropdown instead of navigation arrows (default: true) */
+    enableYearDropdown?: boolean;
+    /** Year range for dropdown selection (default: ±50 years from current) */
+    yearRange?: {
+        start: number;
+        end: number;
+    };
+    /** External control of displayed month/year (for dual calendar mode) */
+    viewDate?: Date;
+    /** Callback when view date changes (from dropdowns or navigation) */
+    onViewDateChange?: (date: Date) => void;
+    /** Custom prev navigation handler (null to hide left arrow) */
+    onNavigatePrev?: (() => void) | null;
+    /** Custom next navigation handler (null to hide right arrow) */
+    onNavigateNext?: (() => void) | null;
+    /** Additional class name for the container */
+    className?: string;
+}
+/**
+ * Internal day object used by the Calendar
+ */
+export interface CalendarDay {
+    /** The date object */
+    date: Date;
+    /** Whether this day belongs to the current month */
+    isCurrentMonth: boolean;
+    /** Whether this day is today */
+    isToday: boolean;
+    /** Whether this day is selected */
+    isSelected: boolean;
+    /** Whether this day is the range start */
+    isRangeStart?: boolean;
+    /** Whether this day is the range end */
+    isRangeEnd?: boolean;
+    /** Whether this day is within a selected range */
+    isInRange?: boolean;
+    /** Whether this day is disabled */
+    isDisabled: boolean;
+}
+/**
+ * Theme interface for Calendar component (flat structure)
+ */
+export interface CalendarTheme {
+    baseStyle: string;
+    headerStyle: string;
+    titleStyle: string;
+    headerDropdownsStyle: string;
+    navButtonStyle: string;
+    weekdaysStyle: string;
+    weekdayStyle: string;
+    daysGridStyle: string;
+    dayButtonStyle: string;
+    dayButtonSizes?: Record<CalendarSize, string>;
+}

package/dist/components/core/Calendar/CalendarEvent/CalendarEvent.d.ts

@@ -0,0 +1,4 @@
+import React from 'react';
+import { CalendarEventProps } from './CalendarEvent.types';
+declare const CalendarEvent: React.ForwardRefExoticComponent<CalendarEventProps & React.RefAttributes<HTMLDivElement>>;
+export { CalendarEvent };

package/dist/components/core/Calendar/CalendarEvent/CalendarEvent.theme.d.ts

@@ -0,0 +1,12 @@
+export interface CalendarEventThemeOverrides {
+    monthly?: string;
+    weekly?: string;
+    daily?: {
+        container?: string;
+        accent?: string;
+        time?: string;
+        title?: string;
+        description?: string;
+    };
+}
+export declare const calendarEventTheme: CalendarEventThemeOverrides;

package/dist/components/core/Calendar/CalendarEvent/CalendarEvent.types.d.ts

@@ -0,0 +1,24 @@
+import { HTMLAttributes } from 'react';
+import { CalendarEventThemeOverrides } from './CalendarEvent.theme';
+import { CalendarEvent as CalendarEventType, GridConfig, EventPosition } from '../../../../utils';
+export type CalendarEventVariant = 'daily' | 'weekly' | 'monthly';
+export interface CalendarEventProps extends HTMLAttributes<HTMLDivElement> {
+    variant?: CalendarEventVariant;
+    event: CalendarEventType & {
+        description?: string;
+        attendees?: Array<{
+            name: string;
+            src: string;
+            alt: string;
+            showTooltip?: boolean;
+        }>;
+    };
+    gridConfig?: GridConfig;
+    position?: EventPosition;
+    containerWidth?: number;
+    cellHeight?: number;
+    gridInterval?: number;
+    startOffset?: number;
+    theme?: CalendarEventThemeOverrides;
+    onEventClick?: (eventData: CalendarEventProps['event']) => void;
+}

package/dist/components/core/Calendar/CalendarEvent/index.d.ts

@@ -0,0 +1,2 @@
+export { CalendarEvent } from './CalendarEvent';
+export type { CalendarEventProps } from './CalendarEvent.types';

package/dist/components/core/Calendar/CalendarMini/CalendarMini.animations.d.ts

@@ -0,0 +1,4 @@
+import { Variants } from 'motion/react';
+export declare const monthTransitionVariants: Variants;
+export declare const dateRowTransitionVariants: Variants;
+export declare const dateItemVariants: Variants;

package/dist/components/core/Calendar/CalendarMini/CalendarMini.animations.js

@@ -0,0 +1,27 @@
+const monthTransitionVariants = {
+    enter: (direction) => ({
+        x: direction > 0 ? 20 : -20,
+        opacity: 0,
+    }),
+    center: {
+        x: 0,
+        opacity: 1,
+    },
+    exit: (direction) => ({
+        x: direction < 0 ? 20 : -20,
+        opacity: 0,
+    }),
+};
+const dateRowTransitionVariants = {
+    enter: (direction) => ({
+        x: direction > 0 ? '100%' : '-100%',
+    }),
+    center: {
+        x: 0,
+    },
+    exit: (direction) => ({
+        x: direction < 0 ? '100%' : '-100%',
+    }),
+};
+
+export { dateRowTransitionVariants, monthTransitionVariants };

package/dist/components/core/Calendar/CalendarMini/CalendarMini.d.ts

@@ -0,0 +1,3 @@
+import React from "react";
+import { CalendarMiniProps } from "./CalendarMini.types";
+export declare const CalendarMini: React.ForwardRefExoticComponent<CalendarMiniProps & React.RefAttributes<HTMLDivElement>>;