@stenajs-webui/calendar 23.23.1 → 24.0.1

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

@@ -4,10 +4,10 @@ import { ValueAndOnValueChangeProps } from "@stenajs-webui/forms";
 import { TravelCalendarSizeVariant } from "../../../features/travel-calendar/components/TravelCalendar";
 import { DateTextInputVariant, RenderTravelDateContent } from "../../../features/travel-calendar/types";
 import { SupportedLocaleCode } from "../../../features/localize-date-format/LocaleMapper";
-export interface TravelDateCalendarProps extends ValueAndOnValueChangeProps<string> {
+import { VisibleMonthState } from "../../../features/travel-calendar/hooks/UseVisibleMonthState";
+export interface TravelDateCalendarProps extends ValueAndOnValueChangeProps<string>, VisibleMonthState {
     localeCode?: SupportedLocaleCode;
     languageLocaleCode?: SupportedLocaleCode;
-    initialMonthInFocus?: Date;
     label?: string;
     previousMonthButtonAriaLabel?: string;
     nextMonthButtonAriaLabel?: string;
@@ -22,13 +22,6 @@ export interface TravelDateCalendarProps extends ValueAndOnValueChangeProps<stri
      * navigation, stays the calendar's. See RenderTravelDateContent.
      */
     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.
-     */
-    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

@@ -3,10 +3,10 @@ import { ValueAndOnValueChangeProps } from "@stenajs-webui/forms";
 import { TravelCalendarSizeVariant } from "../../../features/travel-calendar/components/TravelCalendar";
 import { SupportedLocaleCode } from "../../../features/localize-date-format/LocaleMapper";
 import { RenderTravelDateContent } from "../../../features/travel-calendar/types";
-export interface TravelDateCalendarPanelProps extends ValueAndOnValueChangeProps<string> {
+import { VisibleMonthState } from "../../../features/travel-calendar/hooks/UseVisibleMonthState";
+export interface TravelDateCalendarPanelProps extends ValueAndOnValueChangeProps<string>, VisibleMonthState {
     localeCode?: SupportedLocaleCode;
     languageLocaleCode?: SupportedLocaleCode;
-    initialMonthInFocus?: Date;
     previousMonthButtonAriaLabel?: string;
     nextMonthButtonAriaLabel?: string;
     firstMonthInMonthPicker?: Date;
@@ -18,13 +18,6 @@ export interface TravelDateCalendarPanelProps extends ValueAndOnValueChangeProps
      * navigation, stays the calendar's. See RenderTravelDateContent.
      */
     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.
-     */
-    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

@@ -4,10 +4,10 @@ import { ValueAndOnValueChangeProps } from "@stenajs-webui/forms";
 import { TravelCalendarSizeVariant } from "../../../features/travel-calendar/components/TravelCalendar";
 import { DateTextInputVariant, TravelDateRangeInputValue, RenderTravelDateContent } from "../../../features/travel-calendar/types";
 import { SupportedLocaleCode } from "../../../features/localize-date-format/LocaleMapper";
-export interface TravelDateRangeCalendarProps extends ValueAndOnValueChangeProps<TravelDateRangeInputValue> {
+import { VisibleMonthState } from "../../../features/travel-calendar/hooks/UseVisibleMonthState";
+export interface TravelDateRangeCalendarProps extends ValueAndOnValueChangeProps<TravelDateRangeInputValue>, VisibleMonthState {
     localeCode?: SupportedLocaleCode;
     languageLocaleCode?: SupportedLocaleCode;
-    initialMonthInFocus?: Date;
     startDateLabel?: string;
     endDateLabel?: string;
     previousMonthButtonAriaLabel?: string;
@@ -23,13 +23,6 @@ export interface TravelDateRangeCalendarProps extends ValueAndOnValueChangeProps
      * navigation, stays the calendar's. See RenderTravelDateContent.
      */
     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.
-     */
-    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

@@ -5,13 +5,13 @@ import { ValueAndOnValueChangeProps } from "@stenajs-webui/forms";
 import { TravelCalendarSizeVariant } from "../../../features/travel-calendar/components/TravelCalendar";
 import { DateTextInputVariant, RenderTravelDateContent } from "../../../features/travel-calendar/types";
 import { SupportedLocaleCode } from "../../../features/localize-date-format/LocaleMapper";
+import { VisibleMonthState } from "../../../features/travel-calendar/hooks/UseVisibleMonthState";
 export interface RenderBelowSingleDateCalendarArgs {
     hideCalendar: () => void;
 }
-export interface TravelDateInputProps extends ValueAndOnValueChangeProps<string> {
+export interface TravelDateInputProps extends ValueAndOnValueChangeProps<string>, VisibleMonthState {
     localeCode?: SupportedLocaleCode;
     languageLocaleCode?: SupportedLocaleCode;
-    initialMonthInFocus?: Date;
     label?: string;
     previousMonthButtonAriaLabel?: string;
     nextMonthButtonAriaLabel?: string;
@@ -26,13 +26,6 @@ export interface TravelDateInputProps extends ValueAndOnValueChangeProps<string>
      * navigation, stays the calendar's. See RenderTravelDateContent.
      */
     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.
-     */
-    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

@@ -5,13 +5,13 @@ import { ValueAndOnValueChangeProps } from "@stenajs-webui/forms";
 import { TravelCalendarSizeVariant } from "../../../features/travel-calendar/components/TravelCalendar";
 import { DateTextInputVariant, TravelDateRangeInputValue, RenderTravelDateContent } from "../../../features/travel-calendar/types";
 import { SupportedLocaleCode } from "../../../features/localize-date-format/LocaleMapper";
+import { VisibleMonthState } from "../../../features/travel-calendar/hooks/UseVisibleMonthState";
 export interface RenderBelowCalendarArgs {
     hideCalendar: () => void;
 }
-export interface TravelDateRangeInputProps extends ValueAndOnValueChangeProps<TravelDateRangeInputValue> {
+export interface TravelDateRangeInputProps extends ValueAndOnValueChangeProps<TravelDateRangeInputValue>, VisibleMonthState {
     localeCode?: SupportedLocaleCode;
     languageLocaleCode?: SupportedLocaleCode;
-    initialMonthInFocus?: Date;
     startDateLabel?: string;
     endDateLabel?: string;
     previousMonthButtonAriaLabel?: string;
@@ -27,13 +27,6 @@ export interface TravelDateRangeInputProps extends ValueAndOnValueChangeProps<Tr
      * navigation, stays the calendar's. See RenderTravelDateContent.
      */
     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.
-     */
-    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,26 @@
+/**
+ * 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. The
+ * check is against the month of the last render, so two requests made before
+ * the app has passed a month back, such as two quick clicks while it loads,
+ * both reach it, the same way two quick edits reach any controlled input
+ * that updates later. The second request is left to the app rather than
+ * dropped here, since the app may not have taken the first.
+ *
+ * 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,89 @@
+/**
+ * The visible month of a travel calendar, which the app keeps. All five
+ * travel calendars take these two props, and useVisibleMonthState returns
+ * them, ready to spread onto one.
+ */
+export interface VisibleMonthState {
+    /**
+     * 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 the value, pass
+     * that month; useVisibleMonthState shows how.
+     */
+    visibleMonth: Date;
+    /**
+     * Called when the calendar should show another month: from the month
+     * buttons, the month picker, the arrow keys, or a date in another month
+     * that the calendar follows. The single date calendars follow their value,
+     * typed or set from outside. The range calendars only follow a date typed
+     * into one of their fields.
+     *
+     * 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 date, it never asks for a month before the current
+     * one: a date in the past asks for the current month, unless it is in the
+     * month already shown. 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;
+}
+/**
+ * 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, with a
+ * function, the way useState takes one:
+ *
+ * const visibleMonthState = useVisibleMonthState(() =>
+ *   value ? parseLocalizedDateString(value, localeCode) : undefined,
+ * );
+ *
+ * The function only runs on the first render, so the value is not parsed
+ * again on every render after it, and the check for a missing value keeps
+ * it type safe for an optional value. parseLocalizedDateString returns
+ * undefined for an incomplete value as well, and undefined falls back to
+ * the current month.
+ *
+ * The value of a range calendar is an object of two strings, so parse its
+ * start date instead:
+ *
+ * const visibleMonthState = useVisibleMonthState(() =>
+ *   value?.startDate
+ *     ? parseLocalizedDateString(value.startDate, localeCode)
+ *     : undefined,
+ * );
+ *
+ * A calendar that had initialMonthInFocus passes that month instead:
+ * useVisibleMonthState(initialMonthInFocus).
+ *
+ * @param initialMonth The month to show first, or a function that returns it,
+ * called once. Defaults to the current month, also when it is or returns
+ * undefined.
+ *
+ * @example
+ * const visibleMonthState = useVisibleMonthState();
+ *
+ * <TravelDateInput
+ *   value={value}
+ *   onValueChange={setValue}
+ *   {...visibleMonthState}
+ * />
+ */
+export declare const useVisibleMonthState: (initialMonth?: Date | (() => Date | undefined)) => 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";