@vaadin/date-picker 25.3.0-dev.1fa5a51482 → 25.3.0-rc1

package/src/vaadin-date-picker-helper.d.ts

@@ -3,21 +3,88 @@
  * Copyright (c) 2016 - 2026 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
+import type { DateMetadataController } from './vaadin-date-metadata-controller.js';
 import type { DatePickerDate } from './vaadin-date-picker-mixin.js';
 
+/**
+ * Create a date at midnight in local time. Unlike `new Date(year, month, day)`,
+ * this supports years below 100, which the constructor maps into the 20th
+ * century. The month is assigned before the day so that the initial day of month
+ * (1) always exists in the target month.
+ *
+ * @param month Zero-based month, may be out of range to shift the year
+ * @param day May be `0` to select the last day of the previous month
+ */
+declare function createDate(year: number, month: number, day: number): Date;
+
+/**
+ * Get the first day of the month the given date is in.
+ */
+declare function firstOfMonth(date: Date): Date;
+
+/**
+ * Get the last day of the month the given date is in.
+ */
+declare function lastOfMonth(date: Date): Date;
+
+/**
+ * Get the index of a month, counted from January of year 0. Reduces a month to a single
+ * integer, so a lookup builds no key and two months are adjacent when their indexes are.
+ *
+ * @param month Zero-based month
+ */
+declare function monthIndexOf(year: number, month: number): number;
+
+/**
+ * Get the index of the month the given date is in.
+ */
+declare function monthIndex(date: Date): number;
+
+/**
+ * Get the first day of the month with the given index, inverting `monthIndexOf`. Counting from
+ * January of year 0 also inverts negative indexes, since `createDate` normalizes a month outside
+ * 0-11 into the year.
+ */
+declare function monthDate(index: number): Date;
+
 /**
  * Get ISO 8601 week number for the given date.
  *
  * @returns Week number
  */
-declare function getISOWeekNumber(Date: Date): number;
+declare function getISOWeekNumber(date: Date): number;
+
+/**
+ * Creates a new object with the same date, but sets the hours, minutes, seconds and milliseconds to 0.
+ *
+ * @param date in system timezone
+ * @returns The same date with time elements set to 0, in system timezone.
+ */
+declare function normalizeDate(date: Date): Date;
+
+/**
+ * Creates a new object with the same date, but sets the hours, minutes, seconds and milliseconds to 0.
+ *
+ * Uses UTC date components to allow handling date instances independently of
+ * the system time-zone.
+ *
+ * @param date in UTC timezone
+ * @returns The same date with time elements set to 0, in UTC timezone.
+ */
+declare function normalizeUTCDate(date: Date): Date;
 
 /**
  * Check if two dates are equal.
  *
  * @returns True if the given date objects refer to the same date
  */
-declare function dateEquals(date1: Date | null, date2: Date | null): boolean;
+declare function dateEquals(date1: Date | null, date2: Date | null, normalizer?: (date: Date) => Date): boolean;
+
+/**
+ * Extracts the basic component parts of a date (day, month and year)
+ * to the expected format.
+ */
+declare function extractDateParts(date: Date): { day: number; month: number; year: number };
 
 /**
  * Check if the given date is in the range of allowed dates.
@@ -31,6 +98,21 @@ declare function dateAllowed(
   isDateDisabled: (date: DatePickerDate) => boolean | null,
 ): boolean;
 
+/**
+ * Check if the given date can be selected: allowed by `dateAllowed` and not reported as disabled
+ * by the date metadata controller. This is narrower than `dateAllowed`, which decides what can be
+ * focused: a disabled date is still focusable, it just cannot be selected.
+ *
+ * @returns True if the date can be selected
+ */
+declare function dateSelectable(
+  date: Date,
+  min: Date | null,
+  max: Date | null,
+  isDateDisabled: (date: DatePickerDate) => boolean | null,
+  controller?: DateMetadataController | null,
+): boolean;
+
 /**
  * Get closest date from array of dates.
  *
@@ -39,36 +121,85 @@ declare function dateAllowed(
 declare function getClosestDate(date: Date, dates: Date[]): Date;
 
 /**
- * Extracts the basic component parts of a date (day, month and year)
- * to the expected format.
+ * Get difference in months between today and given months value.
  */
-declare function extractDateParts(date: Date): { day: number; month: number; year: number };
+declare function dateAfterXMonths(months: number): Date;
 
 /**
- * Get difference in months between today and given months value.
+ * Calculate the year of the date based on the provided reference date.
+ * Gets a two-digit year and returns a full year.
+ *
+ * @param year Should be in the range of [0, 99]
+ * @returns Adjusted year value
  */
-declare function dateAfterXMonths(months: number): number;
+declare function getAdjustedYear(referenceDate: Date, year: number, month?: number, day?: number): number;
 
 /**
- * Calculate the year of the date based on the provided reference date
- * Gets a two-digit year and returns a full year.
+ * Parse date string of one of the following date formats:
+ * - ISO 8601 `"YYYY-MM-DD"`
+ * - Extended ISO 8601 with a signed year, e.g. `"+012026-MM-DD"` or `"-0001-MM-DD"`
+ *
+ * A date that does not exist, such as `"2026-02-30"`, is not parsed. Building it would carry the
+ * surplus into the next month or year and answer with a date that was never asked for.
+ *
+ * @param str Date string to parse
+ * @returns Parsed date in system timezone, or `undefined` when the string is not a date
  */
-declare function getAdjustedYear(referenceDate: Date, year: number, month?: number, day?: number): Date;
+declare function parseDate(str: string): Date | undefined;
 
 /**
  * Parse date string of one of the following date formats:
  * - ISO 8601 `"YYYY-MM-DD"`
- * - 6-digit extended ISO 8601 `"+YYYYYY-MM-DD"`, `"-YYYYYY-MM-DD"`
+ * - Extended ISO 8601 with a signed year, e.g. `"+012026-MM-DD"` or `"-0001-MM-DD"`
+ *
+ * Uses UTC date components to allow handling date instances independently of
+ * the system time-zone.
+ *
+ * A date that does not exist, such as `"2026-02-30"`, is not parsed, as in `parseDate`.
+ *
+ * @param str Date string to parse
+ * @returns Parsed date in UTC timezone, or `undefined` when the string is not a date
  */
-declare function parseDate(str: string): Date;
+declare function parseUTCDate(str: string): Date | undefined;
+
+/**
+ * Format a date instance in ISO 8601 (`"YYYY-MM-DD"`) or 6-digit extended ISO
+ * 8601 (`"+YYYYYY-MM-DD"`, `"-YYYYYY-MM-DD"`) format.
+ *
+ * @param date in system timezone
+ */
+declare function formatISODate(date: Date): string;
+
+/**
+ * Format a date instance in ISO 8601 (`"YYYY-MM-DD"`) or 6-digit extended ISO
+ * 8601 (`"+YYYYYY-MM-DD"`, `"-YYYYYY-MM-DD"`) format.
+ *
+ * Uses UTC date components to allow handling date instances independently of
+ * the system time-zone.
+ *
+ * @param date in UTC timezone
+ */
+declare function formatUTCISODate(date: Date): string;
 
 export {
+  createDate,
+  firstOfMonth,
+  lastOfMonth,
+  monthIndexOf,
+  monthIndex,
+  monthDate,
   getISOWeekNumber,
+  normalizeDate,
+  normalizeUTCDate,
   dateEquals,
+  extractDateParts,
   dateAllowed,
+  dateSelectable,
   getClosestDate,
-  extractDateParts,
   dateAfterXMonths,
   getAdjustedYear,
   parseDate,
+  parseUTCDate,
+  formatISODate,
+  formatUTCISODate,
 };

package/src/vaadin-date-picker-helper.js

@@ -4,6 +4,79 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 
+/**
+ * Create a date at midnight in local time. Unlike `new Date(year, month, day)`,
+ * this supports years below 100, which the constructor maps into the 20th
+ * century. The month is assigned before the day so that the initial day of month
+ * (1) always exists in the target month.
+ *
+ * @param {number} year
+ * @param {number} month Zero-based month, may be out of range to shift the year
+ * @param {number} day May be `0` to select the last day of the previous month
+ * @return {Date}
+ */
+export function createDate(year, month, day) {
+  const date = new Date(0, 0); // Wrong date (1900-01-01), but with midnight in local time
+  date.setFullYear(year);
+  date.setMonth(month);
+  date.setDate(day);
+  return date;
+}
+
+/**
+ * Get the first day of the month the given date is in.
+ *
+ * @param {!Date} date
+ * @return {Date}
+ */
+export function firstOfMonth(date) {
+  return createDate(date.getFullYear(), date.getMonth(), 1);
+}
+
+/**
+ * Get the last day of the month the given date is in.
+ *
+ * @param {!Date} date
+ * @return {Date}
+ */
+export function lastOfMonth(date) {
+  return createDate(date.getFullYear(), date.getMonth() + 1, 0);
+}
+
+/**
+ * Get the index of a month, counted from January of year 0. Reduces a month to a single
+ * integer, so a lookup builds no key and two months are adjacent when their indexes are.
+ *
+ * @param {number} year
+ * @param {number} month Zero-based month
+ * @return {number}
+ */
+export function monthIndexOf(year, month) {
+  return year * 12 + month;
+}
+
+/**
+ * Get the index of the month the given date is in.
+ *
+ * @param {!Date} date
+ * @return {number}
+ */
+export function monthIndex(date) {
+  return monthIndexOf(date.getFullYear(), date.getMonth());
+}
+
+/**
+ * Get the first day of the month with the given index, inverting `monthIndexOf`. Counting from
+ * January of year 0 also inverts negative indexes, since `createDate` normalizes a month outside
+ * 0-11 into the year.
+ *
+ * @param {number} index
+ * @return {Date}
+ */
+export function monthDate(index) {
+  return createDate(0, index, 1);
+}
+
 /**
  * Get ISO 8601 week number for the given date.
  *
@@ -106,6 +179,22 @@ export function dateAllowed(date, min, max, isDateDisabled) {
   return (!min || date >= min) && (!max || date <= max) && !dateIsDisabled;
 }
 
+/**
+ * Check if the given date can be selected: allowed by `dateAllowed` and not reported as disabled
+ * by the date metadata controller. This is narrower than `dateAllowed`, which decides what can be
+ * focused: a disabled date is still focusable, it just cannot be selected.
+ *
+ * @param {!Date} date The date to check
+ * @param {Date | null} min Range start
+ * @param {Date | null} max Range end
+ * @param {function(!DatePickerDate): boolean} isDateDisabled Callback to check if the date is disabled
+ * @param {DateMetadataController | null} [controller] The date metadata controller
+ * @return {boolean} True if the date can be selected
+ */
+export function dateSelectable(date, min, max, isDateDisabled, controller) {
+  return dateAllowed(date, min, max, isDateDisabled) && !controller?.isDateDisabled(date);
+}
+
 /**
  * Get closest date from array of dates.
  *
@@ -171,51 +260,66 @@ export function getAdjustedYear(referenceDate, year, month = 0, day = 1) {
   return adjustedYear;
 }
 
+const ISO_DATE = /^([-+]\d{1,6}|\d{2,4})-(\d{1,2})-(\d{1,2})$/u;
+
+// The parts of a date string in a format the parsers accept, as written.
+function parseParts(str) {
+  // Parsing with RegExp to ensure correct format
+  const parts = ISO_DATE.exec(str);
+  if (!parts) {
+    return undefined;
+  }
+
+  return { year: parseInt(parts[1], 10), month: parseInt(parts[2], 10) - 1, day: parseInt(parts[3], 10) };
+}
+
 /**
  * Parse date string of one of the following date formats:
  * - ISO 8601 `"YYYY-MM-DD"`
- * - 6-digit extended ISO 8601 `"+YYYYYY-MM-DD"`, `"-YYYYYY-MM-DD"`
+ * - Extended ISO 8601 with a signed year, e.g. `"+012026-MM-DD"` or `"-0001-MM-DD"`
+ *
+ * A date that does not exist, such as `"2026-02-30"`, is not parsed. Building it would carry the
+ * surplus into the next month or year and answer with a date that was never asked for.
+ *
  * @param {!string} str Date string to parse
  * @return {Date} Parsed date in system timezone
  */
 export function parseDate(str) {
-  // Parsing with RegExp to ensure correct format
-  const parts = /^([-+]\d{1}|\d{2,4}|[-+]\d{6})-(\d{1,2})-(\d{1,2})$/u.exec(str);
+  const parts = parseParts(str);
   if (!parts) {
     return undefined;
   }
 
-  const date = new Date(0, 0); // Wrong date (1900-01-01), but with midnight in local time
-  date.setFullYear(parseInt(parts[1], 10));
-  date.setMonth(parseInt(parts[2], 10) - 1);
-  date.setDate(parseInt(parts[3], 10));
-  return date;
+  const date = createDate(parts.year, parts.month, parts.day);
+
+  return date.getMonth() === parts.month && date.getDate() === parts.day ? date : undefined;
 }
 
 /**
  * Parse date string of one of the following date formats:
  * - ISO 8601 `"YYYY-MM-DD"`
- * - 6-digit extended ISO 8601 `"+YYYYYY-MM-DD"`, `"-YYYYYY-MM-DD"`
+ * - Extended ISO 8601 with a signed year, e.g. `"+012026-MM-DD"` or `"-0001-MM-DD"`
  *
  * Uses UTC date components to allow handling date instances independently of
  * the system time-zone.
  *
+ * A date that does not exist, such as `"2026-02-30"`, is not parsed, as in `parseDate`.
+ *
  * @param {!string} str Date string to parse
  * @return {Date} Parsed date in UTC timezone
  */
 export function parseUTCDate(str) {
-  // Parsing with RegExp to ensure correct format
-  const parts = /^([-+]\d{1}|\d{2,4}|[-+]\d{6})-(\d{1,2})-(\d{1,2})$/u.exec(str);
+  const parts = parseParts(str);
   if (!parts) {
     return undefined;
   }
 
   const date = new Date(Date.UTC(0, 0)); // Wrong date (1900-01-01), but with midnight in UTC
-  date.setUTCFullYear(parseInt(parts[1], 10));
-  date.setUTCMonth(parseInt(parts[2], 10) - 1);
-  date.setUTCDate(parseInt(parts[3], 10));
+  date.setUTCFullYear(parts.year);
+  date.setUTCMonth(parts.month);
+  date.setUTCDate(parts.day);
 
-  return date;
+  return date.getUTCMonth() === parts.month && date.getUTCDate() === parts.day ? date : undefined;
 }
 
 function formatISODateBase(dateParts) {

package/src/vaadin-date-picker-mixin.d.ts

@@ -18,34 +18,49 @@ export interface DatePickerDate {
   year: number;
 }
 
+/**
+ * A range of dates that `dateMetadataProvider` is asked about.
+ * It can span several months and always covers whole months.
+ */
 export interface DatePickerDateRange {
   /**
-   * The first date of the range (inclusive).
+   * The first date of the range (inclusive), as an ISO 8601 date.
    */
-  start: DatePickerDate;
+  start: string;
   /**
-   * The last date of the range (inclusive).
+   * The last date of the range (inclusive), as an ISO 8601 date.
    */
-  end: DatePickerDate;
+  end: string;
 }
 
 /**
- * Metadata resolved on demand for a single date by `dateMetadataProvider`. Extends
- * `DatePickerDate` with the date's metadata. Extra fields can be added and used by the
- * synchronous generators (e.g. `isDateDisabled`) as context.
+ * Metadata for a single date, returned by `dateMetadataProvider`.
  */
-export interface DatePickerDateMetadata extends DatePickerDate {
+export interface DatePickerDateMetadata {
+  /**
+   * The date the metadata applies to in ISO 8601 format.
+   */
+  date: string;
   /**
    * Whether the date cannot be selected.
    */
   disabled?: boolean;
   /**
-   * Custom part name(s) added to the date cell's `part` attribute, so a theme can style the
-   * date via `::part()`. Either a single name or several separated by spaces.
+   * Part names to add to the date, so a theme can style it with `::part()`. A single name, or
+   * several separated by spaces. Do not use built-in names like `disabled` and `selected`.
    */
   part?: string;
 }
 
+/**
+ * A function called with the range of dates the calendar is about to render, returning
+ * the metadata for the dates in that range. It can return a `Promise` to load the metadata
+ * asynchronously, and `null` or `undefined` when no date in the range has metadata.
+ */
+export type DatePickerDateMetadataProvider = (
+  range: DatePickerDateRange,
+) => DatePickerDateMetadata[] | Promise<DatePickerDateMetadata[] | null | undefined> | null | undefined;
+
 export interface DatePickerI18n {
   /**
    * An array with the full names of months starting
@@ -75,6 +90,11 @@ export interface DatePickerI18n {
    * Translation of the Cancel button text.
    */
   cancel?: string;
+  /**
+   * Accessible name of the overlay content, announced by screen readers when
+   * the overlay opens.
+   */
+  dialogAccessibleName?: string;
   /**
    * Used for adjusting the year value when parsing dates with short years.
    * The year values between 0 and 99 are evaluated and adjusted.
@@ -202,6 +222,10 @@ export declare class DatePickerMixinClass {
    *   // Translation of the Cancel button text.
    *   cancel: 'Cancel',
    *
+   *   // Accessible name of the overlay content, announced by screen readers
+   *   // when the overlay opens.
+   *   dialogAccessibleName: 'Calendar',
+   *
    *   // Used for adjusting the year value when parsing dates with short years.
    *   // The year values between 0 and 99 are evaluated and adjusted.
    *   // Example: for a referenceDate of 1970-10-30;
@@ -261,33 +285,51 @@ export declare class DatePickerMixinClass {
    * A function to be used to determine whether the user can select a given date.
    * Receives a `DatePickerDate` object of the date to be selected and should return a
    * boolean.
+   *
+   * The function is called once per date and has to answer synchronously. Use
+   * `dateMetadataProvider` when the answer has to be loaded first, or when dates also need
+   * custom part names. A date is disabled when either of the two disables it.
    */
   isDateDisabled: (date: DatePickerDate) => boolean;
 
   /**
-   * A batch function that fetches metadata for a range of dates the calendar is about to render.
-   * It receives a `DatePickerDateRange` object and returns, or resolves with, an array of
-   * `DatePickerDateMetadata` objects (a `DatePickerDate` extended with metadata such as
-   * `disabled` and custom `part` names) for the dates that have metadata within that range.
+   * A function that provides metadata for the dates the calendar is about to render: whether they
+   * are disabled, and CSS `part` names for styling from outside using the `::part()` selector.
+   * Unlike `isDateDisabled`, which is called once per date, the metadata provider is called for
+   * a range of dates at a time, and again as the calendar renders further dates.
+   *
+   * It receives a `DatePickerDateRange` and returns an array of `DatePickerDateMetadata` objects
+   * for the dates in that range that have metadata. It can return a `Promise` to load the metadata
+   * asynchronously, and `null` or `undefined` when no date in the range has metadata.
+   *
+   * The returned array has the following structure:
+   *
+   * ```js
+   * [
+   *   // The date is an ISO 8601 string.
+   *   { date: '2026-01-01', disabled: true },
+   *
+   *   // Adds a custom part name to the date.
+   *   { date: '2026-01-02', part: 'busy' },
+   * ]
+   * ```
    *
-   * Unlike `isDateDisabled`, which is called once per date, this function is called for a range
-   * of dates at a time, and again as the calendar renders further dates. The size of the range
-   * is decided by the calendar and may span multiple months. It may return a `Promise`, in which
-   * case the affected dates render in a non-selectable pending state until it resolves.
+   * A date is disabled if its metadata marks it disabled, or `isDateDisabled` returns `true`, or
+   * it is outside `min` and `max`. Disabled dates are not selectable, and typing a disabled date in
+   * the field makes it invalid. The provider does not affect which date is focused when opening the
+   * overlay. Use `initialPosition` property to provide a selectable date.
    *
-   * `disabled` from the metadata is combined with `min`, `max` and `isDateDisabled`: a date is
-   * disabled if it is out of range, or `isDateDisabled` returns `true`, or its metadata marks it
-   * disabled. `part` names are added to the date cell so a theme can style it via `::part()`.
+   * While a returned `Promise` is pending, the dates it covers are not disabled yet and render with
+   * the `loading` part. If the function throws or rejects, corresponding dates are requested again
+   * the next time the user navigates.
    *
-   * Both `disabled` and `part` are returned by this one function, rather than by separate
-   * generators, so a single backend query (for example in Flow) can answer both at once instead
-   * of being split into two passes over the same data.
+   * The provider is used for validation also when the overlay is closed. Date is considered valid
+   * while the provider is pending, and is re-validated again after the metadata is loaded.
    *
-   * Keep a stable reference to the function. Assigning a new function resets the internal cache
-   * and re-fetches every visible range. To reload after the underlying data changes while keeping
-   * the same function, call `clearCache()`.
+   * Keep a stable reference to the function: assigning a new one clears the cache and re-fetches
+   * visible range. Call `clearCache()` to re-fetch when the data behind the same function changed.
    */
-  dateMetadataProvider: (range: DatePickerDateRange) => DatePickerDateMetadata[] | Promise<DatePickerDateMetadata[]>;
+  dateMetadataProvider: DatePickerDateMetadataProvider | null | undefined;
 
   /**
    * Opens the dropdown.
@@ -300,9 +342,7 @@ export declare class DatePickerMixinClass {
   close(): void;
 
   /**
-   * Clears the cached date metadata and reloads it from `dateMetadataProvider`. Call this when the
-   * data behind the provider has changed (for example a date became booked) so the calendar
-   * reflects it, without having to replace the provider function.
+   * Clears the `dateMetadataProvider` cache and reloads the date metadata.
    */
   clearCache(): void;
 }