@genesislcap/foundation-ui 14.448.0 → 14.449.0

package/dist/dts/date-picker/date-picker.d.ts

@@ -22,6 +22,14 @@ export declare class DatePicker extends FoundationElement {
     format: string;
     formatChanged(oldValue: string, newValue: string): void;
     lang: string;
+    langChanged(): void;
+    /**
+     * @attr use-locale-format - when true, `format` is set from dayjs locale `L`.
+     * Uses the browser locale (`navigator.language`) unless `lang` is set on the element.
+     * @default false
+     */
+    useLocaleFormat: boolean;
+    useLocaleFormatChanged(oldValue: boolean, newValue: boolean): void;
     visible: boolean;
     /**
      * @attr inline-calendar - display the calendar beneath the value display.
@@ -68,6 +76,19 @@ export declare class DatePicker extends FoundationElement {
      * ```
      */
     label: string;
+    /**
+     * @attr allow-empty - when true, no initial date is selected; the input shows a placeholder until the user picks a date.
+     * @default false
+     * @example
+     * ```html
+     * <rapid-date-picker allow-empty format="DD/MM/YYYY"></rapid-date-picker>
+     * ```
+     */
+    allowEmpty: boolean;
+    /**
+     * @attr placeholder - hint shown when allow-empty is set and no date is selected. Defaults from `format` (e.g. DD/MM/YYYY → dd/mm/yyyy).
+     */
+    placeholder: string;
     /**
      * @attr value - sets the value of the date picker
      * @example
@@ -116,8 +137,50 @@ export declare class DatePicker extends FoundationElement {
     disabledDaysOfWeek: number[];
     calendar: Calendar;
     substringNumber: number;
+    private suppressValueChanged;
+    private cachedFormat;
+    disconnectedCallback(): void;
     connectedCallback(): void;
+    /**
+     * Clears the selected date (only when `allow-empty` is enabled).
+     * @public
+     */
+    clear(): void;
+    /**
+     * @internal
+     */
+    get inputValue(): string;
+    /**
+     * @internal
+     */
+    get inputPlaceholder(): string;
+    /**
+     * Locale for display format and calendar labels: explicit `lang`, or browser when using locale format.
+     * @internal
+     */
+    private get effectiveLang();
+    private applyLocaleFormat;
+    private cacheUserFormat;
+    private restoreUserFormat;
+    private applyEffectiveLangChange;
+    private syncValueAttribute;
+    private initializeEmpty;
+    private initializeWithDefaultDate;
+    private resetToDefaultDate;
+    private applyValue;
+    /**
+     * Resets to the empty/cleared view.
+     * @param emitEvent - emit `value-changed` for user-driven clears (public `clear()`); skip for
+     *   host-driven attribute writes since the host is the source of the change.
+     */
+    private clearToEmpty;
     updateHeaderText(): void;
+    protected visibleChanged(_prev: boolean, next: boolean): void;
+    private clickOutside;
+    private keydownOutside;
+    private handleKeydownOutside;
+    private handleClickOutside;
+    private closeCalendar;
     toggleCalendar(): void;
     toggleVisibility(): void;
     isSelectedDate(date: any): boolean;

package/dist/dts/date-picker/date-picker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"date-picker.d.ts","sourceRoot":"","sources":["../../../src/date-picker/date-picker.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAM/D,OAAO,QAAQ,MAAM,YAAY,CAAC;AAGlC,OAAO,GAAG,MAAM,OAAO,CAAC;AAGxB,eAAO,MAAM,iCAAiC,EAAE,cAA0B,CAAC;AAE3E,eAAO,MAAM,uBAAuB,IAAK,CAAC;AAE1C;;;;GAIG;AACH,qBAAa,UAAW,SAAQ,iBAAiB;IAC/C;;;;;;;;;OASG;IACG,MAAM,SAAgB;IAC5B,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAK1C,IAAI,SAAW;IACf,OAAO,UAAS;IAEtB;;;;;;;;;OASG;IACsD,cAAc,EAAE,OAAO,CAAC;IACjF,qBAAqB;IAIrB;;;;;;;;;OASG;IACoD,YAAY,EAAE,OAAO,CAAC;IAC7E,2BAA2B;IAI3B;;;;;;;;;OASG;IACG,QAAQ,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAY;IAE/D;;;;;;;;OAQG;IACG,KAAK,EAAE,MAAM,CAAC;IACpB;;;;;;;;OAQG;IACG,KAAK,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAU/C;;OAEG;IACS,WAAW,EAAE,GAAG,CAAC;IAC7B;;OAEG;IACS,YAAY,EAAE,MAAM,CAAC;IACjC;;OAEG;IACS,WAAW,EAAE,MAAM,CAAC;IAChC;;OAEG;IACS,uBAAuB,EAAE,MAAM,CAAC;IAC5C;;OAEG;IACS,UAAU,EAAE,MAAM,CAAC;IAE/B;;OAEG;IACS,SAAS,EAAE,GAAG,EAAE,CAAC;IAE7B;;;;;;;;;OASG;IACS,kBAAkB,EAAE,MAAM,EAAE,CAAM;IAClC,QAAQ,EAAE,QAAQ,CAAC;IAC/B,eAAe,EAAE,MAAM,CAAC;IAExB,iBAAiB;IAqBjB,gBAAgB,IAAI,IAAI;IAKxB,cAAc,IAAI,IAAI;IAUtB,gBAAgB,IAAI,IAAI;IASxB,cAAc,CAAC,IAAI,KAAA,GAAG,OAAO;IAI7B,sBAAsB,IAAI,OAAO;IASjC,SAAS,IAAI,IAAI;IAMjB,SAAS,IAAI,IAAI;IAMjB,SAAS,CAAC,GAAG,KAAA,GAAG,IAAI;IAapB,gBAAgB,IAAI,GAAG,EAAE;CAkB1B;AACD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;qBAM/B,CAAC"}
+{"version":3,"file":"date-picker.d.ts","sourceRoot":"","sources":["../../../src/date-picker/date-picker.ts"],"names":[],"mappings":"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"}

package/dist/dts/date-picker/date-picker.template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"date-picker.template.d.ts","sourceRoot":"","sources":["../../../src/date-picker/date-picker.template.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAOhD,eAAO,MAAM,qBAAqB,GAAI,QAAQ,MAAM,oEAmEnD,CAAC;AAEF,eAAO,MAAM,4BAA4B,iEAExC,CAAC"}
+{"version":3,"file":"date-picker.template.d.ts","sourceRoot":"","sources":["../../../src/date-picker/date-picker.template.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAOhD,eAAO,MAAM,qBAAqB,GAAI,QAAQ,MAAM,oEA0EnD,CAAC;AAEF,eAAO,MAAM,4BAA4B,iEAExC,CAAC"}

package/dist/dts/date-picker/date-picker.util.d.ts

@@ -0,0 +1,37 @@
+import dayjs from 'dayjs';
+import 'dayjs/locale/en-gb';
+/**
+ * Maps BCP-47 tags to dayjs locale ids (lowercase, e.g. `fr-FR` → `fr-fr`).
+ * English variants map to dayjs bundles: `en-US` → `en`, `en-GB` → `en-gb`.
+ * @public
+ */
+export declare function resolveDayjsLocale(lang: string): string;
+/**
+ * Browser BCP-47 locale (e.g. `en-GB`), or `en` when unavailable (SSR/tests).
+ * @public
+ */
+export declare function getBrowserLocale(): string;
+/**
+ * Display format from dayjs locale `L` (e.g. en / en-US → MM/DD/YYYY, en-gb → DD/MM/YYYY).
+ * Falls back to `en` when the locale is not loaded in dayjs (import the matching `dayjs/locale/*` bundle).
+ * @public
+ */
+export declare function getDisplayFormatForLang(lang?: string): string;
+/**
+ * Maps a dayjs-style display format to a lowercase placeholder hint (e.g. DD/MM/YYYY → dd/mm/yyyy).
+ * @public
+ */
+export declare function formatToPlaceholder(format: string): string;
+export declare function hasDateValue(value: string | null | undefined): boolean;
+/**
+ * Internal wire format for the date picker's `value` attribute.
+ * Display formatting is independent (see `format` / `getDisplayFormatForLang`).
+ * @public
+ */
+export declare const DATE_PICKER_VALUE_FORMAT = "MM-DD-YYYY";
+/**
+ * Strictly parses a date picker value (`displayFormat` or internal `DATE_PICKER_VALUE_FORMAT`). Returns null when invalid.
+ * @public
+ */
+export declare function parseDatePickerValue(dateString: string, displayFormat: string): dayjs.Dayjs | null;
+//# sourceMappingURL=date-picker.util.d.ts.map

package/dist/dts/date-picker/date-picker.util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"date-picker.util.d.ts","sourceRoot":"","sources":["../../../src/date-picker/date-picker.util.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAI1B,OAAO,oBAAoB,CAAC;AAM5B;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASvD;AAUD;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAKzC;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,GAAE,MAAa,GAAG,MAAM,CAUnE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAQ1D;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAEtE;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,eAAe,CAAC;AAErD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACpB,KAAK,CAAC,KAAK,GAAG,IAAI,CAWpB"}

package/dist/dts/date-picker/index.d.ts

@@ -1,4 +1,5 @@
 export * from './date-picker.styles';
 export * from './date-picker.template';
 export * from './date-picker';
+export * from './date-picker.util';
 //# sourceMappingURL=index.d.ts.map

package/dist/dts/date-picker/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/date-picker/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/date-picker/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC"}

package/dist/dts/react.d.ts

@@ -137,6 +137,15 @@ export declare const ActionsMenu: React.ForwardRefExoticComponent<
 >;
 export type ActionsMenuRef = ActionsMenuWC;
 
+export declare const AiIndicator: React.ForwardRefExoticComponent<
+  React.PropsWithChildren<
+    Omit<PublicOf<AiIndicatorWC>, 'children' | 'style'> &
+    HTMLWCProps & {
+    }
+  > & React.RefAttributes<AiIndicatorWC>
+>;
+export type AiIndicatorRef = AiIndicatorWC;
+
 export declare const AiCriteriaSearch: React.ForwardRefExoticComponent<
   React.PropsWithChildren<
     Omit<PublicOf<AiCriteriaSearchWC>, 'children' | 'style'> &
@@ -148,15 +157,6 @@ export declare const AiCriteriaSearch: React.ForwardRefExoticComponent<
 >;
 export type AiCriteriaSearchRef = AiCriteriaSearchWC;
 
-export declare const AiIndicator: React.ForwardRefExoticComponent<
-  React.PropsWithChildren<
-    Omit<PublicOf<AiIndicatorWC>, 'children' | 'style'> &
-    HTMLWCProps & {
-    }
-  > & React.RefAttributes<AiIndicatorWC>
->;
-export type AiIndicatorRef = AiIndicatorWC;
-
 export declare const Accordion: React.ForwardRefExoticComponent<
   React.PropsWithChildren<
     Omit<PublicOf<AccordionWC>, 'children' | 'style'> &

package/dist/esm/date-picker/date-picker.js

@@ -6,9 +6,11 @@ import dayjs from 'dayjs';
 import customParseFormat from 'dayjs/plugin/customParseFormat';
 import localeData from 'dayjs/plugin/localeData';
 import LocalizedFormat from 'dayjs/plugin/localizedFormat';
+import { wasClickOutsideElement } from '../utils';
 import Calendar from './calendar';
 import { foundationDatePickerStyles as styles } from './date-picker.styles';
 import { foundationDatePickerTemplate as template } from './date-picker.template';
+import { DATE_PICKER_VALUE_FORMAT, formatToPlaceholder, getBrowserLocale, getDisplayFormatForLang, hasDateValue, parseDatePickerValue, } from './date-picker.util';
 import Day from './day';
 import { getNextEnabledDay } from './day.util';
 export const foundationDatePickerShadowOptions = undefined;
@@ -31,7 +33,7 @@ export class DatePicker extends FoundationElement {
          *  </rapid-date-picker>
          * ```
          */
-        this.format = 'MM-DD-YYYY';
+        this.format = DATE_PICKER_VALUE_FORMAT;
         this.lang = 'en-US';
         this.visible = false;
         /**
@@ -56,53 +58,284 @@ export class DatePicker extends FoundationElement {
          * ```
          */
         this.disabledDaysOfWeek = [];
+        this.suppressValueChanged = false;
+        this.cachedFormat = DATE_PICKER_VALUE_FORMAT;
+        this.clickOutside = (e) => this.handleClickOutside(e);
+        this.keydownOutside = (e) => this.handleKeydownOutside(e);
     }
     formatChanged(oldValue, newValue) {
-        if (newValue && this.calendar) {
+        if (!this.useLocaleFormat && newValue) {
+            this.cacheUserFormat(newValue);
+        }
+        if (newValue && this.calendar && hasDateValue(this.value)) {
             this.formatDate = dayjs(this.currentDate.Date).format(newValue);
         }
     }
+    langChanged() {
+        this.applyEffectiveLangChange();
+    }
+    useLocaleFormatChanged(oldValue, newValue) {
+        // Pre-mount: format/useLocaleFormat may be set in any order; let connectedCallback do the
+        // initial cache so we don't snapshot the default format before the `format` attribute is parsed.
+        if (!this.calendar) {
+            return;
+        }
+        if (newValue && !oldValue) {
+            this.cacheUserFormat(this.format);
+        }
+        else if (!newValue && oldValue) {
+            this.restoreUserFormat();
+        }
+        this.applyEffectiveLangChange();
+    }
     inlineCalendarChanged() {
+        if (this.inlineCalendar) {
+            document.removeEventListener('mousedown', this.clickOutside);
+            document.removeEventListener('keydown', this.keydownOutside);
+        }
+        else if (this.visible) {
+            document.addEventListener('mousedown', this.clickOutside);
+            document.addEventListener('keydown', this.keydownOutside);
+        }
         this.toggleVisibility();
     }
     hideWeekendsCalendarChanged() {
         this.toggleVisibility();
     }
     valueChanged(oldValue, newValue) {
-        if (newValue && this.calendar) {
-            const localeFormat = dayjs().localeData().longDateFormat('L');
-            this.currentDate = new Day(dayjs(newValue, localeFormat).toDate(), this.lang);
-            this.calendar.goToDate(this.currentDate.monthNumber, this.currentDate.year);
-            this.formatDate = dayjs(this.currentDate.Date).format(this.format);
-            this.updateHeaderText();
-            this.monthList = this.getMonthDaysGrid();
+        if (this.suppressValueChanged) {
+            return;
+        }
+        if (!this.calendar) {
+            return;
+        }
+        if (!hasDateValue(newValue)) {
+            if (this.allowEmpty) {
+                this.clearToEmpty(false);
+            }
+            else {
+                this.resetToDefaultDate();
+            }
+            return;
         }
+        this.applyValue(newValue);
+    }
+    disconnectedCallback() {
+        document.removeEventListener('mousedown', this.clickOutside);
+        document.removeEventListener('keydown', this.keydownOutside);
+        super.disconnectedCallback();
     }
     connectedCallback() {
-        var _a;
         super.connectedCallback();
         dayjs.extend(customParseFormat);
         dayjs.extend(LocalizedFormat);
         dayjs.extend(localeData);
         this.substringNumber = 3;
+        if (this.useLocaleFormat) {
+            this.cacheUserFormat(this.format);
+            this.applyLocaleFormat();
+        }
         const dateString = this.value;
-        const dayjsDate = dateString ? dayjs(dateString, 'MM-DD-YYYY') : dayjs();
-        let currentDate = new Day(dayjsDate.toDate(), this.lang);
+        if (this.allowEmpty && !hasDateValue(dateString)) {
+            this.initializeEmpty();
+            return;
+        }
+        if (hasDateValue(dateString)) {
+            this.applyValue(dateString);
+            return;
+        }
+        this.initializeWithDefaultDate();
+    }
+    /**
+     * Clears the selected date (only when `allow-empty` is enabled).
+     * @public
+     */
+    clear() {
+        if (!this.allowEmpty) {
+            return;
+        }
+        this.clearToEmpty(true);
+    }
+    /**
+     * @internal
+     */
+    get inputValue() {
+        return hasDateValue(this.value) ? this.formatDate : '';
+    }
+    /**
+     * @internal
+     */
+    get inputPlaceholder() {
+        var _a;
+        if (!this.allowEmpty || hasDateValue(this.value)) {
+            return '';
+        }
+        return ((_a = this.placeholder) === null || _a === void 0 ? void 0 : _a.trim()) || formatToPlaceholder(this.format);
+    }
+    /**
+     * Locale for display format and calendar labels: explicit `lang`, or browser when using locale format.
+     * @internal
+     */
+    get effectiveLang() {
+        if (this.useLocaleFormat && !this.hasAttribute('lang')) {
+            return getBrowserLocale();
+        }
+        return this.lang;
+    }
+    applyLocaleFormat() {
+        this.format = getDisplayFormatForLang(this.effectiveLang);
+    }
+    cacheUserFormat(format) {
+        const trimmed = format === null || format === void 0 ? void 0 : format.trim();
+        if (trimmed) {
+            this.cachedFormat = trimmed;
+        }
+    }
+    restoreUserFormat() {
+        this.format = this.cachedFormat;
+    }
+    applyEffectiveLangChange() {
+        var _a, _b;
+        if (!this.calendar) {
+            return;
+        }
+        if (this.useLocaleFormat) {
+            this.applyLocaleFormat();
+        }
+        const viewYear = this.calendar.year;
+        const viewMonth = this.calendar.month.number;
+        const selectedDate = (_b = (_a = this.currentDate) === null || _a === void 0 ? void 0 : _a.Date) !== null && _b !== void 0 ? _b : dayjs().toDate();
+        this.currentDate = new Day(selectedDate, this.effectiveLang);
+        this.calendar = new Calendar(viewYear, viewMonth, this.effectiveLang);
+        if (hasDateValue(this.value)) {
+            this.formatDate = dayjs(this.currentDate.Date).format(this.format);
+        }
+        this.updateHeaderText();
+        this.monthList = this.getMonthDaysGrid();
+    }
+    syncValueAttribute(value) {
+        this.suppressValueChanged = true;
+        this.value = value;
+        this.suppressValueChanged = false;
+    }
+    initializeEmpty() {
+        const viewDate = dayjs();
+        this.currentDate = new Day(viewDate.toDate(), this.effectiveLang);
+        this.calendar = new Calendar(this.currentDate.year, this.currentDate.monthNumber, this.effectiveLang);
+        this.formatDate = '';
+        this.syncValueAttribute('');
+        this.currentMonth = this.calendar.month.name;
+        this.currentYear = this.calendar.year;
+        this.monthList = this.getMonthDaysGrid();
+    }
+    initializeWithDefaultDate() {
+        this.resetToDefaultDate(true);
+    }
+    resetToDefaultDate(createCalendar = false) {
+        var _a;
+        let currentDate = new Day(dayjs().toDate(), this.effectiveLang);
         if ((_a = this.disabledDaysOfWeek) === null || _a === void 0 ? void 0 : _a.length) {
-            currentDate = getNextEnabledDay(this.disabledDaysOfWeek, currentDate, this.lang);
+            currentDate = getNextEnabledDay(this.disabledDaysOfWeek, currentDate, this.effectiveLang);
         }
         this.currentDate = currentDate;
-        this.calendar = new Calendar(this.currentDate.year, this.currentDate.monthNumber, this.lang);
-        this.value = dayjs(this.currentDate.Date).format('MM-DD-YYYY');
+        if (createCalendar || !this.calendar) {
+            this.calendar = new Calendar(this.currentDate.year, this.currentDate.monthNumber, this.effectiveLang);
+        }
+        else {
+            this.calendar.goToDate(this.currentDate.monthNumber, this.currentDate.year);
+        }
+        this.formatDate = dayjs(this.currentDate.Date).format(this.format);
+        this.syncValueAttribute(dayjs(this.currentDate.Date).format(DATE_PICKER_VALUE_FORMAT));
         this.currentMonth = this.calendar.month.name;
         this.currentYear = this.calendar.year;
+        this.monthList = this.getMonthDaysGrid();
+    }
+    applyValue(dateString) {
+        const parsed = parseDatePickerValue(dateString, this.format);
+        if (!parsed) {
+            if (this.allowEmpty) {
+                this.clearToEmpty(false);
+            }
+            else {
+                this.resetToDefaultDate();
+            }
+            return;
+        }
+        // Honor the host's value verbatim. Disabled-day roll-forward only applies to the
+        // default "today" fallback (see `resetToDefaultDate`); programmatic writes should not
+        // be silently shifted, and user clicks on disabled day cells are blocked in the template.
+        this.currentDate = new Day(parsed.toDate(), this.effectiveLang);
+        if (!this.calendar) {
+            this.calendar = new Calendar(this.currentDate.year, this.currentDate.monthNumber, this.effectiveLang);
+        }
+        else {
+            this.calendar.goToDate(this.currentDate.monthNumber, this.currentDate.year);
+        }
         this.formatDate = dayjs(this.currentDate.Date).format(this.format);
+        this.syncValueAttribute(dayjs(this.currentDate.Date).format(DATE_PICKER_VALUE_FORMAT));
+        this.updateHeaderText();
         this.monthList = this.getMonthDaysGrid();
     }
+    /**
+     * Resets to the empty/cleared view.
+     * @param emitEvent - emit `value-changed` for user-driven clears (public `clear()`); skip for
+     *   host-driven attribute writes since the host is the source of the change.
+     */
+    clearToEmpty(emitEvent) {
+        const viewDate = dayjs();
+        this.currentDate = new Day(viewDate.toDate(), this.effectiveLang);
+        if (this.calendar) {
+            this.calendar.goToDate(this.currentDate.monthNumber, this.currentDate.year);
+            this.updateHeaderText();
+            this.monthList = this.getMonthDaysGrid();
+        }
+        this.formatDate = '';
+        this.syncValueAttribute('');
+        if (emitEvent) {
+            this.$emit('value-changed', undefined);
+        }
+    }
     updateHeaderText() {
         this.currentMonth = this.calendar.month.name;
         this.currentYear = this.calendar.year;
     }
+    visibleChanged(_prev, next) {
+        if (this.inlineCalendar) {
+            return;
+        }
+        if (next) {
+            document.addEventListener('mousedown', this.clickOutside);
+            document.addEventListener('keydown', this.keydownOutside);
+        }
+        else {
+            document.removeEventListener('mousedown', this.clickOutside);
+            document.removeEventListener('keydown', this.keydownOutside);
+        }
+    }
+    handleKeydownOutside(event) {
+        if (this.inlineCalendar || !this.visible) {
+            return;
+        }
+        if (event.key === 'Escape') {
+            event.preventDefault();
+            this.closeCalendar();
+        }
+    }
+    handleClickOutside(event) {
+        if (this.inlineCalendar || !this.visible) {
+            return;
+        }
+        if (wasClickOutsideElement(event, this)) {
+            this.closeCalendar();
+        }
+    }
+    closeCalendar() {
+        if (!this.visible) {
+            return;
+        }
+        this.visible = false;
+        this.toggleVisibility();
+    }
     toggleCalendar() {
         this.visible = !this.visible;
         this.toggleVisibility();
@@ -115,6 +348,9 @@ export class DatePicker extends FoundationElement {
         this.calendarDropdownClasses = classNames(['visible', this.visible], this.position, ['inline', this.inlineCalendar], ['hide-weekends', this.hideWeekends]);
     }
     isSelectedDate(date) {
+        if (this.allowEmpty && !hasDateValue(this.value)) {
+            return false;
+        }
         return dayjs(date.Date).isSame(this.currentDate.Date, 'day');
     }
     isCurrentCalendarMonth() {
@@ -135,14 +371,16 @@ export class DatePicker extends FoundationElement {
         this.monthList = this.getMonthDaysGrid();
     }
     selectDay(day) {
-        if (dayjs(day.Date).isSame(this.currentDate.Date))
+        const sameDayAsCurrent = dayjs(day.Date).isSame(this.currentDate.Date, 'day');
+        if (sameDayAsCurrent && hasDateValue(this.value)) {
             return;
+        }
         this.currentDate = day;
         if (day.monthNumber !== this.calendar.month.number) {
             this.prevMonth();
         }
         this.formatDate = dayjs(this.currentDate.Date).format(this.format);
-        this.value = dayjs(day.Date).format('MM-DD-YYYY');
+        this.syncValueAttribute(dayjs(day.Date).format(DATE_PICKER_VALUE_FORMAT));
         this.$emit('value-changed', this.value);
         this.toggleCalendar();
     }
@@ -168,6 +406,9 @@ __decorate([
 __decorate([
     attr
 ], DatePicker.prototype, "lang", void 0);
+__decorate([
+    attr({ attribute: 'use-locale-format', mode: 'boolean' })
+], DatePicker.prototype, "useLocaleFormat", void 0);
 __decorate([
     attr
 ], DatePicker.prototype, "visible", void 0);
@@ -183,6 +424,12 @@ __decorate([
 __decorate([
     attr
 ], DatePicker.prototype, "label", void 0);
+__decorate([
+    attr({ attribute: 'allow-empty', mode: 'boolean' })
+], DatePicker.prototype, "allowEmpty", void 0);
+__decorate([
+    attr
+], DatePicker.prototype, "placeholder", void 0);
 __decorate([
     attr
 ], DatePicker.prototype, "value", void 0);

package/dist/esm/date-picker/date-picker.template.js

@@ -5,7 +5,15 @@ const SUNDAY_INDEX = 1;
 const SATURDAY_INDEX = 7;
 const WEEKEND_DAY_INDICES = [SUNDAY_INDEX, SATURDAY_INDEX];
 export const getPrefixedDatePicker = (prefix) => html `
-  <${prefix}-text-field data-test-id="date-picker" readonly :value="${(x) => x.formatDate}" part="date-toggle" class="date-toggle" @click="${(x) => x.toggleCalendar()}">
+  <${prefix}-text-field
+    data-test-id="date-picker"
+    readonly
+    :value="${(x) => x.inputValue}"
+    placeholder="${(x) => x.inputPlaceholder}"
+    part="date-toggle"
+    class="date-toggle"
+    @click="${(x) => x.toggleCalendar()}"
+  >
     ${(x) => x.label}
     <div class="input-icon-container" part="input-icon-container" slot="end"><${prefix}-icon variant="regular" name="calendar-alt" size="sm"></${prefix}-icon></div>
   </${prefix}-text-field>

package/dist/esm/date-picker/date-picker.util.js

@@ -0,0 +1,92 @@
+import dayjs from 'dayjs';
+import customParseFormat from 'dayjs/plugin/customParseFormat';
+import localeData from 'dayjs/plugin/localeData';
+import LocalizedFormat from 'dayjs/plugin/localizedFormat';
+import 'dayjs/locale/en-gb';
+dayjs.extend(customParseFormat);
+dayjs.extend(localeData);
+dayjs.extend(LocalizedFormat);
+/**
+ * Maps BCP-47 tags to dayjs locale ids (lowercase, e.g. `fr-FR` → `fr-fr`).
+ * English variants map to dayjs bundles: `en-US` → `en`, `en-GB` → `en-gb`.
+ * @public
+ */
+export function resolveDayjsLocale(lang) {
+    const normalized = ((lang === null || lang === void 0 ? void 0 : lang.trim()) || 'en').toLowerCase().replace(/_/g, '-');
+    if (normalized === 'en-us' || normalized === 'en') {
+        return 'en';
+    }
+    if (normalized === 'en-gb') {
+        return 'en-gb';
+    }
+    return normalized;
+}
+function dayjsLocaleWasApplied(requested, applied) {
+    if (requested === applied) {
+        return true;
+    }
+    const language = requested.split('-')[0];
+    return applied === language;
+}
+/**
+ * Browser BCP-47 locale (e.g. `en-GB`), or `en` when unavailable (SSR/tests).
+ * @public
+ */
+export function getBrowserLocale() {
+    if (typeof navigator !== 'undefined' && navigator.language) {
+        return navigator.language;
+    }
+    return 'en';
+}
+/**
+ * Display format from dayjs locale `L` (e.g. en / en-US → MM/DD/YYYY, en-gb → DD/MM/YYYY).
+ * Falls back to `en` when the locale is not loaded in dayjs (import the matching `dayjs/locale/*` bundle).
+ * @public
+ */
+export function getDisplayFormatForLang(lang = 'en') {
+    const locale = resolveDayjsLocale(lang);
+    const instance = dayjs().locale(locale);
+    const appliedLocale = instance.locale();
+    if (!dayjsLocaleWasApplied(locale, appliedLocale)) {
+        return dayjs().locale('en').localeData().longDateFormat('L') || 'MM/DD/YYYY';
+    }
+    return instance.localeData().longDateFormat('L') || 'MM/DD/YYYY';
+}
+/**
+ * Maps a dayjs-style display format to a lowercase placeholder hint (e.g. DD/MM/YYYY → dd/mm/yyyy).
+ * @public
+ */
+export function formatToPlaceholder(format) {
+    return format
+        .replace(/YYYY/g, 'yyyy')
+        .replace(/YY(?!Y)/g, 'yy')
+        .replace(/DD/g, 'dd')
+        .replace(/D(?!D)/g, 'd')
+        .replace(/MM/g, 'mm')
+        .replace(/M(?!M)/g, 'm');
+}
+export function hasDateValue(value) {
+    return value !== null && value !== undefined && String(value).trim() !== '';
+}
+/**
+ * Internal wire format for the date picker's `value` attribute.
+ * Display formatting is independent (see `format` / `getDisplayFormatForLang`).
+ * @public
+ */
+export const DATE_PICKER_VALUE_FORMAT = 'MM-DD-YYYY';
+/**
+ * Strictly parses a date picker value (`displayFormat` or internal `DATE_PICKER_VALUE_FORMAT`). Returns null when invalid.
+ * @public
+ */
+export function parseDatePickerValue(dateString, displayFormat) {
+    const trimmed = String(dateString).trim();
+    const display = dayjs(trimmed, displayFormat, true);
+    if (display.isValid()) {
+        return display;
+    }
+    const internal = dayjs(trimmed, DATE_PICKER_VALUE_FORMAT, true);
+    if (internal.isValid()) {
+        return internal;
+    }
+    return null;
+}

package/dist/esm/date-picker/index.js

@@ -1,3 +1,4 @@
 export * from './date-picker.styles';
 export * from './date-picker.template';
 export * from './date-picker';
+export * from './date-picker.util';