@salt-ds/lab 1.0.0-alpha.7 → 1.0.0-alpha.70

package/dist-types/calendar/useCalendar.d.ts

@@ -1,60 +1,294 @@
-import { DateValue } from "@internationalized/date";
-import { SyntheticEvent } from "react";
-import { UseMultiSelectionCalendarProps, UseOffsetSelectionCalendarProps, UseRangeSelectionCalendarProps, UseSingleSelectionCalendarProps } from "./useSelection";
-export declare type UnselectableInfo = {
-    emphasis: "medium";
-    tooltip: string;
-} | {
-    emphasis: "low";
-    tooltip?: string;
-};
-interface BaseUseCalendarProps {
-    defaultVisibleMonth?: DateValue;
-    onVisibleMonthChange?: (event: SyntheticEvent, visibleMonth: DateValue) => void;
-    isDayUnselectable?: (date: DateValue) => UnselectableInfo | boolean | void;
-    visibleMonth?: DateValue;
+import { type ResponsiveProp } from "@salt-ds/core";
+import type { DateFrameworkType, Timezone } from "@salt-ds/date-adapters";
+import { type SyntheticEvent } from "react";
+import { type UseCalendarSelectionBaseProps, type UseCalendarSelectionMultiSelectProps, type UseCalendarSelectionOffsetProps, type UseCalendarSelectionRangeProps, type UseCalendarSelectionSingleProps } from "./useCalendarSelection";
+/**
+ * Base properties for the UseCalendar hook.
+ * @template TDate - The type of the date object.
+ */
+interface UseCalendarBaseProps<TDate> extends UseCalendarSelectionBaseProps<TDate> {
+    /**
+     * The default visible month.
+     */
+    defaultVisibleMonth?: TDate;
+    /**
+     * Callback fired when the visible month changes.
+     * @param event - The synthetic event or null if triggered by code.
+     * @param visibleMonth - The new visible month.
+     */
+    onVisibleMonthChange?: (event: SyntheticEvent | null, visibleMonth: TDate) => void;
+    /**
+     * Function to determine if a day is unselectable.
+     * @param date - The date to check.
+     * @returns A string reason if the day is unselectable, otherwise `false` or `undefined`.
+     */
+    isDayUnselectable?: (date: TDate) => string | false | undefined;
+    /**
+     * Function to determine if a day is highlighted.
+     * @param date - The date to check.
+     * @returns A string reason if the day is highlighted, otherwise `false` or `undefined`.
+     */
+    isDayHighlighted?: (date: TDate) => string | false | undefined;
+    /**
+     * Function to determine if a day is disabled.
+     * @param date - The date to check.
+     * @returns A string reason if the day is disabled, otherwise `false` or `undefined`.
+     */
+    isDayDisabled?: (date: TDate) => string | false | undefined;
+    /**
+     * If `true`, hides dates that are out of the selectable range.
+     */
     hideOutOfRangeDates?: boolean;
-    hideYearDropdown?: boolean;
-    minDate?: DateValue;
-    maxDate?: DateValue;
+    /**
+     * The minimum selectable date.
+     */
+    minDate?: TDate;
+    /**
+     * The maximum selectable date.
+     */
+    maxDate?: TDate;
+    /**
+     * Number of visible months, maximum 12, defaults to 1.
+     */
+    numberOfVisibleMonths?: ResponsiveProp<1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12>;
 }
-export declare type useCalendarProps = (Omit<UseSingleSelectionCalendarProps, "isDaySelectable"> | Omit<UseMultiSelectionCalendarProps, "isDaySelectable"> | Omit<UseRangeSelectionCalendarProps, "isDaySelectable"> | Omit<UseOffsetSelectionCalendarProps, "isDaySelectable">) & BaseUseCalendarProps;
-export declare function useCalendar(props: useCalendarProps): {
+/**
+ * UseCalendar hook props for a single date selection Calendar.
+ */
+export interface UseCalendarSingleProps<TDate extends DateFrameworkType> extends UseCalendarSelectionSingleProps<TDate>, UseCalendarBaseProps<TDate> {
+    /**
+     * The selection variant, set to "single".
+     */
+    selectionVariant: "single";
+}
+/**
+ * UseCalendar hook props for a date range selection Calendar.
+ * @template TDate - The type of the date object.
+ */
+export interface UseCalendarRangeProps<TDate extends DateFrameworkType> extends UseCalendarSelectionRangeProps<TDate>, UseCalendarBaseProps<TDate> {
+    /**
+     * The selection variant, set to "range".
+     */
+    selectionVariant: "range";
+}
+/**
+ * UseCalendar hook props for a multi-select Calendar.
+ * @template TDate - The type of the date object.
+ */
+export interface UseCalendarMultiSelectProps<TDate extends DateFrameworkType> extends UseCalendarSelectionMultiSelectProps<TDate>, UseCalendarBaseProps<TDate> {
+    /**
+     * The selection variant, set to "multiselect".
+     */
+    selectionVariant: "multiselect";
+}
+/**
+ * UseCalendar hook props for an offset date selection Calendar.
+ * @template TDate - The type of the date object.
+ */
+export interface UseCalendarOffsetProps<TDate extends DateFrameworkType> extends UseCalendarSelectionOffsetProps<TDate>, UseCalendarBaseProps<TDate> {
+    /**
+     * The selection variant, set to "offset".
+     */
+    selectionVariant: "offset";
+}
+/**
+ * UseCalendar hook props, wth the selection variant determining the return type of the date selection
+ * @template TDate - The type of the date object.
+ */
+export declare type UseCalendarProps<TDate extends DateFrameworkType> = UseCalendarSingleProps<TDate> | UseCalendarRangeProps<TDate> | UseCalendarMultiSelectProps<TDate> | UseCalendarOffsetProps<TDate>;
+/**
+ * Represents the return type of the useCalendar hook.
+ * @template TDate - The type of the date object.
+ */
+export interface UseCalendarReturn<TDate extends DateFrameworkType> {
+    /**
+     * The state of the calendar.
+     */
     state: {
-        selectedDate: import("@internationalized/date").CalendarDate | import("@internationalized/date").CalendarDateTime | import("@internationalized/date").ZonedDateTime | {
-            startDate?: DateValue | undefined;
-            endDate?: DateValue | undefined;
-        } | {
-            startDate?: DateValue | undefined;
-            endDate?: DateValue | undefined;
-        } | DateValue[] | null | undefined;
-        hoveredDate: import("@internationalized/date").CalendarDate | import("@internationalized/date").CalendarDateTime | import("@internationalized/date").ZonedDateTime | null | undefined;
-        visibleMonth: DateValue;
-        focusedDate: DateValue;
-        minDate: DateValue | undefined;
-        maxDate: DateValue | undefined;
-        selectionVariant: "offset" | "range" | "default" | "multiselect";
-        hideOutOfRangeDates: boolean | undefined;
-        calendarFocused: boolean;
+        /**
+         * The currently visible month in the calendar.
+         */
+        visibleMonth: TDate;
+        /**
+         * The currently focused date in the calendar, or null if no date is focused.
+         */
+        focusedDate: TDate | null;
+        /**
+         *  Focusable dates based on current state
+         */
+        focusableDates: TDate[];
+        /**
+         * The minimum selectable date in the calendar.
+         */
+        minDate: TDate;
+        /**
+         * The maximum selectable date in the calendar.
+         */
+        maxDate: TDate;
+        /**
+         * The selection variant of the calendar, indicating the type of selection allowed.
+         */
+        selectionVariant: "single" | "range" | "multiselect" | "offset";
+        /**
+         * Whether to hide dates that are out of the selectable range.
+         */
+        hideOutOfRangeDates?: boolean;
+        /**
+         * Number of visible months
+         */
+        numberOfVisibleMonths: number;
+        /**
+         * Specifies the timezone behavior:
+         * - If undefined, the timezone will be derived from the passed date, or from `defaultSelectedDate`/`selectedDate`.
+         * - If set to "default", the default timezone of the date library will be used.
+         * - If set to "system", the local system's timezone will be applied.
+         * - If set to "UTC", the time will be returned in UTC.
+         * - If set to a valid IANA timezone identifier, the time will be returned for that specific timezone.
+         */
+        timezone?: Timezone;
+        /**
+         * Additional state properties from selectionManager.state.
+         */
+        [key: string]: any;
     };
+    /**
+     * Helper functions for interacting with the calendar.
+     */
     helpers: {
-        setSelectedDate: (event: SyntheticEvent<HTMLButtonElement, Event>, newSelectedDate: DateValue) => void;
-        isSelected: (date: DateValue) => boolean;
-        setHoveredDate: (event: SyntheticEvent<Element, Event>, date: DateValue | null) => void;
-        isHovered: (date: DateValue) => boolean;
-        isSelectedSpan: (date: DateValue) => boolean;
-        isHoveredSpan: (date: DateValue) => boolean;
-        isSelectedStart: (date: DateValue) => boolean;
-        isSelectedEnd: (date: DateValue) => boolean;
-        isHoveredOffset: (date: DateValue) => boolean;
-        setVisibleMonth: (event: SyntheticEvent, newVisibleMonth: DateValue) => void;
-        setFocusedDate: (event: SyntheticEvent, date: DateValue) => void;
-        setCalendarFocused: import("react").Dispatch<import("react").SetStateAction<boolean>>;
-        isDayUnselectable: (date: DateValue) => boolean | void | UnselectableInfo;
-        isDayVisible: (date: DateValue) => boolean;
-        isOutsideAllowedDates: (date: DateValue) => boolean;
-        isOutsideAllowedMonths: (date: DateValue) => boolean;
-        isOutsideAllowedYears: (date: DateValue) => boolean;
+        /**
+         * Sets the visible month in the calendar.
+         *
+         * @param event - The synthetic event or null if triggered by code.
+         * @param newVisibleMonth - The new visible month to set.
+         */
+        setVisibleMonth: (event: SyntheticEvent | null, newVisibleMonth: TDate) => void;
+        /**
+         * Sets the focused date in the calendar.
+         *
+         * @param event - The synthetic event or null if triggered by code.
+         * @param date - The new date to focus.
+         */
+        setFocusedDate: (event: SyntheticEvent | null, date: TDate | null) => void;
+        /**
+         * Determines if a day is unselectable.
+         *
+         * @param date - The date to check.
+         * @returns A string reason if the day is unselectable, otherwise `false` or `undefined`.
+         */
+        isDayUnselectable: (date: TDate) => string | false | undefined;
+        /**
+         * Determines if a day is highlighted.
+         *
+         * @param date - The date to check.
+         * @returns A string reason if the day is highlighted, otherwise `false` or `undefined`.
+         */
+        isDayHighlighted: (date: TDate) => string | false | undefined;
+        /**
+         * Determines if a day is disabled.
+         *
+         * @param date - The date to check.
+         * @returns A string reason if the day is disabled, otherwise `false` or `undefined`.
+         */
+        isDayDisabled: (date: TDate) => string | false | undefined;
+        /**
+         * Determines if a day is visible in the calendar.
+         *
+         * @param date - The date to check.
+         * @returns `true` if the day is visible, otherwise `false`.
+         */
+        isDayVisible: (date: TDate) => boolean;
+        /**
+         * Determines if a date is outside the allowed date range.
+         *
+         * @param date - The date to check.
+         * @returns `true` if the date is outside the allowed range, otherwise `false`.
+         */
+        isOutsideAllowedDates: (date: TDate) => boolean;
+        /**
+         * Determines if a month is outside the allowed range.
+         *
+         * @param date - The date to check.
+         * @returns `true` if the month is outside the allowed range, otherwise `false`.
+         */
+        isOutsideAllowedMonths: (date: TDate) => boolean;
+        /**
+         * Determines if a year is outside the allowed range.
+         *
+         * @param date - The date to check.
+         * @returns `true` if the year is outside the allowed range, otherwise `false`.
+         */
+        isOutsideAllowedYears: (date: TDate) => boolean;
+        /**
+         * Sets the selected date in the calendar.
+         *
+         * @param event - The event triggering the change.
+         * @param newSelectedDate - The new date to select.
+         */
+        setSelectedDate: (event: React.KeyboardEvent<HTMLButtonElement> | React.MouseEvent<HTMLButtonElement, MouseEvent>, newSelectedDate: TDate) => void;
+        /**
+         * Determines if a date is selected.
+         *
+         * @param date - The date to check.
+         * @returns `true` if the date is selected, otherwise `false`.
+         */
+        isSelected: (date: TDate) => boolean;
+        /**
+         * Sets the hovered date in the calendar.
+         *
+         * @param event - The event triggering the change.
+         * @param newHoveredDate - The new date to hover.
+         */
+        setHoveredDate: (event: SyntheticEvent, newHoveredDate: TDate | null) => void;
+        /**
+         * Determines if a date is part of a selected span.
+         *
+         * @param date - The date to check.
+         * @returns `true` if the date is part of a selected span, otherwise `false`.
+         */
+        isSelectedSpan: (date: TDate) => boolean;
+        /**
+         * Determines if a date is part of a hovered span.
+         *
+         * @param date - The date to check.
+         * @returns `true` if the date is part of a hovered span, otherwise `false`.
+         */
+        isHoveredSpan: (date: TDate) => boolean;
+        /**
+         * Determines if a date is the start of a selected range.
+         *
+         * @param date - The date to check.
+         * @returns `true` if the date is the start of a selected range, otherwise `false`.
+         */
+        isSelectedStart: (date: TDate) => boolean;
+        /**
+         * Determines if a date is the end of a selected range.
+         *
+         * @param date - The date to check.
+         * @returns `true` if the date is the end of a selected range, otherwise `false`.
+         */
+        isSelectedEnd: (date: TDate) => boolean;
+        /**
+         * Determines if a date is hovered.
+         *
+         * @param date - The date to check.
+         * @returns `true` if the date is hovered, otherwise `false`.
+         */
+        isHovered: (date: TDate) => boolean;
+        /**
+         * Determines if a date is part of a hovered offset.
+         *
+         * @param date - The date to check.
+         * @returns `true` if the date is part of a hovered offset, otherwise `false`.
+         */
+        isHoveredOffset: (date: TDate) => boolean;
+        /**
+         * Determines if a day is selectable.
+         *
+         * @param date - The date to check.
+         * @returns `true` if the day is selectable, otherwise `false`.
+         */
+        isDaySelectable: (date: TDate) => boolean;
     };
-};
+}
+export declare function useCalendar<TDate extends DateFrameworkType>(props: UseCalendarProps<TDate>): UseCalendarReturn<TDate>;
 export {};

package/dist-types/calendar/useCalendarDay.d.ts

@@ -1,19 +1,59 @@
-import { DateValue } from "@internationalized/date";
-import { RefObject } from "react";
-export declare type DayStatus = {
+import type { DateFrameworkType } from "@salt-ds/date-adapters";
+/**
+ * Interface representing the status of a day in the Calendar.
+ */
+export interface DayStatus {
+    /**
+     * If `true`, the day is out of the selectable range.
+     */
     outOfRange?: boolean;
+    /**
+     * If `true`, the day is selected.
+     */
     selected?: boolean;
+    /**
+     * If `true`, the day is today.
+     */
     today?: boolean;
-    unselectable?: "medium" | "low" | false;
+    /**
+     * If set, the day is unselectable with a reason.
+     */
+    unselectable?: string | false;
+    /**
+     * If set, the day is highlighted with a reason.
+     */
+    highlighted?: string | false;
+    /**
+     * If `true`, the day is focused.
+     */
     focused?: boolean;
+    /**
+     * If `true`, the day is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * If `true`, the day is hidden.
+     */
     hidden?: boolean;
-};
-export interface useCalendarDayProps {
-    date: DateValue;
-    month: DateValue;
 }
-export declare function useCalendarDay({ date, month }: useCalendarDayProps, ref: RefObject<HTMLElement>): {
+/**
+ * UseCalendar hook props to return a calendar day's status
+ * @template TDate - The type of the date object.
+ */
+export interface useCalendarDayProps<TDate> {
+    /**
+     * The date of the calendar day.
+     */
+    date: TDate;
+    /**
+     * The month of the calendar day.
+     */
+    month: TDate;
+}
+export declare function useCalendarDay<TDate extends DateFrameworkType>(props: useCalendarDayProps<TDate>): {
     status: DayStatus;
     dayProps: Omit<import("react").DetailedHTMLProps<import("react").ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref">;
-    unselectableReason: string | undefined;
+    focusedDateRef: any;
+    unselectableReason: string | false | undefined;
+    highlightedReason: string | false | undefined;
 };