@vaadin/date-picker 25.3.0-alpha13 → 25.3.0-alpha14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/date-picker",
-  "version": "25.3.0-alpha13",
+  "version": "25.3.0-alpha14",
   "publishConfig": {
     "access": "public"
   },
@@ -35,21 +35,21 @@
   ],
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
-    "@vaadin/a11y-base": "25.3.0-alpha13",
-    "@vaadin/button": "25.3.0-alpha13",
-    "@vaadin/component-base": "25.3.0-alpha13",
-    "@vaadin/field-base": "25.3.0-alpha13",
-    "@vaadin/input-container": "25.3.0-alpha13",
-    "@vaadin/overlay": "25.3.0-alpha13",
-    "@vaadin/vaadin-themable-mixin": "25.3.0-alpha13",
+    "@vaadin/a11y-base": "25.3.0-alpha14",
+    "@vaadin/button": "25.3.0-alpha14",
+    "@vaadin/component-base": "25.3.0-alpha14",
+    "@vaadin/field-base": "25.3.0-alpha14",
+    "@vaadin/input-container": "25.3.0-alpha14",
+    "@vaadin/overlay": "25.3.0-alpha14",
+    "@vaadin/vaadin-themable-mixin": "25.3.0-alpha14",
     "lit": "^3.0.0"
   },
   "devDependencies": {
-    "@vaadin/aura": "25.3.0-alpha13",
-    "@vaadin/chai-plugins": "25.3.0-alpha13",
-    "@vaadin/test-runner-commands": "25.3.0-alpha13",
+    "@vaadin/aura": "25.3.0-alpha14",
+    "@vaadin/chai-plugins": "25.3.0-alpha14",
+    "@vaadin/test-runner-commands": "25.3.0-alpha14",
     "@vaadin/testing-helpers": "^2.0.0",
-    "@vaadin/vaadin-lumo-styles": "25.3.0-alpha13",
+    "@vaadin/vaadin-lumo-styles": "25.3.0-alpha14",
     "sinon": "^22.0.0"
   },
   "customElements": "custom-elements.json",
@@ -57,5 +57,5 @@
     "web-types.json",
     "web-types.lit.json"
   ],
-  "gitHead": "e23e44d29e6bc1e47245d5e2cc0e4b022ec61818"
+  "gitHead": "10a01ae7a1e278af50eda7255dbb68dafc0e4caf"
 }

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

@@ -6,19 +6,85 @@
 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.
@@ -55,37 +121,85 @@ declare function dateSelectable(
 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 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 parseDate(str: string): Date;
+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/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/date-picker",
-  "version": "25.3.0-alpha13",
+  "version": "25.3.0-alpha14",
   "description-markup": "markdown",
   "contributions": {
     "html": {

package/web-types.lit.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/date-picker",
-  "version": "25.3.0-alpha13",
+  "version": "25.3.0-alpha14",
   "description-markup": "markdown",
   "framework": "lit",
   "framework-config": {