@stenajs-webui/calendar 24.0.0 → 25.0.0

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

@@ -4,19 +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;
-    /**
-     * 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;
@@ -31,23 +22,6 @@ export interface TravelDateCalendarProps extends ValueAndOnValueChangeProps<stri
      * navigation, stays the calendar's. See RenderTravelDateContent.
      */
     renderDateContent?: RenderTravelDateContent;
-    /**
-     * 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;
     prevMonthDisabled?: (visibleMonth: Date) => boolean;
     nextMonthDisabled?: (visibleMonth: Date) => boolean;
     size?: TravelCalendarSizeVariant;

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

@@ -3,19 +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;
-    /**
-     * 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;
@@ -27,23 +18,6 @@ export interface TravelDateCalendarPanelProps extends ValueAndOnValueChangeProps
      * navigation, stays the calendar's. See RenderTravelDateContent.
      */
     renderDateContent?: RenderTravelDateContent;
-    /**
-     * 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;
     prevMonthDisabled?: (visibleMonth: Date) => boolean;
     nextMonthDisabled?: (visibleMonth: Date) => boolean;
     size?: TravelCalendarSizeVariant;

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

@@ -4,19 +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;
-    /**
-     * 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;
@@ -32,23 +23,6 @@ export interface TravelDateRangeCalendarProps extends ValueAndOnValueChangeProps
      * navigation, stays the calendar's. See RenderTravelDateContent.
      */
     renderDateContent?: RenderTravelDateContent;
-    /**
-     * 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;
     prevMonthDisabled?: (visibleMonth: Date) => boolean;
     nextMonthDisabled?: (visibleMonth: Date) => boolean;
     size?: TravelCalendarSizeVariant;

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

@@ -5,22 +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;
-    /**
-     * 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;
@@ -35,23 +26,6 @@ export interface TravelDateInputProps extends ValueAndOnValueChangeProps<string>
      * navigation, stays the calendar's. See RenderTravelDateContent.
      */
     renderDateContent?: RenderTravelDateContent;
-    /**
-     * 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;
     prevMonthDisabled?: (visibleMonth: Date) => boolean;
     nextMonthDisabled?: (visibleMonth: Date) => boolean;
     zIndex?: number;

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

@@ -5,22 +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;
-    /**
-     * 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;
@@ -36,23 +27,6 @@ export interface TravelDateRangeInputProps extends ValueAndOnValueChangeProps<Tr
      * navigation, stays the calendar's. See RenderTravelDateContent.
      */
     renderDateContent?: RenderTravelDateContent;
-    /**
-     * 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;
     prevMonthDisabled?: (visibleMonth: Date) => boolean;
     nextMonthDisabled?: (visibleMonth: Date) => boolean;
     zIndex?: number;

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

@@ -9,8 +9,12 @@
  * 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.
+ * 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.

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

@@ -1,5 +1,39 @@
+/**
+ * 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;
 }
 /**
@@ -14,20 +48,34 @@ export interface VisibleMonthState {
  *
  * 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:
+ * month of its value. To keep that, start from the value's date, with a
+ * function, the way useState takes one:
  *
- * const visibleMonthState = useVisibleMonthState(
- *   parseLocalizedDateString(value, localeCode),
+ * const visibleMonthState = useVisibleMonthState(() =>
+ *   value ? parseLocalizedDateString(value, localeCode) : undefined,
  * );
  *
- * 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.
+ * 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. Defaults to the current month.
+ * @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();
@@ -38,4 +86,4 @@ export interface VisibleMonthState {
  *   {...visibleMonthState}
  * />
  */
-export declare const useVisibleMonthState: (initialMonth?: Date) => VisibleMonthState;
+export declare const useVisibleMonthState: (initialMonth?: Date | (() => Date | undefined)) => VisibleMonthState;