@aurodesignsystem/auro-library 5.12.3 → 5.13.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Semantic Release Automated Changelog
 
+# [5.13.0](https://github.com/AlaskaAirlines/auro-library/compare/v5.12.3...v5.13.0) (2026-05-14)
+
+
+### Features
+
+* add ISO date formatting support AB[#1495381](https://github.com/AlaskaAirlines/auro-library/issues/1495381) ([006947a](https://github.com/AlaskaAirlines/auro-library/commit/006947abf0736ec8efa25fe7861d99327e459a3b))
+
+
+### Performance Improvements
+
+* **dateutil:** add null check guard ([e5187f4](https://github.com/AlaskaAirlines/auro-library/commit/e5187f45a96aeec66c286ba9ca858e5bce9b6860))
+* **dateutil:** clean up some dup logics ([bbed2ee](https://github.com/AlaskaAirlines/auro-library/commit/bbed2ee4257ff1d107505158809eaa8cc3245685))
+* refactor structure and performance ([42247a0](https://github.com/AlaskaAirlines/auro-library/commit/42247a03392c80dd29ab3447bf65b73fc461ba38))
+
 ## [5.12.3](https://github.com/AlaskaAirlines/auro-library/compare/v5.12.2...v5.12.3) (2026-04-30)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aurodesignsystem/auro-library",
-  "version": "5.12.3",
+  "version": "5.13.0",
   "description": "This repository holds shared scripts, utilities, and workflows utilized across repositories along the Auro Design System.",
   "repository": {
     "type": "git",

package/scripts/runtime/Focusables/test/Focusables.test.js

@@ -1,21 +1,26 @@
 /* eslint-disable max-classes-per-file */
-import { fixture, html, expect, elementUpdated } from '@open-wc/testing';
+import { expect, fixtureSync, html } from "@open-wc/testing";
 
-import {
-  isFocusableComponent,
-  getFocusableElements
-} from '../Focusables.mjs';
+import { getFocusableElements, isFocusableComponent } from "../Focusables.mjs";
 
-describe('isFocusableComponent', () => {
-  it('returns true for enabled custom focusable components', async () => {
+describe("isFocusableComponent", () => {
+  it("returns true for enabled custom focusable components", async () => {
     for (const tag of [
-      'auro-checkbox', 'auro-radio', 'auro-dropdown', 'auro-button', 'auro-combobox',
-      'auro-input', 'auro-counter', 'auro-select', 'auro-datepicker',
-      'auro-hyperlink', 'auro-accordion'
+      "auro-checkbox",
+      "auro-radio",
+      "auro-dropdown",
+      "auro-button",
+      "auro-combobox",
+      "auro-input",
+      "auro-counter",
+      "auro-select",
+      "auro-datepicker",
+      "auro-hyperlink",
+      "auro-accordion",
     ]) {
       const el = document.createElement(tag);
-      if (tag === 'auro-hyperlink') {
-        el.setAttribute('href', '#');
+      if (tag === "auro-hyperlink") {
+        el.setAttribute("href", "#");
       }
       document.body.appendChild(el);
       expect(isFocusableComponent(el)).to.be.true;
@@ -23,16 +28,24 @@ describe('isFocusableComponent', () => {
     }
   });
 
-  it('returns false for custom components with disabled attribute', async () => {
+  it("returns false for custom components with disabled attribute", async () => {
     for (const tag of [
-      'auro-checkbox', 'auro-radio', 'auro-dropdown', 'auro-button', 'auro-combobox',
-      'auro-input', 'auro-counter', 'auro-select', 'auro-datepicker',
-      'auro-hyperlink', 'auro-accordion'
+      "auro-checkbox",
+      "auro-radio",
+      "auro-dropdown",
+      "auro-button",
+      "auro-combobox",
+      "auro-input",
+      "auro-counter",
+      "auro-select",
+      "auro-datepicker",
+      "auro-hyperlink",
+      "auro-accordion",
     ]) {
       const el = document.createElement(tag);
-      el.setAttribute('disabled', '');
-      if (tag === 'auro-hyperlink') {
-        el.setAttribute('href', '#');
+      el.setAttribute("disabled", "");
+      if (tag === "auro-hyperlink") {
+        el.setAttribute("href", "#");
       }
       document.body.appendChild(el);
       expect(isFocusableComponent(el)).to.be.false;
@@ -40,24 +53,26 @@ describe('isFocusableComponent', () => {
     }
   });
 
-  it('returns false for auro-hyperlink without href', async () => {
-    const el = document.createElement('auro-hyperlink');
+  it("returns false for auro-hyperlink without href", async () => {
+    const el = document.createElement("auro-hyperlink");
     document.body.appendChild(el);
     expect(isFocusableComponent(el)).to.be.false;
     el.remove();
   });
 
-  it('returns false for non-custom elements', async () => {
-    const el = document.createElement('div');
+  it("returns false for non-custom elements", async () => {
+    const el = document.createElement("div");
     document.body.appendChild(el);
     expect(isFocusableComponent(el)).to.be.false;
     el.remove();
   });
 });
 
-describe('getFocusableElements', () => {
-  it('finds standard focusable elements', async () => {
-    const el = await fixture(html`
+// fixtureSync is used instead of fixture to avoid requestAnimationFrame, which Chrome
+// pauses in background tabs when multiple test files run concurrently under WTR.
+describe("getFocusableElements", () => {
+  it("finds standard focusable elements", () => {
+    const el = fixtureSync(html`
       <div>
         <button id="btn"></button>
         <input id="input">
@@ -67,11 +82,17 @@ describe('getFocusableElements', () => {
       </div>
     `);
     const focusables = getFocusableElements(el);
-    expect(focusables.map(e => e.id)).to.include.members(['btn', 'input', 'link', 'ta', 'sel']);
+    expect(focusables.map((e) => e.id)).to.include.members([
+      "btn",
+      "input",
+      "link",
+      "ta",
+      "sel",
+    ]);
   });
 
-  it('skips disabled elements', async () => {
-    const el = await fixture(html`
+  it("skips disabled elements", () => {
+    const el = fixtureSync(html`
       <div>
         <button id="btn" disabled></button>
         <input id="input" disabled>
@@ -83,8 +104,8 @@ describe('getFocusableElements', () => {
     expect(focusables.length).to.equal(0);
   });
 
-  it('finds custom focusable components', async () => {
-    const el = await fixture(html`
+  it("finds custom focusable components", () => {
+    const el = fixtureSync(html`
       <div>
         <auro-checkbox id="cb"></auro-checkbox>
         <auro-hyperlink id="hl" href="#"></auro-hyperlink>
@@ -92,11 +113,11 @@ describe('getFocusableElements', () => {
       </div>
     `);
     const focusables = getFocusableElements(el);
-    expect(focusables.map(e => e.id)).to.include.members(['cb', 'hl', 'ab']);
+    expect(focusables.map((e) => e.id)).to.include.members(["cb", "hl", "ab"]);
   });
 
-  it('skips disabled custom components', async () => {
-    const el = await fixture(html`
+  it("skips disabled custom components", () => {
+    const el = fixtureSync(html`
       <div>
         <auro-checkbox id="cb" disabled></auro-checkbox>
         <auro-hyperlink id="hl" disabled href="#"></auro-hyperlink>
@@ -106,60 +127,59 @@ describe('getFocusableElements', () => {
     expect(focusables.length).to.equal(0);
   });
 
-  it('finds elements in shadow DOM', async () => {
+  it("finds elements in shadow DOM", () => {
     class ShadowEl extends HTMLElement {
       constructor() {
         super();
-        this.attachShadow({ mode: 'open' });
+        this.attachShadow({ mode: "open" });
       }
       connectedCallback() {
-        this.shadowRoot.innerHTML = `<button id="shadowBtn"></button>`;
+        const btn = document.createElement("button");
+        btn.id = "shadowBtn";
+        this.shadowRoot.appendChild(btn);
       }
     }
-    customElements.define('shadow-el', ShadowEl);
-    const el = await fixture(html`
+    customElements.define("shadow-el", ShadowEl);
+    const el = fixtureSync(html`
       <div>
         <shadow-el id="host"></shadow-el>
       </div>
     `);
-    await elementUpdated(el);
     const focusables = getFocusableElements(el);
-    // Should find the button inside shadow DOM
-    const shadowBtn = el.querySelector('shadow-el').shadowRoot.getElementById('shadowBtn');
+    const shadowBtn = el
+      .querySelector("shadow-el")
+      .shadowRoot.getElementById("shadowBtn");
     expect(focusables).to.include(shadowBtn);
   });
 
-  it('finds elements assigned to slots', async () => {
+  it("finds elements assigned to slots", () => {
     class SlotEl extends HTMLElement {
       constructor() {
         super();
-        this.attachShadow({ mode: 'open' });
+        this.attachShadow({ mode: "open" });
       }
       connectedCallback() {
-        this.shadowRoot.innerHTML = `<slot></slot>`;
+        this.shadowRoot.appendChild(document.createElement("slot"));
       }
     }
-    customElements.define('slot-el', SlotEl);
-    const el = await fixture(html`
+    customElements.define("slot-el", SlotEl);
+    const el = fixtureSync(html`
       <slot-el>
         <button id="slottedBtn"></button>
       </slot-el>
     `);
-    await elementUpdated(el);
     const focusables = getFocusableElements(el);
-    const slottedBtn = el.querySelector('#slottedBtn');
+    const slottedBtn = el.querySelector("#slottedBtn");
     expect(focusables).to.include(slottedBtn);
   });
 
-  it('does not return duplicates', async () => {
-    // This is a contrived case, but let's check that duplicates are not returned
-    const el = await fixture(html`
+  it("does not return duplicates", () => {
+    const el = fixtureSync(html`
       <div>
         <button id="btn"></button>
       </div>
     `);
     const focusables = getFocusableElements(el);
-    // Should only have one instance of the button
-    expect(focusables.filter(e => e.id === 'btn').length).to.equal(1);
+    expect(focusables.filter((e) => e.id === "btn").length).to.equal(1);
   });
-});
+});

package/scripts/runtime/dateUtilities/dateFormatter.mjs

@@ -1,104 +1,230 @@
-class DateFormatter {
-
-  constructor() {
-
-    /**
-     * @description Parses a date string into its components.
-     * @param {string} dateStr - Date string to parse.
-     * @param {string} format - Date format to parse.
-     * @returns {Object<key["month" | "day" | "year"]: number>|undefined}
-     */
-    this.parseDate = (dateStr, format = 'mm/dd/yyyy') => {
-
-      // Guard Clause: Date string is defined
-      if (!dateStr) {
-        return undefined;
-      }
-
-      // Assume the separator is a "/" a defined in our code base
-      const separator = '/';
-
-      // Get the parts of the date and format
-      const valueParts = dateStr.split(separator);
-      const formatParts = format.split(separator);
-
-      // Check if the value and format have the correct number of parts
-      if (valueParts.length !== formatParts.length) {
-        throw new Error('AuroDatepickerUtilities | parseDate: Date string and format length do not match');
-      }
-
-      // Holds the result to be returned
-      const result = formatParts.reduce((acc, part, index) => {
-        const value = valueParts[index];
-
-        if ((/m/iu).test(part)) {
-          acc.month = value;
-        } else if ((/d/iu).test(part)) {
-          acc.day = value;
-        } else if ((/y/iu).test(part)) {
-          acc.year = value;
-        }
-
-        return acc;
-      }, {});
-
-      // If we found all the parts, return the result
-      if (result.month && result.year) {
-        return result;
-      }
-
-      // Throw an error to let the dev know we were unable to parse the date string
-      throw new Error('AuroDatepickerUtilities | parseDate: Unable to parse date string');
-    };
-
-    /**
-     * 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.
-     */
-    this.getDateAsString = (date, locale = undefined) => 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 {Boolean}
-     */
-    this.toNorthAmericanFormat = (dateStr, format) => {
-
-      if (format === 'mm/dd/yyyy') {
-        return dateStr;
-      }
-
-      const parsedDate = this.parseDate(dateStr, format);
-
-      if (!parsedDate) {
-        throw new Error('AuroDatepickerUtilities | toNorthAmericanFormat: Unable to parse date string');
-      }
-
-      const { month, day, year } = parsedDate;
-
-      const dateParts = [];
-      if (month) {
-        dateParts.push(month);
-      }
-
-      if (day) {
-        dateParts.push(day);
-      }
-
-      if (year) {
-        dateParts.push(year);
-      }
-
-      return dateParts.join('/');
-    };
+/**
+ * @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}`,
+    );
   }
-};
 
-export const dateFormatter = new DateFormatter();
+  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}`);
+}
+
+export const dateFormatter = {
+  parseDate,
+  getDateParts,
+  getDateAsString,
+  toNorthAmericanFormat,
+  isValidDate,
+  toISOFormatString,
+  stringToDateInstance,
+};

package/scripts/runtime/dateUtilities/dateFormatter.test.js

@@ -0,0 +1,284 @@
+import { expect } from "@open-wc/testing";
+import { dateFormatter } from "./dateFormatter.mjs";
+
+describe("dateFormatter.parseDate", () => {
+  describe("null / undefined / empty input", () => {
+    it("returns undefined for null", () => {
+      expect(dateFormatter.parseDate(null)).to.be.undefined;
+    });
+
+    it("returns undefined for undefined", () => {
+      expect(dateFormatter.parseDate(undefined)).to.be.undefined;
+    });
+
+    it("returns undefined for empty string", () => {
+      expect(dateFormatter.parseDate("")).to.be.undefined;
+    });
+  });
+});
+
+describe("dateFormatter.toNorthAmericanFormat", () => {
+  it("returns the string unchanged for mm/dd/yyyy", () => {
+    expect(
+      dateFormatter.toNorthAmericanFormat("01/15/2024", "mm/dd/yyyy"),
+    ).to.equal("01/15/2024");
+  });
+
+  it("reorders dd/mm/yyyy to mm/dd/yyyy", () => {
+    expect(
+      dateFormatter.toNorthAmericanFormat("15/01/2024", "dd/mm/yyyy"),
+    ).to.equal("01/15/2024");
+  });
+
+  it("reorders yyyy-mm-dd to mm/dd/yyyy", () => {
+    expect(
+      dateFormatter.toNorthAmericanFormat("2024-01-15", "yyyy-mm-dd"),
+    ).to.equal("01/15/2024");
+  });
+
+  it("throws when the date string cannot be parsed", () => {
+    expect(() =>
+      dateFormatter.toNorthAmericanFormat(null, "dd/mm/yyyy"),
+    ).to.throw(Error);
+  });
+});
+
+describe("dateFormatter.stringToDateInstance", () => {
+  describe("ISO input", () => {
+    const isoCases = [
+      { input: "2024-01-15", description: "typical ISO date" },
+      { input: "1999-12-31", description: "end of year ISO date" },
+    ];
+
+    isoCases.forEach(({ input, description }) => {
+      it(`creates Date directly from ISO string for: ${description}`, () => {
+        const result = dateFormatter.stringToDateInstance(input);
+
+        expect(result).to.be.instanceOf(Date);
+        expect(result.toISOString().slice(0, 10)).to.equal(input);
+      });
+    });
+  });
+
+  describe("non-ISO input with explicit format", () => {
+    it("returns a Date using parseDate result for dd/mm/yyyy format", () => {
+      const inputStr = "15/01/2024";
+      const expectedYear = 2024;
+      const expectedMonth = 1; // January (1-based)
+      const expectedDay = 15;
+
+      const result = dateFormatter.stringToDateInstance(inputStr, "dd/mm/yyyy");
+
+      expect(result).to.be.instanceOf(Date);
+      expect(result.getFullYear()).to.equal(expectedYear);
+      expect(result.getMonth()).to.equal(expectedMonth - 1);
+      expect(result.getDate()).to.equal(expectedDay);
+    });
+  });
+
+  describe("default format behaviour", () => {
+    it("uses default format parameter when format is not provided", () => {
+      const inputStr = "2024-02-29";
+
+      const result = dateFormatter.stringToDateInstance(inputStr);
+
+      expect(result).to.be.instanceOf(Date);
+      expect(result.getFullYear()).to.equal(2024);
+      expect(result.getMonth()).to.equal(1);
+      expect(result.getDate()).to.equal(29);
+    });
+  });
+
+  describe("month adjustment", () => {
+    it("correctly adjusts month from 1-based to 0-based when creating Date", () => {
+      const inputStr = "2024-12-31";
+
+      const result = dateFormatter.stringToDateInstance(inputStr);
+
+      expect(result.getFullYear()).to.equal(2024);
+      expect(result.getMonth()).to.equal(11);
+      expect(result.getDate()).to.equal(31);
+    });
+  });
+});
+
+describe("dateFormatter.isValidDate", () => {
+  describe("valid date inputs", () => {
+    const validCases = [
+      {
+        args: ["2024-02-29"],
+        description: "valid leap day ISO (default format)",
+      },
+      {
+        args: ["1999-12-31", "yyyy-mm-dd"],
+        description: "valid ISO with explicit format",
+      },
+      {
+        args: ["12/31/1999", "mm/dd/yyyy"],
+        description: "valid mm/dd/yyyy",
+      },
+      {
+        args: ["31-01-2020", "dd-mm-yyyy"],
+        description: "valid dd-mm-yyyy",
+      },
+      {
+        args: ["01/15/01", "mm/dd/yy"],
+        description: "2-digit year below 50 normalizes to 20xx (01 → 2001)",
+      },
+      {
+        args: ["12/31/99", "mm/dd/yy"],
+        description: "2-digit year >= 50 normalizes to 19xx (99 → 1999)",
+      },
+    ];
+
+    validCases.forEach(({ args, description }) => {
+      it(`returns true for: ${description}`, () => {
+        const result = dateFormatter.isValidDate(...args);
+        expect(result, `Expected ${JSON.stringify(args)} to be a valid date`).to
+          .be.true;
+      });
+    });
+  });
+
+  describe("invalid date inputs", () => {
+    const invalidCases = [
+      {
+        args: ["02/2024", "mm/yyyy"],
+        description: "short format mm/yyyy",
+      },
+      {
+        args: ["2024/02", "yyyy/mm"],
+        description: "short format yyyy/mm",
+      },
+      {
+        args: ["2024", "yyyy"],
+        description: "short format yyyy",
+      },
+      { args: ["2024-02-30"], description: "invalid ISO day" },
+      {
+        args: ["12/31/1999", "yyyy-mm-dd"],
+        description: "non-ISO string with yyyy-mm-dd format",
+      },
+      {
+        args: ["02/30/2024", "mm/dd/yyyy"],
+        description: "invalid mm/dd/yyyy with impossible day",
+      },
+      {
+        args: [null, "mm/dd/yyyy"],
+        description: "non-string date value",
+      },
+      {
+        args: ["13/2024", "mm/yyyy"],
+        description: "invalid mm/yyyy with month out of range",
+      },
+      {
+        args: ["00/24", "mm/yy"],
+        description: "invalid mm/yy with month below range",
+      },
+      {
+        args: ["02/24", "mm/yy"],
+        description: "invalid mm/yy",
+      },
+      {
+        args: ["2024/13", "yyyy/mm"],
+        description: "invalid yyyy/mm with month out of range",
+      },
+      {
+        args: ["ab24", "yyyy"],
+        description: "invalid yyyy with non-numeric value",
+      },
+      {
+        args: ["2a", "yy"],
+        description: "invalid yy with non-numeric value",
+      },
+      {
+        args: ["24", "yy"],
+        description: "invalid yy",
+      },
+      {
+        args: ["00", "mm"],
+        description: "invalid mm below range",
+      },
+      {
+        args: ["12", "mm"],
+        description: "invalid mm",
+      },
+      {
+        args: ["00", "dd"],
+        description: "invalid dd below range",
+      },
+      {
+        args: ["31", "dd"],
+        description: "invalid dd",
+      },
+      {
+        args: ["32", "dd"],
+        description: "invalid dd above range",
+      },
+    ];
+
+    invalidCases.forEach(({ args, description }) => {
+      it(`returns false for: ${description}`, () => {
+        const result = dateFormatter.isValidDate(...args);
+        expect(result, `Expected ${JSON.stringify(args)} to be an invalid date`)
+          .to.be.false;
+      });
+    });
+  });
+});
+
+describe("dateFormatter.toISOFormatString", () => {
+  describe("valid Date inputs", () => {
+    const validCases = [
+      {
+        input: new Date("2024/01/15"),
+        expected: "2024-01-15",
+        description: "typical date",
+      },
+      {
+        input: new Date("1999/12/31"),
+        expected: "1999-12-31",
+        description: "end of year",
+      },
+      {
+        input: new Date("2024/02/29"),
+        expected: "2024-02-29",
+        description: "leap day",
+      },
+      {
+        input: new Date("2000/01/01"),
+        expected: "2000-01-01",
+        description: "first day of millennium",
+      },
+      {
+        input: new Date("2024/12/31"),
+        expected: "2024-12-31",
+        description: "last day of year",
+      },
+    ];
+
+    validCases.forEach(({ input, expected, description }) => {
+      it(`returns "${expected}" for: ${description}`, () => {
+        const result = dateFormatter.toISOFormatString(input);
+        expect(result).to.equal(expected);
+      });
+    });
+  });
+
+  describe("invalid inputs", () => {
+    const invalidCases = [
+      { input: new Date("not-a-date"), description: "invalid Date instance" },
+      { input: "2024-01-15", description: "string input" },
+      { input: null, description: "null input" },
+      { input: undefined, description: "undefined input" },
+      { input: 20240115, description: "number input" },
+      { input: {}, description: "plain object input" },
+    ];
+
+    invalidCases.forEach(({ input, description }) => {
+      it(`throws for: ${description}`, () => {
+        expect(() => dateFormatter.toISOFormatString(input)).to.throw(Error);
+      });
+    });
+  });
+});

package/scripts/runtime/dateUtilities/dateUtilities.mjs

@@ -3,12 +3,11 @@ import { AuroDateUtilitiesBase } from "./baseDateUtilities.mjs";
 import { dateFormatter } from "./dateFormatter.mjs";
 
 export class AuroDateUtilities extends AuroDateUtilitiesBase {
-
   /**
    * Returns the current century.
    * @returns {String} The current century.
    */
-  getCentury () {
+  getCentury() {
     return String(new Date().getFullYear()).slice(0, 2);
   }
 
@@ -17,14 +16,12 @@ export class AuroDateUtilities extends AuroDateUtilitiesBase {
    * @param {String} year - The year to convert to four digits.
    * @returns {String} The four digit year.
    */
-  getFourDigitYear (year) {
-
+  getFourDigitYear(year) {
     const strYear = String(year).trim();
     return strYear.length <= 2 ? this.getCentury() + strYear : strYear;
   }
 
   constructor() {
-
     super();
 
     /**
@@ -33,7 +30,8 @@ export class AuroDateUtilities extends AuroDateUtilitiesBase {
      * @param {Object} date2 - Second date to compare.
      * @returns {Boolean} Returns true if the dates match.
      */
-    this.datesMatch = (date1, date2) => new Date(date1).getTime() === new Date(date2).getTime();
+    this.datesMatch = (date1, date2) =>
+      new Date(date1).getTime() === new Date(date2).getTime();
 
     /**
      * Returns true if value passed in is a valid date.
@@ -42,54 +40,41 @@ export class AuroDateUtilities extends AuroDateUtilitiesBase {
      * @returns {Boolean}
      */
     this.validDateStr = (date, format) => {
-
       // The length we expect the date string to be
-      const dateStrLength = format.length;
+      const dateStrLength = format?.length || 0;
 
       // Guard Clause: Date and format are defined
       if (typeof date === "undefined" || typeof format === "undefined") {
-        throw new Error('AuroDatepickerUtilities | validateDateStr: Date and format are required');
+        throw new Error(
+          "AuroDatepickerUtilities | validateDateStr: Date and format are required",
+        );
       }
 
       // Guard Clause: Date should be of type string
       if (typeof date !== "string") {
-        throw new Error('AuroDatepickerUtilities | validateDateStr: Date must be a string');
+        throw new Error(
+          "AuroDatepickerUtilities | validateDateStr: Date must be a string",
+        );
       }
 
       // Guard Clause: Format should be of type string
       if (typeof format !== "string") {
-        throw new Error('AuroDatepickerUtilities | validateDateStr: Format must be a string');
+        throw new Error(
+          "AuroDatepickerUtilities | validateDateStr: Format must be a string",
+        );
       }
 
       // Guard Clause: Length is what we expect it to be
       if (date.length !== dateStrLength) {
         return false;
-      };
-
-      // Get a formatted date string and parse it
-      const dateParts = dateFormatter.parseDate(date, format);
-
-      // Guard Clause: Date parse succeeded
-      if (!dateParts) {
-        return false;
       }
 
-      // Create the expected date string based on the date parts
-      const expectedDateStr = `${dateParts.month}/${dateParts.day || "01"}/${this.getFourDigitYear(dateParts.year)}`;
-
-      // Generate a date object that we will extract a string date from to compare to the passed in date string
-      const dateObj = new Date(this.getFourDigitYear(dateParts.year), dateParts.month - 1, dateParts.day || 1);
-
-      // Get the date string of the date object we created from the string date
-      const actualDateStr = dateFormatter.getDateAsString(dateObj, "en-US");
-
-      // Guard Clause: Generated date matches date string input
-      if (expectedDateStr !== actualDateStr) {
+      // Get a formatted date string and parse and validate it
+      try {
+        return Boolean(dateFormatter.parseDate(date, format));
+      } catch (error) {
         return false;
       }
-
-      // If we passed all other checks, we can assume the date is valid
-      return true;
     };
 
     /**
@@ -99,10 +84,11 @@ export class AuroDateUtilities extends AuroDateUtilitiesBase {
      * @returns {boolean}
      */
     this.dateAndFormatMatch = (value, format) => {
-
       // Ensure we have both values we need to do the comparison
       if (!value || !format) {
-        throw new Error('AuroFormValidation | dateFormatMatch: value and format are required');
+        throw new Error(
+          "AuroFormValidation | dateFormatMatch: value and format are required",
+        );
       }
 
       // If the lengths are different, they cannot match
@@ -111,11 +97,10 @@ export class AuroDateUtilities extends AuroDateUtilitiesBase {
       }
 
       // Get the parts of the date
-      const dateParts = dateFormatter.parseDate(value, format);
+      const dateParts = dateFormatter.getDateParts(value, format);
 
       // Validator for day
       const dayValueIsValid = (day) => {
-
         // Guard clause: if there is no day in the dateParts, we can ignore this check.
         if (!dateParts.day) {
           return true;
@@ -131,7 +116,9 @@ export class AuroDateUtilities extends AuroDateUtilitiesBase {
 
         // Guard clause: ensure day is a valid integer
         if (Number.isNaN(numDay)) {
-          throw new Error('AuroDatepickerUtilities | dayValueIsValid: Unable to parse day value integer');
+          throw new Error(
+            "AuroDatepickerUtilities | dayValueIsValid: Unable to parse day value integer",
+          );
         }
 
         // Guard clause: ensure day is within the valid range
@@ -145,6 +132,10 @@ export class AuroDateUtilities extends AuroDateUtilitiesBase {
 
       // Validator for month
       const monthValueIsValid = (month) => {
+        // Guard clause: if there is no month in the dateParts, we can ignore this check.
+        if (!dateParts.month) {
+          return true;
+        }
 
         // Guard clause: ensure month exists.
         if (!month) {
@@ -156,7 +147,9 @@ export class AuroDateUtilities extends AuroDateUtilitiesBase {
 
         // Guard clause: ensure month is a valid integer
         if (Number.isNaN(numMonth)) {
-          throw new Error('AuroDatepickerUtilities | monthValueIsValid: Unable to parse month value integer');
+          throw new Error(
+            "AuroDatepickerUtilities | monthValueIsValid: Unable to parse month value integer",
+          );
         }
 
         // Guard clause: ensure month is within the valid range
@@ -170,6 +163,10 @@ export class AuroDateUtilities extends AuroDateUtilitiesBase {
 
       // Validator for year
       const yearIsValid = (_year) => {
+        // Guard clause: if there is no year in the dateParts, we can ignore this check.
+        if (!dateParts.year) {
+          return true;
+        }
 
         // Guard clause: ensure year exists.
         if (!_year) {
@@ -184,7 +181,9 @@ export class AuroDateUtilities extends AuroDateUtilitiesBase {
 
         // Guard clause: ensure year is a valid integer
         if (Number.isNaN(numYear)) {
-          throw new Error('AuroDatepickerUtilities | yearValueIsValid: Unable to parse year value integer');
+          throw new Error(
+            "AuroDatepickerUtilities | yearValueIsValid: Unable to parse year value integer",
+          );
         }
 
         // Guard clause: ensure year is within the valid range
@@ -200,7 +199,7 @@ export class AuroDateUtilities extends AuroDateUtilitiesBase {
       const checks = [
         monthValueIsValid(dateParts.month),
         dayValueIsValid(dateParts.day),
-        yearIsValid(dateParts.year)
+        yearIsValid(dateParts.year),
       ];
 
       // If any of the checks failed, the date format does not match and the result is invalid

package/scripts/runtime/dateUtilities/dateUtilities.test.js

@@ -0,0 +1,80 @@
+import { expect } from "@open-wc/testing";
+import { AuroDateUtilities } from "./dateUtilities.mjs";
+
+const utils = new AuroDateUtilities();
+
+describe("AuroDateUtilities.validDateStr", () => {
+  it("throws when date is undefined", () => {
+    expect(() => utils.validDateStr(undefined, "mm/dd/yyyy")).to.throw(Error);
+  });
+
+  it("throws when format is undefined", () => {
+    expect(() => utils.validDateStr("01/15/2024", undefined)).to.throw(Error);
+  });
+
+  it("throws when date is not a string", () => {
+    expect(() => utils.validDateStr(20240115, "mm/dd/yyyy")).to.throw(Error);
+  });
+
+  it("returns false when date length does not match format length", () => {
+    expect(utils.validDateStr("01/15", "mm/dd/yyyy")).to.be.false;
+  });
+
+  it("returns true for a valid date matching its format", () => {
+    expect(utils.validDateStr("01/15/2024", "mm/dd/yyyy")).to.be.true;
+  });
+
+  it("returns false for an invalid calendar date (Feb 30)", () => {
+    expect(utils.validDateStr("02/30/2024", "mm/dd/yyyy")).to.be.false;
+  });
+});
+
+describe("AuroDateUtilities.dateAndFormatMatch", () => {
+  it("throws when value is falsy", () => {
+    expect(() => utils.dateAndFormatMatch(null, "mm/dd/yyyy")).to.throw(Error);
+  });
+
+  it("throws when format is falsy", () => {
+    expect(() => utils.dateAndFormatMatch("01/15/2024", null)).to.throw(Error);
+  });
+
+  it("returns false when value length differs from format length", () => {
+    expect(utils.dateAndFormatMatch("01/15", "mm/dd/yyyy")).to.be.false;
+  });
+
+  it("returns true for a value that matches the format", () => {
+    expect(utils.dateAndFormatMatch("01/15/2024", "mm/dd/yyyy")).to.be.true;
+  });
+
+  it("returns false when month is below range", () => {
+    expect(utils.dateAndFormatMatch("00/15/2024", "mm/dd/yyyy")).to.be.false;
+  });
+
+  it("returns false when month is above range", () => {
+    expect(utils.dateAndFormatMatch("13/15/2024", "mm/dd/yyyy")).to.be.false;
+  });
+
+  it("returns false when day is below range", () => {
+    expect(utils.dateAndFormatMatch("01/00/2024", "mm/dd/yyyy")).to.be.false;
+  });
+
+  it("returns false when day is above range", () => {
+    expect(utils.dateAndFormatMatch("01/32/2024", "mm/dd/yyyy")).to.be.false;
+  });
+
+  it("returns false when year is below range", () => {
+    expect(utils.dateAndFormatMatch("01/15/1899", "mm/dd/yyyy")).to.be.false;
+  });
+
+  it("returns false when year is above range", () => {
+    expect(utils.dateAndFormatMatch("01/15/2401", "mm/dd/yyyy")).to.be.false;
+  });
+
+  it("skips day check when format has no day component", () => {
+    expect(utils.dateAndFormatMatch("01/2024", "mm/yyyy")).to.be.true;
+  });
+
+  it("skips month check when format has no month component", () => {
+    expect(utils.dateAndFormatMatch("15/2024", "dd/yyyy")).to.be.true;
+  });
+});