@aurodesignsystem-dev/auro-formkit 0.0.0-pr1483.0 → 0.0.0-pr1483.10

package/components/counter/dist/registered.js

@@ -258,237 +258,6 @@ let p$2 = class p{registerComponent(t,a){customElements.get(t)||customElements.d
 
 var iconVersion$1 = '9.1.2';
 
-/**
- * @description Splits a date string into its parts according to the provided format. Does NOT validate that the result is a real calendar date — use `parseDate` when validation is required.
- * @param {string} dateStr - Date string to parse.
- * @param {string} format - Date format to parse.
- * @returns {{ month?: string, day?: string, year?: string }|undefined}
- */
-function getDateParts(dateStr, format) {
-  if (!dateStr) {
-    return undefined;
-  }
-
-  const formatSeparatorMatch = format.match(/[/.-]/);
-  let valueParts;
-  let formatParts;
-
-  if (formatSeparatorMatch) {
-    const separator = formatSeparatorMatch[0];
-    valueParts = dateStr.split(separator);
-    formatParts = format.split(separator);
-  } else {
-    if (dateStr.match(/[/.-]/)) {
-      throw new Error(
-        "AuroDatepickerUtilities | parseDate: Date string has no separators",
-      );
-    }
-
-    if (dateStr.length !== format.length) {
-      throw new Error(
-        "AuroDatepickerUtilities | parseDate: Date string and format length do not match",
-      );
-    }
-
-    valueParts = [dateStr];
-    formatParts = [format];
-  }
-
-  if (valueParts.length !== formatParts.length) {
-    throw new Error(
-      `AuroDatepickerUtilities | parseDate: Date string and format do not match : ${dateStr} vs ${format}`,
-    );
-  }
-
-  const result = formatParts.reduce((acc, part, index) => {
-    const value = valueParts[index];
-
-    if (/m/iu.test(part) && part.length === value.length) {
-      acc.month = value;
-    } else if (/d/iu.test(part) && part.length === value.length) {
-      acc.day = value;
-    } else if (/y/iu.test(part) && part.length === value.length) {
-      acc.year = value;
-    }
-
-    return acc;
-  }, {});
-
-  if (!result.month && !result.day && !result.year) {
-    throw new Error(
-      "AuroDatepickerUtilities | parseDate: Unable to parse date string",
-    );
-  }
-
-  return result;
-}
-
-function isCalendarDate(year, month, day) {
-  let yearNumber = Number(year);
-  const monthNumber = Number(month);
-  const dayNumber = Number(day);
-
-  if (
-    !Number.isInteger(yearNumber) ||
-    !Number.isInteger(monthNumber) ||
-    !Number.isInteger(dayNumber)
-  ) {
-    return false;
-  }
-
-  // Handle 2-digit years by converting them to 4-digit years based on a cutoff. This allows for parsing of 2-digit year formats while still validating the resulting date.
-  if (yearNumber < 100 && yearNumber >= 50) {
-    yearNumber += 1900;
-  } else if (yearNumber < 50) {
-    yearNumber += 2000;
-  }
-
-  const stringified = `${String(yearNumber).padStart(4, "0")}-${String(monthNumber).padStart(2, "0")}-${String(dayNumber).padStart(2, "0")}`;
-  const date = new Date(stringified.replace(/[.-]/g, "/"));
-
-  return (
-    !Number.isNaN(date.getTime()) && toISOFormatString(date) === stringified
-  );
-}
-
-/**
- * @description Parses a date string into its components and validates that the result is a real calendar date. Use `getDateParts` instead when raw splitting without validation is needed (e.g. for in-progress input).
- *
- * Partial formats are supported: components absent from `format` default to `year → "0"`,
- * `month → "01"`, `day → "01"` for calendar validation only. The returned object contains
- * only the fields actually present in the format string — missing fields are never injected.
- * @param {string} dateStr - Date string to parse.
- * @param {string} format - Date format to parse.
- * @returns {{ month?: string, day?: string, year?: string }|undefined}
- * @throws {Error} Throws when the parsed result does not represent a valid calendar date.
- */
-function parseDate(dateStr, format = "mm/dd/yyyy") {
-  if (!dateStr || !format) {
-    return undefined;
-  }
-  const result = getDateParts(dateStr.trim(), format);
-
-  if (!result) {
-    return undefined;
-  }
-
-  const lowerFormat = format.toLowerCase();
-  const year = lowerFormat.includes("yy") ? result.year : "0";
-  const month = lowerFormat.includes("mm") ? result.month : "01";
-  const day = lowerFormat.includes("dd") ? result.day : "01";
-
-  if (isCalendarDate(year, month, day)) {
-    return result;
-  }
-
-  throw new Error(
-    `AuroDatepickerUtilities | parseDate: Date string is not a valid date ${JSON.stringify(result)} with format ${format}`,
-  );
-}
-
-/**
- * Convert a date object to string format.
- * @param {Object} date - Date to convert to string.
- * @param {String} locale - Optional locale to use for the date string. Defaults to user's locale.
- * @returns {String} Returns the date as a string.
- */
-function getDateAsString(date, locale = undefined) {
-  return date.toLocaleDateString(locale, {
-    year: "numeric",
-    month: "2-digit",
-    day: "2-digit",
-  });
-}
-
-/**
- * Converts a date string to a North American date format.
- * @param {String} dateStr - Date to validate.
- * @param {String} format - Date format to validate against.
- * @returns {String}
- */
-function toNorthAmericanFormat(dateStr, format) {
-  if (format === "mm/dd/yyyy") {
-    return dateStr;
-  }
-
-  const parsedDate = parseDate(dateStr, format);
-
-  if (!parsedDate) {
-    throw new Error(
-      "AuroDatepickerUtilities | toNorthAmericanFormat: Unable to parse date string",
-    );
-  }
-
-  const { month, day, year } = parsedDate;
-
-  return [month, day, year].filter(Boolean).join("/");
-}
-
-/**
- * Validates that a date string matches the provided format and represents a real calendar date.
- *
- * @param {string} dateStr - Date string to validate.
- * @param {string} [format="yyyy-mm-dd"] - Format of the date string.
- * @returns {boolean} True when the date string is valid for the provided format, otherwise false.
- */
-function isValidDate(dateStr, format = "yyyy-mm-dd") {
-  try {
-    if (typeof dateStr !== "string" || !dateStr || format?.length < 8) {
-      return false;
-    }
-
-    if (parseDate(dateStr, format)) {
-      return true;
-    }
-  } catch (error) {
-    return false;
-  }
-  return false;
-}
-
-/**
- * Converts a JavaScript Date instance to a simple ISO-like date string. This returns only the calendar date portion without any time or timezone information.
- *
- * @param {Date} date - Date instance to convert to an ISO-like string.
- * @returns {string} A string in the format "yyyy-mm-dd" representing the provided date.
- * @throws {Error} Throws an error when the input is not a valid Date instance.
- */
-function toISOFormatString(date) {
-  if (!(date instanceof Date) || Number.isNaN(date.getTime())) {
-    throw new Error(
-      "AuroDatepickerUtilities | toISOFormatString: Input must be a valid Date instance",
-    );
-  }
-  return `${String(date.getFullYear()).padStart(4, "0")}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
-}
-
-/**
- * Converts a date string into a JavaScript Date instance. This method supports ISO formatted strings and other formats that can be parsed by the formatter.
- *
- * @param {String} dateStr - Date string to convert into a Date object.
- * @param {String} format - Date format used to parse the string when it is not in ISO format.
- * @returns {Date|null} Returns a Date instance for valid input or null for non-string input.
- * @throws {Error} Throws when parsing fails for non-ISO string input.
- */
-function stringToDateInstance(dateStr, format = "yyyy-mm-dd") {
-  if (typeof dateStr !== "string") {
-    return null;
-  }
-
-  const { month, day, year } = parseDate(dateStr, format);
-  return new Date(`${year}/${month}/${day}`);
-}
-
-const dateFormatter = {
-  parseDate,
-  getDateParts,
-  getDateAsString,
-  toNorthAmericanFormat,
-  isValidDate,
-  toISOFormatString,
-  stringToDateInstance,
-};
-
 // Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.
 
@@ -710,7 +479,7 @@ class AuroFormValidation {
         }
 
         // Validate that the date passed was the correct format and is a valid date
-        if (elem.value && !dateFormatter.isValidDate(elem.inputElement.value, elem.format)) {
+        if (elem.value && !elem.valueObject) {
           elem.validity = 'patternMismatch';
           elem.errorMessage = elem.setCustomValidityPatternMismatch || elem.setCustomValidity || 'Invalid Date Format Entered';
           return;
@@ -1280,7 +1049,7 @@ class AuroHelpText extends LitElement {
   }
 }
 
-var formkitVersion = '202605271728';
+var formkitVersion = '202606051610';
 
 // Copyright (c) 2026 Alaska Airlines. All rights reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.

package/components/datepicker/demo/api.md

@@ -7,57 +7,58 @@ The `auro-datepicker` component provides users with a way to select a date or da
 
 ## Properties
 
-| Property                          | Attribute                         | Modifiers | Type                                             | Default                                          | Description                                      |
-|-----------------------------------|-----------------------------------|-----------|--------------------------------------------------|--------------------------------------------------|--------------------------------------------------|
-| `appearance`                      | `appearance`                      |           | `string`                                         | "'default'"                                      | Defines whether the component will be on lighter or darker backgrounds. |
-| `autoPlacement`                   | `autoPlacement`                   |           | `boolean`                                        | "false"                                          | If declared, bib's position will be automatically calculated where to appear. |
-| `calendarEndDate`                 | `calendarEndDate`                 |           | `string`                                         | "undefined"                                      | The last date that may be displayed in the calendar. |
-| `calendarEndDateObject`           |                                   | readonly  | `Date \| undefined`                              |                                                  |                                                  |
-| `calendarFocusDate`               | `calendarFocusDate`               |           | `string`                                         | "value"                                          | The date that will first be visually rendered to the user in the calendar. |
-| `calendarFocusDateObject`         |                                   | readonly  | `Date \| undefined`                              |                                                  |                                                  |
-| `calendarStartDate`               | `calendarStartDate`               |           | `string`                                         | "undefined"                                      | The first date that may be displayed in the calendar. |
-| `calendarStartDateObject`         |                                   | readonly  | `Date \| undefined`                              |                                                  |                                                  |
-| `centralDate`                     | `centralDate`                     |           | `string`                                         |                                                  | The date that determines the currently visible month. |
-| `centralDateObject`               |                                   | readonly  | `Date \| undefined`                              |                                                  |                                                  |
-| `disabled`                        | `disabled`                        |           | `boolean`                                        | false                                            | If set, disables the datepicker.                 |
-| `dvInputOnly`                     | `dvInputOnly`                     |           | `boolean`                                        | false                                            | If defined, the display value slot content will only mask the HTML5 input element. The input's label will not be masked. |
-| `error`                           | `error`                           |           | `string`                                         |                                                  | When defined, sets persistent validity to `customError` and sets the validation message to the attribute value. |
-| `format`                          | `format`                          |           | `string`                                         | "mm/dd/yyyy"                                     | Specifies the date format. The default is `mm/dd/yyyy`. |
-| `fullscreenBreakpoint`            | `fullscreenBreakpoint`            |           | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'disabled'` | "'sm'"                                           | Defines the screen size breakpoint at which the dropdown switches to fullscreen mode on mobile. `disabled` indicates a dropdown should _never_ enter fullscreen.<br /><br />When expanded, the dropdown will automatically display in fullscreen mode<br />if the screen size is equal to or smaller than the selected breakpoint. |
-| `hasError`                        |                                   | readonly  | `boolean`                                        |                                                  |                                                  |
-| `inputmode`                       | `inputmode`                       |           | `string`                                         |                                                  | Exposes inputmode attribute for input.           |
-| `largeFullscreenHeadline`         | `largeFullscreenHeadline`         |           | `boolean`                                        | false                                            | If declared, make bib.fullscreen.headline in HeadingDisplay.<br />Otherwise, Heading 600. |
-| `layout`                          | `layout`                          |           | `'classic' \| 'snowflake'`                       | "'classic'"                                      | Sets the layout of the datepicker.               |
-| `maxDate`                         | `maxDate`                         |           | `string`                                         |                                                  | Maximum date. All dates after will be disabled.  |
-| `maxDateObject`                   |                                   | readonly  | `Date \| undefined`                              |                                                  |                                                  |
-| `minDate`                         | `minDate`                         |           | `string`                                         |                                                  | Minimum date. All dates before will be disabled. |
-| `minDateObject`                   |                                   | readonly  | `Date \| undefined`                              |                                                  |                                                  |
-| `monthNames`                      | `monthNames`                      |           | `array`                                          | ["January","February","March","April","May","June","July","August","September","October","November","December"] | Names of all 12 months to render in the calendar, used for localization of date string in mobile layout. |
-| `noFlip`                          | `noFlip`                          |           | `boolean`                                        | false                                            | If declared, the bib will NOT flip to an alternate position<br />when there isn't enough space in the specified `placement`. |
-| `noValidate`                      | `noValidate`                      |           | `boolean`                                        | false                                            | If set, disables auto-validation on blur.        |
-| `offset`                          | `offset`                          |           | `number`                                         | "0"                                              | Gap between the trigger element and bib.         |
-| `onDark`                          | `onDark`                          |           | `boolean`                                        | false                                            | DEPRECATED - use `appearance="inverse"` instead. |
-| `placeholder`                     | `placeholder`                     |           | `string`                                         |                                                  | Placeholder text to display in the input(s) when no value is set. |
-| `placeholderEndDate`              | `placeholderEndDate`              |           | `string`                                         |                                                  | Optional placeholder text to display in the second input when using date range.<br />By default, datepicker will use `placeholder` for both inputs if placeholder is<br />specified, but placeholderEndDate is not. |
-| `placement`                       | `placement`                       |           | `'top' \| 'right' \| 'bottom' \| 'left' \| 'bottom-start' \| 'top-start' \| 'top-end' \| 'right-start' \| 'right-end' \| 'bottom-end' \| 'left-start' \| 'left-end'` | "'bottom-start'"                                 | Position where the bib should appear relative to the trigger. |
-| `range`                           | `range`                           |           | `boolean`                                        | false                                            | If set, turns on date range functionality in auro-calendar. |
-| `referenceDates`                  | `referenceDates`                  |           | `array`                                          |                                                  | Dates that the user should have for reference as part of their decision making when selecting a date.<br />This should be a JSON string array of ISO date strings (`YYYY-MM-DD`). |
-| `required`                        | `required`                        |           | `boolean`                                        | false                                            | Populates the `required` attribute on the input. Used for client-side validation. |
-| `setCustomValidity`               | `setCustomValidity`               |           | `string`                                         |                                                  | Sets a custom help text message to display for all validityStates. |
-| `setCustomValidityCustomError`    | `setCustomValidityCustomError`    |           | `string`                                         |                                                  | Custom help text message to display when validity = `customError`. |
-| `setCustomValidityRangeOverflow`  | `setCustomValidityRangeOverflow`  |           | `string`                                         |                                                  | Custom help text message to display when validity = `rangeOverflow`. |
-| `setCustomValidityRangeUnderflow` | `setCustomValidityRangeUnderflow` |           | `string`                                         |                                                  | Custom help text message to display when validity = `rangeUnderflow`. |
-| `setCustomValidityValueMissing`   | `setCustomValidityValueMissing`   |           | `string`                                         |                                                  | Custom help text message to display when validity = `valueMissing`. |
-| `shape`                           |                                   |           | `string`                                         | "classic"                                        |                                                  |
-| `shift`                           | `shift`                           |           | `boolean`                                        | false                                            | If declared, the dropdown will shift its position to avoid being cut off by the viewport. |
-| `size`                            |                                   |           | `string`                                         | "lg"                                             |                                                  |
-| `stacked`                         | `stacked`                         |           | `boolean`                                        | false                                            | Set true to make datepicker stacked style.       |
-| `validity`                        | `validity`                        |           | `string`                                         | "undefined"                                      | Specifies the `validityState` this element is in. |
-| `value`                           | `value`                           |           | `string`                                         | "undefined"                                      | Value selected for the datepicker.               |
-| `valueEnd`                        | `valueEnd`                        |           | `string`                                         | "undefined"                                      | Value selected for the second datepicker when using date range. |
-| `valueEndObject`                  |                                   | readonly  | `Date \| undefined`                              |                                                  |                                                  |
-| `valueObject`                     |                                   | readonly  | `Date \| undefined`                              |                                                  |                                                  |
-| `values`                          |                                   | readonly  | `string[]`                                       |                                                  | A convenience wrapper for `value` and `valueEnd`, uses the new Auro "array value pattern". |
+| Property                          | Attribute                         | Modifiers | Type                                             | Default          | Description                                      |
+|-----------------------------------|-----------------------------------|-----------|--------------------------------------------------|------------------|--------------------------------------------------|
+| `appearance`                      | `appearance`                      |           | `string`                                         | "'default'"      | Defines whether the component will be on lighter or darker backgrounds. |
+| `autoPlacement`                   | `autoPlacement`                   |           | `boolean`                                        | "false"          | If declared, bib's position will be automatically calculated where to appear. |
+| `calendarEndDate`                 | `calendarEndDate`                 |           | `string`                                         | "undefined"      | The last date that may be displayed in the calendar. |
+| `calendarEndDateObject`           |                                   | readonly  | `Date \| undefined`                              |                  |                                                  |
+| `calendarFocusDate`               | `calendarFocusDate`               |           | `string`                                         | "value"          | The date that will first be visually rendered to the user in the calendar. |
+| `calendarFocusDateObject`         |                                   | readonly  | `Date \| undefined`                              |                  |                                                  |
+| `calendarStartDate`               | `calendarStartDate`               |           | `string`                                         | "undefined"      | The first date that may be displayed in the calendar. |
+| `calendarStartDateObject`         |                                   | readonly  | `Date \| undefined`                              |                  |                                                  |
+| `centralDate`                     | `centralDate`                     |           | `string`                                         |                  | The date that determines the currently visible month. |
+| `centralDateObject`               |                                   | readonly  | `Date \| undefined`                              |                  |                                                  |
+| `disabled`                        | `disabled`                        |           | `boolean`                                        | false            | If set, disables the datepicker.                 |
+| `dvInputOnly`                     | `dvInputOnly`                     |           | `boolean`                                        | false            | If defined, the display value slot content will only mask the HTML5 input element. The input's label will not be masked. |
+| `error`                           | `error`                           |           | `string`                                         |                  | When defined, sets persistent validity to `customError` and sets the validation message to the attribute value. |
+| `format`                          | `format`                          |           | `string`                                         |                  | Specifies the date format. The default is `mm/dd/yyyy`. |
+| `fullscreenBreakpoint`            | `fullscreenBreakpoint`            |           | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'disabled'` | "'sm'"           | Defines the screen size breakpoint at which the dropdown switches to fullscreen mode on mobile. `disabled` indicates a dropdown should _never_ enter fullscreen.<br /><br />When expanded, the dropdown will automatically display in fullscreen mode<br />if the screen size is equal to or smaller than the selected breakpoint. |
+| `hasError`                        |                                   | readonly  | `boolean`                                        |                  |                                                  |
+| `inputmode`                       | `inputmode`                       |           | `string`                                         |                  | Exposes inputmode attribute for input.           |
+| `largeFullscreenHeadline`         | `largeFullscreenHeadline`         |           | `boolean`                                        | false            | If declared, make bib.fullscreen.headline in HeadingDisplay.<br />Otherwise, Heading 600. |
+| `layout`                          | `layout`                          |           | `'classic' \| 'snowflake'`                       | "'classic'"      | Sets the layout of the datepicker.               |
+| `locale`                          | `locale`                          |           | `string`                                         |                  | Defines the locale of the element. Used to derive the date format when `format` is not explicitly set. |
+| `maxDate`                         | `maxDate`                         |           | `string`                                         |                  | Maximum date. All dates after will be disabled.  |
+| `maxDateObject`                   |                                   | readonly  | `Date \| undefined`                              |                  |                                                  |
+| `minDate`                         | `minDate`                         |           | `string`                                         |                  | Minimum date. All dates before will be disabled. |
+| `minDateObject`                   |                                   | readonly  | `Date \| undefined`                              |                  |                                                  |
+| `monthNames`                      | `monthNames`                      |           | `array`                                          |                  | Names of all 12 months to render in the calendar.<br />When omitted, month names will be automatically populated from the active `locale` (falling back to `en-US`). |
+| `noFlip`                          | `noFlip`                          |           | `boolean`                                        | false            | If declared, the bib will NOT flip to an alternate position<br />when there isn't enough space in the specified `placement`. |
+| `noValidate`                      | `noValidate`                      |           | `boolean`                                        | false            | If set, disables auto-validation on blur.        |
+| `offset`                          | `offset`                          |           | `number`                                         | "0"              | Gap between the trigger element and bib.         |
+| `onDark`                          | `onDark`                          |           | `boolean`                                        | false            | DEPRECATED - use `appearance="inverse"` instead. |
+| `placeholder`                     | `placeholder`                     |           | `string`                                         |                  | Placeholder text to display in the input(s) when no value is set. |
+| `placeholderEndDate`              | `placeholderEndDate`              |           | `string`                                         |                  | Optional placeholder text to display in the second input when using date range.<br />By default, datepicker will use `placeholder` for both inputs if placeholder is<br />specified, but placeholderEndDate is not. |
+| `placement`                       | `placement`                       |           | `'top' \| 'right' \| 'bottom' \| 'left' \| 'bottom-start' \| 'top-start' \| 'top-end' \| 'right-start' \| 'right-end' \| 'bottom-end' \| 'left-start' \| 'left-end'` | "'bottom-start'" | Position where the bib should appear relative to the trigger. |
+| `range`                           | `range`                           |           | `boolean`                                        | false            | If set, turns on date range functionality in auro-calendar. |
+| `referenceDates`                  | `referenceDates`                  |           | `array`                                          |                  | Dates that the user should have for reference as part of their decision making when selecting a date.<br />This should be a JSON string array of ISO date strings (`YYYY-MM-DD`). |
+| `required`                        | `required`                        |           | `boolean`                                        | false            | Populates the `required` attribute on the input. Used for client-side validation. |
+| `setCustomValidity`               | `setCustomValidity`               |           | `string`                                         |                  | Sets a custom help text message to display for all validityStates. |
+| `setCustomValidityCustomError`    | `setCustomValidityCustomError`    |           | `string`                                         |                  | Custom help text message to display when validity = `customError`. |
+| `setCustomValidityRangeOverflow`  | `setCustomValidityRangeOverflow`  |           | `string`                                         |                  | Custom help text message to display when validity = `rangeOverflow`. |
+| `setCustomValidityRangeUnderflow` | `setCustomValidityRangeUnderflow` |           | `string`                                         |                  | Custom help text message to display when validity = `rangeUnderflow`. |
+| `setCustomValidityValueMissing`   | `setCustomValidityValueMissing`   |           | `string`                                         |                  | Custom help text message to display when validity = `valueMissing`. |
+| `shape`                           |                                   |           | `string`                                         | "classic"        |                                                  |
+| `shift`                           | `shift`                           |           | `boolean`                                        | false            | If declared, the dropdown will shift its position to avoid being cut off by the viewport. |
+| `size`                            |                                   |           | `string`                                         | "lg"             |                                                  |
+| `stacked`                         | `stacked`                         |           | `boolean`                                        | false            | Set true to make datepicker stacked style.       |
+| `validity`                        | `validity`                        |           | `string`                                         | "undefined"      | Specifies the `validityState` this element is in. |
+| `value`                           | `value`                           |           | `string`                                         | "undefined"      | Value selected for the datepicker.               |
+| `valueEnd`                        | `valueEnd`                        |           | `string`                                         | "undefined"      | Value selected for the second datepicker when using date range. |
+| `valueEndObject`                  |                                   | readonly  | `Date \| undefined`                              |                  |                                                  |
+| `valueObject`                     |                                   | readonly  | `Date \| undefined`                              |                  |                                                  |
+| `values`                          |                                   | readonly  | `string[]`                                       |                  | A convenience wrapper for `value` and `valueEnd`, uses the new Auro "array value pattern". |
 
 ## Methods
 

package/components/datepicker/demo/customize.md

@@ -19,7 +19,7 @@
 <auro-anchorlink fluid href="#customValidation" class="level2 body-xs">Custom Validation</auro-anchorlink>
 <auro-anchorlink fluid href="#noValidate" class="level2 body-xs">No Validation</auro-anchorlink>
 <auro-anchorlink fluid href="#minMaxDate" class="level2 body-xs">Min/Max Date</auro-anchorlink>
-<auro-anchorlink fluid href="#localization" class="level2 body-xs">Localization</auro-anchorlink>
+<auro-anchorlink fluid href="#regionalDate" class="level2 body-xs">Regional Date</auro-anchorlink>
 </auro-nav>
 </nav>
 <div class="mainContent">
@@ -694,27 +694,64 @@
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 <auro-header level="3" id="localization">Localization</auro-header>
-<p>Use the <code>centralDate</code>, locale, and related attributes to configure the datepicker for different regions and languages.</p>
+<auro-header level="4" id="regionalDate">Regional Date</auro-header>
+<p>When the <code>locale</code> attribute is set, the component automatically derives the correct date format for that region — no need to set <code>format</code> manually. For example, <code>locale="en-US"</code> produces <code>mm/dd/yyyy</code>, <code>locale="de-DE"</code> produces <code>dd.mm.yyyy</code>, and <code>locale="ja-JP"</code> produces <code>yyyy/mm/dd</code>.</p>
+<p>If <code>format</code> is explicitly set alongside <code>locale</code>, <code>format</code> always wins. Use this when a specific format is required regardless of region.</p>
+<p>If no <code>locale</code> attribute is set on the element, the component walks up the DOM looking for the nearest ancestor with a <code>data-locale</code> attribute and uses that value. If none is found, it defaults to <code>en-US</code>.</p>
 <div class="exampleWrapper">
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/localization.html) -->
-<!-- The below content is automatically added from ./../apiExamples/localization.html -->
-<auro-datepicker format="yyyy/mm/dd" id="localizationExample">
-<span slot="bib.fullscreen.headline">Localization Headline</span>
-<span slot="fromLabel">Choose a date</span>
-<span slot="bib.fullscreen.fromLabel">Choose a date</span>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/locale.html) -->
+<!-- The below content is automatically added from ./../apiExamples/locale.html -->
+<div data-locale="de-DE">
+<auro-datepicker locale="en-US">
+<span slot="fromLabel">en-US Date</span>
+<span slot="helpText">Help Text</span>
+</auro-datepicker>
+<auro-datepicker locale="de-DE">
+<span slot="fromLabel">de-DE Date</span>
+<span slot="helpText">Help Text</span>
+</auro-datepicker>
+<auro-datepicker locale="zh-CN">
+<span slot="fromLabel">zh-CN Date</span>
+<span slot="helpText">Help Text</span>
+</auro-datepicker>
+<auro-datepicker>
+<span slot="fromLabel">Nearest `data-locale` attribute format (`de-DE` in this case)</span>
+<span slot="helpText">Help Text</span>
+</auro-datepicker>
+<auro-datepicker locale="ja-JP" format="mm/dd/yyyy">
+<span slot="fromLabel">ja-JP locale with explicit mm/dd/yyyy format</span>
+<span slot="helpText">Help Text</span>
 </auro-datepicker>
+</div>
 <!-- AURO-GENERATED-CONTENT:END -->
 </div>
 <auro-accordion alignRight>
 <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/localization.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/localization.html -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/locale.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/locale.html -->
 
-<pre class="language-html"><code class="language-html">&lt;auro-datepicker format="yyyy/mm/dd" id="localizationExample"&gt;
-  &lt;span slot="bib.fullscreen.headline"&gt;Localization Headline&lt;/span&gt;
-  &lt;span slot="fromLabel"&gt;Choose a date&lt;/span&gt;
-  &lt;span slot="bib.fullscreen.fromLabel"&gt;Choose a date&lt;/span&gt;
-&lt;/auro-datepicker&gt;</code></pre>
+<pre class="language-html"><code class="language-html">&lt;div data-locale="de-DE"&gt;
+  &lt;auro-datepicker locale="en-US"&gt;
+    &lt;span slot="fromLabel"&gt;en-US Date&lt;/span&gt;
+    &lt;span slot="helpText"&gt;Help Text&lt;/span&gt;
+  &lt;/auro-datepicker&gt;
+  &lt;auro-datepicker locale="de-DE"&gt;
+    &lt;span slot="fromLabel"&gt;de-DE Date&lt;/span&gt;
+    &lt;span slot="helpText"&gt;Help Text&lt;/span&gt;
+  &lt;/auro-datepicker&gt;
+  &lt;auro-datepicker locale="zh-CN"&gt;
+    &lt;span slot="fromLabel"&gt;zh-CN Date&lt;/span&gt;
+    &lt;span slot="helpText"&gt;Help Text&lt;/span&gt;
+  &lt;/auro-datepicker&gt;
+  &lt;auro-datepicker&gt;
+    &lt;span slot="fromLabel"&gt;Nearest `data-locale` attribute format (`de-DE` in this case)&lt;/span&gt;
+    &lt;span slot="helpText"&gt;Help Text&lt;/span&gt;
+  &lt;/auro-datepicker&gt;
+  &lt;auro-datepicker locale="ja-JP" format="mm/dd/yyyy"&gt;
+    &lt;span slot="fromLabel"&gt;ja-JP locale with explicit mm/dd/yyyy format&lt;/span&gt;
+    &lt;span slot="helpText"&gt;Help Text&lt;/span&gt;
+  &lt;/auro-datepicker&gt;
+&lt;/div&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 </section>

package/components/datepicker/demo/index.md

@@ -10,6 +10,7 @@
 <auro-anchorlink fluid href="#selectRange" class="level2 body-xs">Select a Range</auro-anchorlink>
 <auro-anchorlink fluid href="#presetValue" class="level2 body-xs">Preset Value</auro-anchorlink>
 <auro-anchorlink fluid href="#skipSelection" class="level2 body-xs">Skip Selection</auro-anchorlink>
+<auro-anchorlink fluid href="#regionalDateFormat" class="level2 body-xs">Regional Date</auro-anchorlink>
 <auro-anchorlink fluid href="#viewportSize" class="level2 body-xs">Viewport Size</auro-anchorlink>
 </auro-nav>
 </nav>
@@ -167,6 +168,28 @@
 <auro-header level="3" id="skipSelection">Skip selection</auro-header>
 <p>The datepicker does not force the user to select a date. If no selection is made and the field is not <code>required</code>, the user can move past the datepicker without entering a value.</p>
 <p>If the field is <code>required</code>, moving focus away without selecting a date triggers validation and renders the <code>valueMissing</code> error state.</p>
+<auro-header level="3" id="regionalDateFormat">Regional date format support</auro-header>
+<p>People around the world write dates differently. A traveler in the United States expects to see <strong>12/25/2025</strong>, while someone in Germany expects <strong>25.12.2025</strong>, and someone in Japan expects <strong>2025/12/25</strong>. Showing the wrong format causes confusion and mistakes.</p>
+<p>When the datepicker knows the user's region via the <code>locale</code> attribute, it automatically displays dates in the format that looks natural to them — no extra setup required.</p>
+<div class="exampleWrapper">
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/locale-single.html) -->
+<!-- The below content is automatically added from ./../apiExamples/locale-single.html -->
+<auro-datepicker locale="zh-CN">
+<span slot="fromLabel">zh-CN Date</span>
+<span slot="helpText">Help Text</span>
+</auro-datepicker>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+<span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/locale-single.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/locale-single.html -->
+<pre class="language-html"><code class="language-html">&lt;auro-datepicker locale="zh-CN"&gt;
+  &lt;span slot="fromLabel"&gt;zh-CN Date&lt;/span&gt;
+  &lt;span slot="helpText"&gt;Help Text&lt;/span&gt;
+&lt;/auro-datepicker&gt;</code></pre>
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
 <auro-header level="3" id="viewportSize">Viewport size</auro-header>
 <p>The datepicker automatically adapts its presentation based on viewport size. On larger screens, the calendar opens in a floating popover anchored to the trigger. On smaller screens, the calendar opens in a fullscreen dialog.</p>
 <p>The breakpoint at which the fullscreen behavior activates is controlled by the <code>fullscreenBreakpoint</code> attribute. The default value is <code>sm</code>. Supported values are <code>xs</code>, <code>sm</code>, <code>md</code>, <code>lg</code>, <code>xl</code>, and <code>disabled</code>.</p>