@stenajs-webui/calendar 23.23.0 → 24.0.0

package/README.md

@@ -5,6 +5,18 @@ and input fields using calendar functionality.
 
 ## Components
 
+### Travel calendars
+
+One month at a time, for picking travel dates. Each date can show custom
+content, such as a price. See [AGENT_DOC.mdx](AGENT_DOC.mdx), which is also the
+"AI Documentation/Calendar" page in Storybook.
+
+* TravelDateInput
+* TravelDateRangeInput
+* TravelDateCalendar
+* TravelDateCalendarPanel
+* TravelDateRangeCalendar
+
 ### Calendars
 
 * [DateRangeCalendar](src/components/calendar-types/date-range-calendar/DateRangeCalendar.md)

package/dist/components/calendar-types/travel-date-calendar/TravelDateCalendar.d.ts

@@ -7,7 +7,16 @@ import { SupportedLocaleCode } from "../../../features/localize-date-format/Loca
 export interface TravelDateCalendarProps extends ValueAndOnValueChangeProps<string> {
     localeCode?: SupportedLocaleCode;
     languageLocaleCode?: SupportedLocaleCode;
-    initialMonthInFocus?: Date;
+    /**
+     * The month the calendar shows. Only its year and month are read, so any
+     * day of the month will do. The calendar never changes it by itself; see
+     * onVisibleMonthChange.
+     *
+     * It is not taken from the value. To open on the month of a value, pass
+     * that month, for example with
+     * useVisibleMonthState(parseLocalizedDateString(value, localeCode)).
+     */
+    visibleMonth: Date;
     label?: string;
     previousMonthButtonAriaLabel?: string;
     nextMonthButtonAriaLabel?: string;
@@ -23,12 +32,22 @@ export interface TravelDateCalendarProps extends ValueAndOnValueChangeProps<stri
      */
     renderDateContent?: RenderTravelDateContent;
     /**
-     * Called with the first day of the month the calendar shows: once when the
-     * component mounts, and again each time the user moves to another month.
-     * For loading data one month at a time, such as prices for
-     * renderDateContent.
+     * Called when the calendar should show another month: from the month
+     * buttons, the month picker, the arrow keys, or a value in another month.
+     * It gets the first day of that month, and the calendar moves once
+     * visibleMonth is set to it. It is not called for the month already shown.
+     *
+     * When it follows a value, it never asks for a month before the current
+     * one: a value in the past asks for the current month. The month buttons
+     * and the arrow keys are not limited that way. To keep the user out of
+     * past months, set prevMonthDisabled and isDateDisabled, for example with
+     * usePrevMonthDisabledBeforeToday() and useDisabledBeforeToday(). The
+     * month picker starts at firstMonthInMonthPicker, the current month by
+     * default.
+     *
+     * useVisibleMonthState() keeps this state, for when nothing else needs it.
      */
-    onVisibleMonthChange?: (visibleMonth: Date) => void;
+    onVisibleMonthChange: (visibleMonth: Date) => void;
     prevMonthDisabled?: (visibleMonth: Date) => boolean;
     nextMonthDisabled?: (visibleMonth: Date) => boolean;
     size?: TravelCalendarSizeVariant;

package/dist/components/calendar-types/travel-date-calendar-panel/TravelDateCalendarPanel.d.ts

@@ -6,7 +6,16 @@ import { RenderTravelDateContent } from "../../../features/travel-calendar/types
 export interface TravelDateCalendarPanelProps extends ValueAndOnValueChangeProps<string> {
     localeCode?: SupportedLocaleCode;
     languageLocaleCode?: SupportedLocaleCode;
-    initialMonthInFocus?: Date;
+    /**
+     * The month the calendar shows. Only its year and month are read, so any
+     * day of the month will do. The calendar never changes it by itself; see
+     * onVisibleMonthChange.
+     *
+     * It is not taken from the value. To open on the month of a value, pass
+     * that month, for example with
+     * useVisibleMonthState(parseLocalizedDateString(value, localeCode)).
+     */
+    visibleMonth: Date;
     previousMonthButtonAriaLabel?: string;
     nextMonthButtonAriaLabel?: string;
     firstMonthInMonthPicker?: Date;
@@ -19,12 +28,22 @@ export interface TravelDateCalendarPanelProps extends ValueAndOnValueChangeProps
      */
     renderDateContent?: RenderTravelDateContent;
     /**
-     * Called with the first day of the month the calendar shows: once when the
-     * component mounts, and again each time the user moves to another month.
-     * For loading data one month at a time, such as prices for
-     * renderDateContent.
+     * Called when the calendar should show another month: from the month
+     * buttons, the month picker, the arrow keys, or a value in another month.
+     * It gets the first day of that month, and the calendar moves once
+     * visibleMonth is set to it. It is not called for the month already shown.
+     *
+     * When it follows a value, it never asks for a month before the current
+     * one: a value in the past asks for the current month. The month buttons
+     * and the arrow keys are not limited that way. To keep the user out of
+     * past months, set prevMonthDisabled and isDateDisabled, for example with
+     * usePrevMonthDisabledBeforeToday() and useDisabledBeforeToday(). The
+     * month picker starts at firstMonthInMonthPicker, the current month by
+     * default.
+     *
+     * useVisibleMonthState() keeps this state, for when nothing else needs it.
      */
-    onVisibleMonthChange?: (visibleMonth: Date) => void;
+    onVisibleMonthChange: (visibleMonth: Date) => void;
     prevMonthDisabled?: (visibleMonth: Date) => boolean;
     nextMonthDisabled?: (visibleMonth: Date) => boolean;
     size?: TravelCalendarSizeVariant;

package/dist/components/calendar-types/travel-date-range-calendar/TravelDateRangeCalendar.d.ts

@@ -7,7 +7,16 @@ import { SupportedLocaleCode } from "../../../features/localize-date-format/Loca
 export interface TravelDateRangeCalendarProps extends ValueAndOnValueChangeProps<TravelDateRangeInputValue> {
     localeCode?: SupportedLocaleCode;
     languageLocaleCode?: SupportedLocaleCode;
-    initialMonthInFocus?: Date;
+    /**
+     * The month the calendar shows. Only its year and month are read, so any
+     * day of the month will do. The calendar never changes it by itself; see
+     * onVisibleMonthChange.
+     *
+     * It is not taken from the value. To open on the month of a value, pass
+     * that month, for example with
+     * useVisibleMonthState(parseLocalizedDateString(value, localeCode)).
+     */
+    visibleMonth: Date;
     startDateLabel?: string;
     endDateLabel?: string;
     previousMonthButtonAriaLabel?: string;
@@ -24,12 +33,22 @@ export interface TravelDateRangeCalendarProps extends ValueAndOnValueChangeProps
      */
     renderDateContent?: RenderTravelDateContent;
     /**
-     * Called with the first day of the month the calendar shows: once when the
-     * component mounts, and again each time the user moves to another month.
-     * For loading data one month at a time, such as prices for
-     * renderDateContent.
+     * Called when the calendar should show another month: from the month
+     * buttons, the month picker, the arrow keys, or a value in another month.
+     * It gets the first day of that month, and the calendar moves once
+     * visibleMonth is set to it. It is not called for the month already shown.
+     *
+     * When it follows a value, it never asks for a month before the current
+     * one: a value in the past asks for the current month. The month buttons
+     * and the arrow keys are not limited that way. To keep the user out of
+     * past months, set prevMonthDisabled and isDateDisabled, for example with
+     * usePrevMonthDisabledBeforeToday() and useDisabledBeforeToday(). The
+     * month picker starts at firstMonthInMonthPicker, the current month by
+     * default.
+     *
+     * useVisibleMonthState() keeps this state, for when nothing else needs it.
      */
-    onVisibleMonthChange?: (visibleMonth: Date) => void;
+    onVisibleMonthChange: (visibleMonth: Date) => void;
     prevMonthDisabled?: (visibleMonth: Date) => boolean;
     nextMonthDisabled?: (visibleMonth: Date) => boolean;
     size?: TravelCalendarSizeVariant;

package/dist/components/input-types/travel-date-input/TravelDateInput.d.ts

@@ -11,7 +11,16 @@ export interface RenderBelowSingleDateCalendarArgs {
 export interface TravelDateInputProps extends ValueAndOnValueChangeProps<string> {
     localeCode?: SupportedLocaleCode;
     languageLocaleCode?: SupportedLocaleCode;
-    initialMonthInFocus?: Date;
+    /**
+     * The month the calendar shows. Only its year and month are read, so any
+     * day of the month will do. The calendar never changes it by itself; see
+     * onVisibleMonthChange.
+     *
+     * It is not taken from the value. To open on the month of a value, pass
+     * that month, for example with
+     * useVisibleMonthState(parseLocalizedDateString(value, localeCode)).
+     */
+    visibleMonth: Date;
     label?: string;
     previousMonthButtonAriaLabel?: string;
     nextMonthButtonAriaLabel?: string;
@@ -27,12 +36,22 @@ export interface TravelDateInputProps extends ValueAndOnValueChangeProps<string>
      */
     renderDateContent?: RenderTravelDateContent;
     /**
-     * Called with the first day of the month the calendar shows: once when the
-     * component mounts, and again each time the user moves to another month.
-     * For loading data one month at a time, such as prices for
-     * renderDateContent.
+     * Called when the calendar should show another month: from the month
+     * buttons, the month picker, the arrow keys, or a value in another month.
+     * It gets the first day of that month, and the calendar moves once
+     * visibleMonth is set to it. It is not called for the month already shown.
+     *
+     * When it follows a value, it never asks for a month before the current
+     * one: a value in the past asks for the current month. The month buttons
+     * and the arrow keys are not limited that way. To keep the user out of
+     * past months, set prevMonthDisabled and isDateDisabled, for example with
+     * usePrevMonthDisabledBeforeToday() and useDisabledBeforeToday(). The
+     * month picker starts at firstMonthInMonthPicker, the current month by
+     * default.
+     *
+     * useVisibleMonthState() keeps this state, for when nothing else needs it.
      */
-    onVisibleMonthChange?: (visibleMonth: Date) => void;
+    onVisibleMonthChange: (visibleMonth: Date) => void;
     prevMonthDisabled?: (visibleMonth: Date) => boolean;
     nextMonthDisabled?: (visibleMonth: Date) => boolean;
     zIndex?: number;

package/dist/components/input-types/travel-date-range-input/TravelDateRangeInput.d.ts

@@ -11,7 +11,16 @@ export interface RenderBelowCalendarArgs {
 export interface TravelDateRangeInputProps extends ValueAndOnValueChangeProps<TravelDateRangeInputValue> {
     localeCode?: SupportedLocaleCode;
     languageLocaleCode?: SupportedLocaleCode;
-    initialMonthInFocus?: Date;
+    /**
+     * The month the calendar shows. Only its year and month are read, so any
+     * day of the month will do. The calendar never changes it by itself; see
+     * onVisibleMonthChange.
+     *
+     * It is not taken from the value. To open on the month of a value, pass
+     * that month, for example with
+     * useVisibleMonthState(parseLocalizedDateString(value, localeCode)).
+     */
+    visibleMonth: Date;
     startDateLabel?: string;
     endDateLabel?: string;
     previousMonthButtonAriaLabel?: string;
@@ -28,12 +37,22 @@ export interface TravelDateRangeInputProps extends ValueAndOnValueChangeProps<Tr
      */
     renderDateContent?: RenderTravelDateContent;
     /**
-     * Called with the first day of the month the calendar shows: once when the
-     * component mounts, and again each time the user moves to another month.
-     * For loading data one month at a time, such as prices for
-     * renderDateContent.
+     * Called when the calendar should show another month: from the month
+     * buttons, the month picker, the arrow keys, or a value in another month.
+     * It gets the first day of that month, and the calendar moves once
+     * visibleMonth is set to it. It is not called for the month already shown.
+     *
+     * When it follows a value, it never asks for a month before the current
+     * one: a value in the past asks for the current month. The month buttons
+     * and the arrow keys are not limited that way. To keep the user out of
+     * past months, set prevMonthDisabled and isDateDisabled, for example with
+     * usePrevMonthDisabledBeforeToday() and useDisabledBeforeToday(). The
+     * month picker starts at firstMonthInMonthPicker, the current month by
+     * default.
+     *
+     * useVisibleMonthState() keeps this state, for when nothing else needs it.
      */
-    onVisibleMonthChange?: (visibleMonth: Date) => void;
+    onVisibleMonthChange: (visibleMonth: Date) => void;
     prevMonthDisabled?: (visibleMonth: Date) => boolean;
     nextMonthDisabled?: (visibleMonth: Date) => boolean;
     zIndex?: number;

package/dist/features/travel-calendar/components/TravelDateCell.d.ts

@@ -10,6 +10,8 @@ export interface TravelDateCellProps {
     selectedEndDate: Date | undefined;
     isValidDateRange: boolean;
     onChangeVisibleMonth: (visibleMonth: Date) => void;
+    /** Focuses the date once its month is shown, which the app decides. */
+    focusDateWhenShown: (date: Date) => void;
     onStartHover: (date: Date) => void;
     onEndHover: (date: Date) => void;
     /** Current date that the mouse is hovering over. */

package/dist/features/travel-calendar/components/__tests__/StatefulTravelCalendars.d.ts

@@ -0,0 +1,16 @@
+import * as React from "react";
+import { VisibleMonthState } from "../../hooks/UseVisibleMonthState";
+/**
+ * The travel calendars with their visible month kept in state, the way an app
+ * using useVisibleMonthState would. For tests that are about something else,
+ * and still need the month buttons and the arrow keys to move the calendar.
+ */
+type WithMonthState<P> = Omit<P, keyof VisibleMonthState> & {
+    initialMonth?: Date;
+};
+export declare const StatefulTravelDateInput: ({ initialMonth, ...props }: WithMonthState<import("../../../..").TravelDateInputProps>) => React.JSX.Element;
+export declare const StatefulTravelDateRangeInput: ({ initialMonth, ...props }: WithMonthState<import("../../../..").TravelDateRangeInputProps>) => React.JSX.Element;
+export declare const StatefulTravelDateCalendar: ({ initialMonth, ...props }: WithMonthState<import("../../../..").TravelDateCalendarProps>) => React.JSX.Element;
+export declare const StatefulTravelDateCalendarPanel: ({ initialMonth, ...props }: WithMonthState<import("../../../..").TravelDateCalendarPanelProps>) => React.JSX.Element;
+export declare const StatefulTravelDateRangeCalendar: ({ initialMonth, ...props }: WithMonthState<import("../../../..").TravelDateRangeCalendarProps>) => React.JSX.Element;
+export {};

package/dist/features/travel-calendar/hooks/UseControlledVisibleMonth.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The visible month of a travel calendar, which the app owns.
+ *
+ * The calendar never changes the month itself. Everything that would move it,
+ * the month buttons, the month picker, the arrow keys and a new value, asks the
+ * app instead, through onVisibleMonthChange.
+ *
+ * The request is always the first day of the month. The arrow keys and the
+ * month picker work with other days of the month, and the app should get the
+ * same month in the same form whichever way it was reached.
+ *
+ * A request for the month that is already visible is not made at all, so the
+ * app only hears about actual changes.
+ *
+ * The month is kept by year and month, so an app that passes a new Date on
+ * every render, such as new Date(), does not rebuild the calendar each time.
+ */
+export declare const useControlledVisibleMonth: (visibleMonthValue: Date, onVisibleMonthChange: (visibleMonth: Date) => void, today: Date) => {
+    visibleMonth: Date;
+    setVisibleMonth: (requested: Date) => void;
+    setVisibleMonthClamped: (requested: Date) => void;
+};

package/dist/features/travel-calendar/hooks/UseTravelDateInput.d.ts

@@ -1,6 +1,6 @@
 import { SupportedLocaleCode } from "../../localize-date-format/LocaleMapper";
 import { VisiblePanel } from "../types";
-export declare const useTravelDateInput: (value: string | undefined, onValueChange: ((value: string) => void) | undefined, localeCode: SupportedLocaleCode, languageLocaleCode: SupportedLocaleCode, initialMonthInFocus: Date | undefined, onClickDate?: (date: Date) => void) => {
+export declare const useTravelDateInput: (value: string | undefined, onValueChange: ((value: string) => void) | undefined, localeCode: SupportedLocaleCode, languageLocaleCode: SupportedLocaleCode, visibleMonthValue: Date, onVisibleMonthChange: (visibleMonth: Date) => void, onClickDate?: (date: Date) => void) => {
     onClickDate: (date: Date) => void;
     onValueChangeByInputs: (value: string) => void;
     monthPickerButtonRef: import("react").RefObject<HTMLButtonElement | null>;
@@ -8,7 +8,7 @@ export declare const useTravelDateInput: (value: string | undefined, onValueChan
     monthPickerButtonLabel: string;
     visiblePanel: VisiblePanel;
     setVisiblePanel: import("react").Dispatch<import("react").SetStateAction<VisiblePanel>>;
-    setVisibleMonth: import("react").Dispatch<import("react").SetStateAction<Date>>;
+    setVisibleMonth: (requested: Date) => void;
     visibleMonthData: import("../../..").MonthData;
     todayIsInVisibleMonth: boolean;
     hoverDate: Date | undefined;

package/dist/features/travel-calendar/hooks/UseTravelDateRangeInput.d.ts

@@ -1,6 +1,6 @@
 import { SupportedLocaleCode } from "../../localize-date-format/LocaleMapper";
 import { TravelDateRangeInputValue, VisiblePanel } from "../types";
-export declare const useTravelDateRangeInput: (value: TravelDateRangeInputValue | undefined, onValueChange: ((value: TravelDateRangeInputValue) => void) | undefined, localeCode: SupportedLocaleCode, languageLocaleCode: SupportedLocaleCode, initialMonthInFocus: Date | undefined, fieldLastInFocus: "startDate" | "endDate" | undefined, setFieldLastInFocus: (field: "startDate" | "endDate" | undefined) => void, moveFocusToField: (field: "startDate" | "endDate") => void, hideCalendar: undefined | (() => void)) => {
+export declare const useTravelDateRangeInput: (value: TravelDateRangeInputValue | undefined, onValueChange: ((value: TravelDateRangeInputValue) => void) | undefined, localeCode: SupportedLocaleCode, languageLocaleCode: SupportedLocaleCode, visibleMonthValue: Date, onVisibleMonthChange: (visibleMonth: Date) => void, fieldLastInFocus: "startDate" | "endDate" | undefined, setFieldLastInFocus: (field: "startDate" | "endDate" | undefined) => void, moveFocusToField: (field: "startDate" | "endDate") => void, hideCalendar: undefined | (() => void)) => {
     onClickDate: (date: Date) => void;
     onValueChangeByInputs: (value: TravelDateRangeInputValue) => void;
     isValidDateRange: boolean;
@@ -9,7 +9,7 @@ export declare const useTravelDateRangeInput: (value: TravelDateRangeInputValue
     monthPickerButtonLabel: string;
     visiblePanel: VisiblePanel;
     setVisiblePanel: import("react").Dispatch<import("react").SetStateAction<VisiblePanel>>;
-    setVisibleMonth: import("react").Dispatch<import("react").SetStateAction<Date>>;
+    setVisibleMonth: (requested: Date) => void;
     visibleMonthData: import("../../..").MonthData;
     todayIsInVisibleMonth: boolean;
     hoverDate: Date | undefined;

package/dist/features/travel-calendar/hooks/UseVisibleMonthState.d.ts

@@ -0,0 +1,41 @@
+export interface VisibleMonthState {
+    visibleMonth: Date;
+    onVisibleMonthChange: (visibleMonth: Date) => void;
+}
+/**
+ * Keeps the visible month of a travel calendar, for when nothing else needs to
+ * know it.
+ *
+ * The travel calendars do not keep their visible month themselves; the app
+ * passes it in as visibleMonth and changes it in onVisibleMonthChange. This is
+ * that state, returned as those two props, so it can be spread onto the
+ * calendar. Keep the state elsewhere instead when something else depends on
+ * the month, such as data loaded for it.
+ *
+ * It starts at the current month, not at the month of a value. Before the
+ * month was controlled, a calendar without initialMonthInFocus opened on the
+ * month of its value. To keep that, start from the value's date:
+ *
+ * const visibleMonthState = useVisibleMonthState(
+ *   parseLocalizedDateString(value, localeCode),
+ * );
+ *
+ * parseLocalizedDateString returns undefined for an empty or incomplete
+ * value, which falls back to the current month. Only the first render's
+ * month is used, like any initial state.
+ *
+ * A calendar that had initialMonthInFocus passes that month instead:
+ * useVisibleMonthState(initialMonthInFocus).
+ *
+ * @param initialMonth The month to show first. Defaults to the current month.
+ *
+ * @example
+ * const visibleMonthState = useVisibleMonthState();
+ *
+ * <TravelDateInput
+ *   value={value}
+ *   onValueChange={setValue}
+ *   {...visibleMonthState}
+ * />
+ */
+export declare const useVisibleMonthState: (initialMonth?: Date) => VisibleMonthState;

package/dist/index.d.ts

@@ -35,6 +35,7 @@ export * from "./components/calendar-types/travel-date-calendar-panel/TravelDate
 export type { TravelCalendarSizeVariant } from "./features/travel-calendar/components/TravelCalendar";
 export * from "./components/calendar-types/travel-date-range-calendar/TravelDateRangeCalendar";
 export * from "./features/travel-calendar/hooks/DisabledDateHooks";
+export * from "./features/travel-calendar/hooks/UseVisibleMonthState";
 export * from "./features/travel-calendar/types";
 export * from "./features/localize-date-format/LocalizedDateFormatter";
 export * from "./features/localize-date-format/LocalizedDateParser";