@aurodesignsystem-dev/auro-formkit 0.0.0-pr1477.2 → 0.0.0-pr1480.0

package/custom-elements.json

@@ -128,6 +128,17 @@
               },
               "attribute": "isFullscreen",
               "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "showFooter",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "If declared, the footer slot will be rendered even when not in fullscreen mode.",
+              "attribute": "showFooter",
+              "reflects": true
             }
           ],
           "events": [
@@ -159,6 +170,14 @@
               },
               "default": "false",
               "fieldName": "large"
+            },
+            {
+              "name": "showFooter",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "If declared, the footer slot will be rendered even when not in fullscreen mode.",
+              "fieldName": "showFooter"
             }
           ],
           "superclass": {
@@ -2435,7 +2454,7 @@
           "type": {
             "text": "object"
           },
-          "default": "{ ArrowDown(component, evt, ctx) { // If the clear button has focus, let the browser handle ArrowDown normally. if (isClearBtnFocused(ctx)) { return; } // option display and navigation are prevented if there are no available options if (component.availableOptions.length > 0) { evt.preventDefault(); // navigate if bib is open otherwise open it if (component.dropdown.isPopoverVisible) { if (evt.altKey || evt.ctrlKey || evt.metaKey) { component.activateLastEnabledAvailableOption(); } else { navigateArrow(component, 'down'); } } else { component.showBib(); } } }, ArrowUp(component, evt, ctx) { // If the clear button has focus, let the browser handle ArrowUp normally. if (isClearBtnFocused(ctx)) { return; } // option display and navigation are prevented if there are no available options if (component.availableOptions.length > 0) { evt.preventDefault(); // navigate if bib is open otherwise open it if (component.dropdown.isPopoverVisible) { if (evt.altKey || evt.ctrlKey || evt.metaKey) { component.activateFirstEnabledAvailableOption(); } else { navigateArrow(component, 'up'); } } else { component.showBib(); } } }, End(component, evt, ctx) { if (ctx.isExpanded) { evt.preventDefault(); evt.stopPropagation(); component.activateLastEnabledAvailableOption(); } }, Enter(component, evt, ctx) { if (isClearBtnFocused(ctx)) { // If the clear button has focus, let the browser activate it normally. // stopPropagation prevents parent containers (e.g., forms) from treating // Enter as a submit, but we must NOT call preventDefault — that would // block the browser's built-in \"Enter activates focused button\" behavior. evt.stopPropagation(); } else if (ctx.isExpanded && component.menu.optionActive) { component.menu.makeSelection(); if (ctx.isModal) { component.setTriggerInputFocus(); } evt.preventDefault(); evt.stopPropagation(); } else { // Prevent the keypress from bubbling to parent containers (e.g., forms) // which could interpret Enter as a submit or trigger other unintended behavior. // This is safe because showBib() opens the dialog programmatically, // not via event propagation. evt.preventDefault(); evt.stopPropagation(); component.showBib(); } }, Escape(component, evt, ctx) { if (!ctx.isExpanded) { return; } // Prevent the Escape key from bubbling up and closing any parent dialogs / drawers / popups evt.stopPropagation(); if (ctx.isModal) { component.setTriggerInputFocus(); } component.hideBib(); }, Home(component, evt, ctx) { if (ctx.isExpanded) { evt.preventDefault(); evt.stopPropagation(); component.activateFirstEnabledAvailableOption(); } }, Tab(component, evt, ctx) { if (ctx.isExpanded && !isClearBtnFocused(ctx)) { // When the clear button is focused, Tab events do not bubble out of // its shadow DOM, so this handler only fires when the clear button // is NOT focused. In that case, select the active option and close. component.menu.makeSelection(); component.hideBib(); // In fullscreen modal mode, closing the dialog does not // automatically restores focus to the input. In the tab case, // Explicitly move focus to the trigger's clear button so the // user can continues tabbing through the page normally. if (ctx.isModal && !evt.shiftKey) { component.setClearBtnFocus(); } } }, }"
+          "default": "{ ArrowDown(component, evt, ctx) { // If the clear button has focus, let the browser handle ArrowDown normally. if (isClearBtnFocused(ctx)) { return; } // option display and navigation are prevented if there are no available options if (component.availableOptions.length > 0) { evt.preventDefault(); // navigate if bib is open otherwise open it if (component.dropdown.isPopoverVisible) { if (evt.altKey || evt.metaKey) { component.activateLastEnabledAvailableOption(); } else { navigateArrow(component, 'down'); } } else { component.showBib(); } } }, ArrowUp(component, evt, ctx) { // If the clear button has focus, let the browser handle ArrowUp normally. if (isClearBtnFocused(ctx)) { return; } // option display and navigation are prevented if there are no available options if (component.availableOptions.length > 0) { evt.preventDefault(); // navigate if bib is open otherwise open it if (component.dropdown.isPopoverVisible) { if (evt.altKey || evt.metaKey) { component.activateFirstEnabledAvailableOption(); } else { navigateArrow(component, 'up'); } } else { component.showBib(); } } }, End(component, evt, ctx) { if (ctx.isExpanded) { evt.preventDefault(); evt.stopPropagation(); component.activateLastEnabledAvailableOption(); } }, Enter(component, evt, ctx) { if (isClearBtnFocused(ctx)) { // If the clear button has focus, let the browser activate it normally. // stopPropagation prevents parent containers (e.g., forms) from treating // Enter as a submit, but we must NOT call preventDefault — that would // block the browser's built-in \"Enter activates focused button\" behavior. evt.stopPropagation(); } else if (ctx.isExpanded && component.menu.optionActive) { component.menu.makeSelection(); if (ctx.isModal) { component.setTriggerInputFocus(); } evt.preventDefault(); evt.stopPropagation(); } else { // Prevent the keypress from bubbling to parent containers (e.g., forms) // which could interpret Enter as a submit or trigger other unintended behavior. // This is safe because showBib() opens the dialog programmatically, // not via event propagation. evt.preventDefault(); evt.stopPropagation(); component.showBib(); } }, Escape(component, evt, ctx) { if (!ctx.isExpanded) { return; } // Prevent the Escape key from bubbling up and closing any parent dialogs / drawers / popups evt.stopPropagation(); if (ctx.isModal) { component.setTriggerInputFocus(); } component.hideBib(); }, Home(component, evt, ctx) { if (ctx.isExpanded) { evt.preventDefault(); evt.stopPropagation(); component.activateFirstEnabledAvailableOption(); } }, Tab(component, evt, ctx) { if (ctx.isExpanded && !isClearBtnFocused(ctx)) { // When the clear button is focused, Tab events do not bubble out of // its shadow DOM, so this handler only fires when the clear button // is NOT focused. In that case, select the active option and close. component.menu.makeSelection(); component.hideBib(); // In fullscreen modal mode, closing the dialog does not // automatically restores focus to the input. In the tab case, // Explicitly move focus to the trigger's clear button so the // user can continues tabbing through the page normally. if (ctx.isModal && !evt.shiftKey) { component.setClearBtnFocus(); } } }, }"
         }
       ],
       "exports": [
@@ -4179,13 +4198,6 @@
                     "text": "Number"
                   }
                 },
-                {
-                  "name": "hoveredDate",
-                  "description": "Hovered date.",
-                  "type": {
-                    "text": "Number"
-                  }
-                },
                 {
                   "name": "day",
                   "description": "An object containing the dateFrom and day of month values.",
@@ -4194,7 +4206,7 @@
                   }
                 }
               ],
-              "description": "Handles selected and hovered states of the calendar cell when the date changes.",
+              "description": "Handles selected state of the calendar cell when the selection changes.\nAlso clears any imperative range preview classes so classMap is the\nsole source of truth after a selection update.",
               "privacy": "private",
               "return": {
                 "type": {
@@ -4216,7 +4228,18 @@
             {
               "kind": "method",
               "name": "handleHover",
-              "description": "Handles user hover events and dispatches a custom event.",
+              "description": "Handles user hover events and dispatches a custom event.\nDoes NOT set any reactive properties — the range preview is handled\nimperatively by the calendar component to avoid O(N) re-renders.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "handleFocus",
+              "description": "Handles focus events on the cell button.\nDispatches a lightweight event for the calendar to handle SR\nannouncements and range preview updates without triggering\nany Lit lifecycle updates.",
               "privacy": "private",
               "return": {
                 "type": {
@@ -4224,6 +4247,51 @@
                 }
               }
             },
+            {
+              "kind": "method",
+              "name": "isOutOfRange",
+              "parameters": [
+                {
+                  "name": "day",
+                  "description": "An object containing the dateFrom and day of month values.",
+                  "type": {
+                    "text": "Object"
+                  }
+                },
+                {
+                  "name": "min",
+                  "description": "The minimum date value.",
+                  "type": {
+                    "text": "Number"
+                  }
+                },
+                {
+                  "name": "max",
+                  "description": "The maximum date value.",
+                  "type": {
+                    "text": "Number"
+                  }
+                }
+              ],
+              "description": "Checks if the current date is outside the valid min/max range.\nOut-of-range cells are not focusable and are hidden from screen readers.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Boolean"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "isBlackout",
+              "description": "Checks if the current date is a blackout date (in disabledDays but within range).\nBlackout cells are focusable but not selectable.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Boolean"
+                }
+              }
+            },
             {
               "kind": "method",
               "name": "isEnabled",
@@ -4257,7 +4325,7 @@
                   }
                 }
               ],
-              "description": "Checks if the current date is a valid date depending on the min and max values.",
+              "description": "Checks if the current date is disabled based on min/max range or the\nlegacy disabledDays timestamp list.  Sets the `disabled` attribute on the\nhost when the date falls outside the allowed range or appears in\ndisabledDays. Note: blackout dates are handled separately by `isBlackout()`.",
               "privacy": "private",
               "return": {
                 "type": {
@@ -4265,6 +4333,39 @@
                 }
               }
             },
+            {
+              "kind": "method",
+              "name": "getCellId",
+              "description": "Generates a unique cell ID in the format cell-YYYY-MM-DD.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "String"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "getAriaLabel",
+              "description": "Generates a localized aria-label for the cell button using Intl.DateTimeFormat.\nIncludes range position and blackout status.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "String"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "getRangePosition",
+              "description": "Determines the range position of this cell relative to the current selection.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "String|null"
+                }
+              }
+            },
             {
               "kind": "method",
               "name": "isDepartDate",
@@ -4462,6 +4563,98 @@
                 }
               }
             },
+            {
+              "kind": "method",
+              "name": "configurePopover",
+              "description": "Configures the popover instance with the calendar month boundary.\nCalled from firstUpdated and updated because the popover element is only\nrendered after hasPopoverContent becomes true (set by handleSlotContent).",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "updateHostAria",
+              "description": "Updates ARIA attributes on the host element so that\nariaActiveDescendantElement can expose cell info to the SR.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "focusButton",
+              "description": "Programmatically focuses the cell's interactive button element.\nUses focusVisible: true so the :focus-visible ring appears even when\nthe bib was opened via mouse click (which sets mouse input modality).",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "setActive",
+              "description": "Imperatively marks this cell as active (tabindex=\"0\") without\ntriggering a Lit re-render.",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "clearActive",
+              "description": "Imperatively marks this cell as inactive (tabindex=\"-1\") without\ntriggering a Lit re-render.",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "updateRangePreviewClasses",
+              "parameters": [
+                {
+                  "name": "hoveredDate",
+                  "description": "Unix timestamp of the currently hovered/focused date.",
+                  "type": {
+                    "text": "Number"
+                  }
+                },
+                {
+                  "name": "dateFrom",
+                  "description": "Unix timestamp of the selected departure date.",
+                  "type": {
+                    "text": "Number"
+                  }
+                }
+              ],
+              "description": "Updates range preview classes imperatively (no Lit re-render).\nCalled by the calendar component when the hovered date changes\nduring range selection (dateFrom set, dateTo not yet set).",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "clearRangePreviewClasses",
+              "description": "Clears all imperative range preview classes from the cell button.\nCalled when a selection occurs so classMap becomes the sole source of truth.",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "renderCellButton"
+            },
             {
               "kind": "field",
               "name": "day",
@@ -4482,16 +4675,6 @@
               "default": "false",
               "attribute": "selected"
             },
-            {
-              "kind": "field",
-              "name": "hovered",
-              "privacy": "public",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "attribute": "hovered"
-            },
             {
               "kind": "field",
               "name": "dateTo",
@@ -4563,16 +4746,6 @@
               "default": "[]",
               "attribute": "disabledDays"
             },
-            {
-              "kind": "field",
-              "name": "hoveredDate",
-              "privacy": "public",
-              "type": {
-                "text": "null"
-              },
-              "default": "null",
-              "attribute": "hoveredDate"
-            },
             {
               "kind": "field",
               "name": "isCurrentDate",
@@ -4611,6 +4784,24 @@
               "default": "false",
               "attribute": "renderForDateSlot"
             },
+            {
+              "kind": "field",
+              "name": "active",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false"
+            },
+            {
+              "kind": "field",
+              "name": "hasPopoverContent",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "attribute": "hasPopoverContent"
+            },
             {
               "kind": "field",
               "name": "runtimeUtils",
@@ -4622,11 +4813,23 @@
             }
           ],
           "events": [
+            {
+              "name": "calendar-cell-activate",
+              "type": {
+                "text": "CustomEvent"
+              }
+            },
             {
               "name": "date-is-hovered",
               "type": {
                 "text": "CustomEvent"
               }
+            },
+            {
+              "name": "calendar-cell-focused",
+              "type": {
+                "text": "CustomEvent"
+              }
             }
           ],
           "attributes": [
@@ -4646,14 +4849,6 @@
               "default": "false",
               "fieldName": "selected"
             },
-            {
-              "name": "hovered",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "fieldName": "hovered"
-            },
             {
               "name": "dateTo",
               "type": {
@@ -4710,14 +4905,6 @@
               "default": "[]",
               "fieldName": "disabledDays"
             },
-            {
-              "name": "hoveredDate",
-              "type": {
-                "text": "null"
-              },
-              "default": "null",
-              "fieldName": "hoveredDate"
-            },
             {
               "name": "isCurrentDate",
               "type": {
@@ -4748,6 +4935,14 @@
               },
               "default": "false",
               "fieldName": "renderForDateSlot"
+            },
+            {
+              "name": "hasPopoverContent",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "fieldName": "hasPopoverContent"
             }
           ],
           "superclass": {
@@ -4806,10 +5001,21 @@
                 }
               }
             },
+            {
+              "kind": "method",
+              "name": "getHeadingId",
+              "description": "Returns the unique heading ID for this month, used by aria-labelledby.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "String"
+                }
+              }
+            },
             {
               "kind": "method",
               "name": "localeChanged",
-              "description": "Determines the current month name based on locale.\nThis is a rewrite of the function used in the class RangeDatepickerCalendar and should not be removed from here.",
+              "description": "Determines the current month name based on locale.\nAlso builds parallel arrays of full day names for abbr attributes.\nThis is a rewrite of the function used in the class RangeDatepickerCalendar and should not be removed from here.",
               "privacy": "private",
               "return": {
                 "type": {
@@ -4819,16 +5025,102 @@
             },
             {
               "kind": "method",
-              "name": "renderDay",
+              "name": "renderDayOfWeek",
               "parameters": [
                 {
-                  "name": "day"
+                  "name": "dayOfWeek",
+                  "description": "The short day name.",
+                  "type": {
+                    "text": "String"
+                  }
+                },
+                {
+                  "name": "index",
+                  "description": "The index in the dayNamesOfTheWeek array.",
+                  "type": {
+                    "text": "Number"
+                  }
                 }
-              ]
-            },
-            {
-              "kind": "field",
-              "name": "monthFirst",
+              ],
+              "description": "Renders a day-of-week header with abbr attribute for the full day name.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Object"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "getFocusableCells",
+              "description": "Returns all focusable cell elements (enabled + blackout, not out-of-range) in this month.",
+              "return": {
+                "type": {
+                  "text": "Array"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "handleDateHovered",
+              "parameters": [
+                {
+                  "name": "event",
+                  "description": "The date-is-hovered event from a cell.",
+                  "type": {
+                    "text": "CustomEvent"
+                  }
+                }
+              ],
+              "description": "Overrides the base class handler to prevent setting `this.hoveredDate`\nas a reactive property. Instead, just dispatches the event upward so\nthe calendar can handle range preview imperatively.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "handleGridKeyDown",
+              "parameters": [
+                {
+                  "name": "event",
+                  "description": "The keyboard event.",
+                  "type": {
+                    "text": "KeyboardEvent"
+                  }
+                }
+              ],
+              "description": "Handles arrow key navigation within the month grid.\nDispatches a cross-month navigation event when the boundary is reached.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "renderWeek",
+              "parameters": [
+                {
+                  "name": "week"
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "renderDay",
+              "parameters": [
+                {
+                  "name": "day"
+                }
+              ]
+            },
+            {
+              "kind": "field",
+              "name": "monthFirst",
               "privacy": "private",
               "type": {
                 "text": "boolean"
@@ -4837,6 +5129,26 @@
               "reflects": true
             }
           ],
+          "events": [
+            {
+              "name": "hovered-date-changed",
+              "type": {
+                "text": "CustomEvent"
+              }
+            },
+            {
+              "name": "calendar-month-boundary",
+              "type": {
+                "text": "CustomEvent"
+              }
+            },
+            {
+              "name": "calendar-cell-activate",
+              "type": {
+                "text": "CustomEvent"
+              }
+            }
+          ],
           "attributes": [
             {
               "name": "monthFirst",
@@ -4884,8 +5196,325 @@
           "members": [
             {
               "kind": "method",
-              "name": "handlePrevMonth",
-              "description": "Updates the month and year when the user navigates to the previous calendar month.",
+              "name": "handlePrevMonth",
+              "description": "Updates the month and year when the user navigates to the previous calendar month.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "handleNextMonth",
+              "description": "Updates the month and year when the user navigates to the next calendar month.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "announceMonthChange",
+              "description": "Announces the current month and year via the live region after navigation.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "updateActiveCellForVisibleMonth",
+              "description": "Recomputes and sets the active cell for the newly visible month after\nmonth navigation. Without this, activeCellDate can point at a date in\nthe old month, leaving no tabindex=\"0\" cell in the grid.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "renderAllCalendars",
+              "description": "Renders all of the auro-calendar-months HTML.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Object"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "focusCloseButton",
+              "description": "Focuses the close button inside the calendar's bibtemplate.\nUsed by datepicker to set initial focus when the fullscreen dialog opens.",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "scrollMonthIntoView",
+              "parameters": [
+                {
+                  "name": "date",
+                  "description": "The date to scroll into view.",
+                  "type": {
+                    "text": "String"
+                  }
+                }
+              ],
+              "description": "Request the calendar be scrolled to a given date.",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "getMonthComponents",
+              "description": "Gets all rendered month components.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Array"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "getAllFocusableCells",
+              "description": "Gets all focusable cells across all rendered months.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Array"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "setActiveCell",
+              "parameters": [
+                {
+                  "name": "date",
+                  "description": "Unix timestamp of the cell to activate.",
+                  "type": {
+                    "text": "Number"
+                  }
+                }
+              ],
+              "description": "Sets the active cell across all months. Only one cell has tabindex=\"0\" at a time.\nUses imperative DOM manipulation — no Lit re-render triggered.\nAlso updates ariaActiveDescendantElement on the grid wrapper so\nscreen readers announce the active cell without moving DOM focus.",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "focusActiveCell",
+              "description": "Focuses the calendar grid wrapper and sets the active cell.\nDOM focus stays on the grid wrapper; ariaActiveDescendantElement\ntells the screen reader which cell is \"active\".",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "computeActiveDate",
+              "parameters": [
+                {
+                  "name": "options",
+                  "default": "{}",
+                  "description": "Optional settings.",
+                  "optional": true,
+                  "type": {
+                    "text": "@param {boolean} [options.skipDateFrom=false] - When true, skip the selected-date\n   *   shortcut (step 1). Used after month navigation so the active cell lands in the\n   *   newly visible month instead of jumping back to the selected date's month.\n   * "
+                  }
+                }
+              ],
+              "description": "Computes the initial active date from data properties alone — no DOM required.\nPriority:\n  1. Selected date (dateFrom) if within range\n  2. Today's date if not disabled (in-range and not blackout)\n  3. First future non-disabled date (scans day-by-day from today up to 1 year)\n  4. First previous non-disabled date (scans day-by-day from today up to 1 year)\n  5. First enabled date in finite [min, max] range\n  5b. First enabled date scanning forward from finite min (unbounded max)\n  5c. First enabled date scanning backward from finite max (unbounded min)\n  6. First in-range date (even if blackout) so focus can land somewhere\n  7. undefined — no valid target",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Number|undefined"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "handleGridKeyDown",
+              "parameters": [
+                {
+                  "name": "event",
+                  "description": "The keyboard event.",
+                  "type": {
+                    "text": "KeyboardEvent"
+                  }
+                }
+              ],
+              "description": "Handles arrow key navigation on the calendar grid wrapper.\nFocus stays on the grid wrapper; only ariaActiveDescendantElement\nand the visual active-cell indicator change.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "handleMonthBoundary",
+              "parameters": [
+                {
+                  "name": "event",
+                  "description": "The boundary event with direction and source date info.",
+                  "type": {
+                    "text": "CustomEvent"
+                  }
+                }
+              ],
+              "description": "Handles cross-month boundary navigation events from month components.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "handleCellActivate",
+              "parameters": [
+                {
+                  "name": "event",
+                  "description": "The activation event with target date.",
+                  "type": {
+                    "text": "CustomEvent"
+                  }
+                }
+              ],
+              "description": "Handles cell activation events from month components.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "handleCellFocused",
+              "parameters": [
+                {
+                  "name": "event",
+                  "description": "The calendar-cell-focused event.",
+                  "type": {
+                    "text": "CustomEvent"
+                  }
+                }
+              ],
+              "description": "Handles focus events from calendar cells.\nUpdates the live region with an SR announcement and triggers\nthe imperative range preview if applicable.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "buildFocusAnnouncement",
+              "parameters": [
+                {
+                  "name": "date",
+                  "description": "Unix timestamp (seconds) of the focused cell.",
+                  "type": {
+                    "text": "Number"
+                  }
+                }
+              ],
+              "description": "Builds a full SR announcement string for a focused cell date.\nIncludes the localized date, range position, popover content,\nand blackout status.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "String"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "getRangePositionLabel",
+              "parameters": [
+                {
+                  "name": "date",
+                  "description": "Unix timestamp (seconds).",
+                  "type": {
+                    "text": "Number"
+                  }
+                }
+              ],
+              "description": "Determines the range position label for a given date.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "String|null"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "isDateBlackout",
+              "parameters": [
+                {
+                  "name": "dateTs",
+                  "description": "Unix timestamp (seconds).",
+                  "type": {
+                    "text": "Number"
+                  }
+                }
+              ],
+              "description": "Checks whether a given date is a blackout date.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Boolean"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "updateRangePreview",
+              "parameters": [
+                {
+                  "name": "hoveredDate",
+                  "description": "Unix timestamp of the hovered/focused date.",
+                  "type": {
+                    "text": "Number"
+                  }
+                }
+              ],
+              "description": "Updates the range preview classes imperatively across all cells.\nOnly active when in range mode with dateFrom set and dateTo not yet set.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "clearRangePreview",
+              "description": "Clears range preview classes from all cells.",
               "privacy": "private",
               "return": {
                 "type": {
@@ -4895,8 +5524,17 @@
             },
             {
               "kind": "method",
-              "name": "handleNextMonth",
-              "description": "Updates the month and year when the user navigates to the next calendar month.",
+              "name": "hoveredDateChanged",
+              "parameters": [
+                {
+                  "name": "event",
+                  "description": "The hovered-date-changed event from a month.",
+                  "type": {
+                    "text": "CustomEvent"
+                  }
+                }
+              ],
+              "description": "Overrides the base class handler to prevent setting `this.hoveredDate`\nas a reactive property. Instead, handles the range preview imperatively.",
               "privacy": "private",
               "return": {
                 "type": {
@@ -4906,19 +5544,29 @@
             },
             {
               "kind": "method",
-              "name": "renderAllCalendars",
-              "description": "Renders all of the auro-calendar-months HTML.",
+              "name": "scrollToActiveCell",
+              "description": "Scrolls the calendar to ensure the month containing the active cell is visible.",
               "privacy": "private",
               "return": {
                 "type": {
-                  "text": "Object"
+                  "text": "void"
                 }
               }
             },
             {
               "kind": "method",
-              "name": "focusCloseButton",
-              "description": "Focuses the close button inside the calendar's bibtemplate.\nUsed by datepicker to set initial focus when the fullscreen dialog opens.",
+              "name": "announceSelection",
+              "parameters": [
+                {
+                  "name": "dateStr",
+                  "description": "The localized date string to announce.",
+                  "type": {
+                    "text": "String"
+                  }
+                }
+              ],
+              "description": "Announces a date selection or focus change via the live region.",
+              "privacy": "private",
               "return": {
                 "type": {
                   "text": "void"
@@ -4927,23 +5575,44 @@
             },
             {
               "kind": "method",
-              "name": "scrollMonthIntoView",
+              "name": "announceFocusDebounced",
               "parameters": [
                 {
-                  "name": "date",
-                  "description": "The date to scroll into view.",
+                  "name": "dateStr",
+                  "description": "The localized date string to announce.",
                   "type": {
                     "text": "String"
                   }
                 }
               ],
-              "description": "Request the calendar be scrolled to a given date.",
+              "description": "Debounced version of announceSelection for focus navigation.\nOnly announces the last focused date after rapid navigation pauses,\npreventing the screen reader from queueing up stale announcements\nthat can't keep pace with arrow-key traversal.",
+              "privacy": "private",
               "return": {
                 "type": {
                   "text": "void"
                 }
               }
             },
+            {
+              "kind": "method",
+              "name": "formatAnnouncementDate",
+              "parameters": [
+                {
+                  "name": "timestamp",
+                  "description": "Unix timestamp in seconds.",
+                  "type": {
+                    "text": "String|Number"
+                  }
+                }
+              ],
+              "description": "Formats a Unix timestamp (seconds) as a localized date string for SR announcements.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "String"
+                }
+              }
+            },
             {
               "kind": "method",
               "name": "injectSlot",
@@ -5047,6 +5716,16 @@
               "attribute": "isFullscreen",
               "reflects": true
             },
+            {
+              "kind": "field",
+              "name": "activeCellDate",
+              "type": {
+                "text": "null"
+              },
+              "description": "The date of the currently active cell (Unix timestamp).\nOnly one cell across the entire calendar has tabindex=\"0\" at a time.",
+              "privacy": "private",
+              "default": "null"
+            },
             {
               "kind": "field",
               "name": "firstMonthRenderable",
@@ -5671,6 +6350,17 @@
                 }
               }
             },
+            {
+              "kind": "method",
+              "name": "focusActiveCellWhenReady",
+              "description": "Attempts to focus the active calendar cell using a rAF retry loop.\nShared by both fullscreen and desktop open paths.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
             {
               "kind": "method",
               "name": "configureDropdown",
@@ -5822,6 +6512,26 @@
                 }
               }
             },
+            {
+              "kind": "method",
+              "name": "isBlackoutDate",
+              "parameters": [
+                {
+                  "name": "dateStr",
+                  "description": "A date string in the component's configured format.",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Checks whether a formatted date string matches a blackout date.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              }
+            },
             {
               "kind": "method",
               "name": "validate",
@@ -6151,6 +6861,114 @@
               "attribute": "range",
               "reflects": true
             },
+            {
+              "kind": "field",
+              "name": "rangeLabelStart",
+              "privacy": "public",
+              "type": {
+                "text": "string"
+              },
+              "description": "Label announced for the range start date cell.",
+              "default": "'range start'",
+              "attribute": "rangeLabelStart",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "rangeLabelEnd",
+              "privacy": "public",
+              "type": {
+                "text": "string"
+              },
+              "description": "Label announced for the range end date cell.",
+              "default": "'range end'",
+              "attribute": "rangeLabelEnd",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "rangeLabelBeforeRange",
+              "privacy": "public",
+              "type": {
+                "text": "string"
+              },
+              "description": "Label announced for cells before the range start.",
+              "default": "'before range'",
+              "attribute": "rangeLabelBeforeRange",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "rangeLabelInRange",
+              "privacy": "public",
+              "type": {
+                "text": "string"
+              },
+              "description": "Label announced for cells within the selected range.",
+              "default": "'in range'",
+              "attribute": "rangeLabelInRange",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "rangeLabelAfterRange",
+              "privacy": "public",
+              "type": {
+                "text": "string"
+              },
+              "description": "Label announced for cells after the range (or after start when no end is selected).",
+              "default": "'after range'",
+              "attribute": "rangeLabelAfterRange",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "blackoutDates",
+              "privacy": "public",
+              "type": {
+                "text": "array"
+              },
+              "description": "Array of dates that cannot be selected. Dates should be in ISO format (YYYY-MM-DD).",
+              "default": "[]",
+              "attribute": "blackoutDates",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "blackoutLabel",
+              "privacy": "public",
+              "type": {
+                "text": "string"
+              },
+              "description": "Label announced for blackout (disabled but in-range) date cells.",
+              "default": "'unavailable'",
+              "attribute": "blackoutLabel",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "navLabelPrevMonth",
+              "privacy": "public",
+              "type": {
+                "text": "string"
+              },
+              "description": "Accessible label for the previous month navigation button.",
+              "default": "'Previous month'",
+              "attribute": "navLabelPrevMonth",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "navLabelNextMonth",
+              "privacy": "public",
+              "type": {
+                "text": "string"
+              },
+              "description": "Accessible label for the next month navigation button.",
+              "default": "'Next month'",
+              "attribute": "navLabelNextMonth",
+              "reflects": true
+            },
             {
               "kind": "field",
               "name": "stacked",
@@ -6604,7 +7422,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Custom help text message to display when validity = `customError`.",
+              "description": "Custom help text message to display when validity = `customError`.\nAlso used as the validation message when a blackout date is typed into the input.",
               "attribute": "setCustomValidityCustomError"
             },
             {
@@ -6714,8 +7532,11 @@
               "description": "Notifies that new slot content has been added to the datepicker."
             },
             {
-              "description": "Notifies that the component value(s) have been validated.",
-              "name": "auroFormElement-validated"
+              "name": "auroFormElement-validated",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Notifies that the component value(s) have been validated."
             }
           ],
           "attributes": [
@@ -6980,6 +7801,87 @@
               "default": "false",
               "fieldName": "range"
             },
+            {
+              "name": "rangeLabelStart",
+              "type": {
+                "text": "string"
+              },
+              "description": "Label announced for the range start date cell.",
+              "default": "'range start'",
+              "fieldName": "rangeLabelStart"
+            },
+            {
+              "name": "rangeLabelEnd",
+              "type": {
+                "text": "string"
+              },
+              "description": "Label announced for the range end date cell.",
+              "default": "'range end'",
+              "fieldName": "rangeLabelEnd"
+            },
+            {
+              "name": "rangeLabelBeforeRange",
+              "type": {
+                "text": "string"
+              },
+              "description": "Label announced for cells before the range start.",
+              "default": "'before range'",
+              "fieldName": "rangeLabelBeforeRange"
+            },
+            {
+              "name": "rangeLabelInRange",
+              "type": {
+                "text": "string"
+              },
+              "description": "Label announced for cells within the selected range.",
+              "default": "'in range'",
+              "fieldName": "rangeLabelInRange"
+            },
+            {
+              "name": "rangeLabelAfterRange",
+              "type": {
+                "text": "string"
+              },
+              "description": "Label announced for cells after the range (or after start when no end is selected).",
+              "default": "'after range'",
+              "fieldName": "rangeLabelAfterRange"
+            },
+            {
+              "name": "blackoutDates",
+              "type": {
+                "text": "array"
+              },
+              "description": "Array of dates that cannot be selected. Dates should be in ISO format (YYYY-MM-DD).",
+              "default": "[]",
+              "fieldName": "blackoutDates"
+            },
+            {
+              "name": "blackoutLabel",
+              "type": {
+                "text": "string"
+              },
+              "description": "Label announced for blackout (disabled but in-range) date cells.",
+              "default": "'unavailable'",
+              "fieldName": "blackoutLabel"
+            },
+            {
+              "name": "navLabelPrevMonth",
+              "type": {
+                "text": "string"
+              },
+              "description": "Accessible label for the previous month navigation button.",
+              "default": "'Previous month'",
+              "fieldName": "navLabelPrevMonth"
+            },
+            {
+              "name": "navLabelNextMonth",
+              "type": {
+                "text": "string"
+              },
+              "description": "Accessible label for the next month navigation button.",
+              "default": "'Next month'",
+              "fieldName": "navLabelNextMonth"
+            },
             {
               "name": "referenceDates",
               "type": {
@@ -7010,7 +7912,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Custom help text message to display when validity = `customError`.",
+              "description": "Custom help text message to display when validity = `customError`.\nAlso used as the validation message when a blackout date is typed into the input.",
               "fieldName": "setCustomValidityCustomError"
             },
             {
@@ -7151,7 +8053,7 @@
           "type": {
             "text": "object"
           },
-          "default": "{ Escape(component, evt) { if (!component.dropdown || !component.dropdown.isPopoverVisible) { return; } // Prevent the Escape key from bubbling up and closing any parent dialogs / drawers / popups. // Because stopPropagation prevents the document-level floatingUI keydown handler from // seeing this event, we must also close the dropdown explicitly. evt.stopPropagation(); component.dropdown.hide(); }, }"
+          "default": "{ Escape(component, evt, ctx) { if (!ctx.isExpanded) { return; } // Stop propagation so parent containers (auro-dialog, auro-drawer) // don't also react to Escape. evt.stopPropagation(); evt.preventDefault(); component.hideBib(); }, Enter(component, evt, ctx) { if (ctx.isExpanded) { return; } // Only open from the trigger input, not the clear button or other internal elements. // evt.target is retargeted to the host in shadow DOM, so use composedPath() // to find the real origin. The clear button is rendered with class \"clearBtn\". const path = evt.composedPath(); if (path.some(el => el.classList?.contains('clearBtn'))) { return; } evt.preventDefault(); component.dropdown.show(); }, ' '(component, evt, ctx) { if (ctx.isExpanded) { return; } // Only open from the trigger input, not the clear button or other internal elements. // evt.target is retargeted to the host in shadow DOM, so use composedPath() // to find the real origin. The clear button is rendered with class \"clearBtn\". const path = evt.composedPath(); if (path.some(el => el.classList?.contains('clearBtn'))) { return; } evt.preventDefault(); component.dropdown.show(); }, }"
         }
       ],
       "exports": [
@@ -8005,6 +8907,29 @@
               "name": "updateFocusTrap",
               "privacy": "private"
             },
+            {
+              "kind": "method",
+              "name": "_getActiveElements",
+              "description": "Returns the chain of active (focused) elements through shadow roots.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Array<HTMLElement>"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "_setPageInert",
+              "description": "Sets `inert` on sibling elements of the dropdown's top-level host\nso that content outside the dropdown is not interactive while the modal is open.\nWalks up through shadow DOM boundaries to find the outermost host element\nin the light DOM, then sets `inert` on siblings at each ancestor level\nto ensure all page content outside the host subtree is inert.",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "_clearPageInert",
+              "description": "Restores `inert` state on siblings that were tracked by `_setPageInert`.\nPreserves the previous inert state so externally-inerted elements are\nnot inadvertently re-enabled.",
+              "privacy": "private"
+            },
             {
               "kind": "method",
               "name": "handleFocusout",
@@ -8311,6 +9236,17 @@
               "attribute": "autoPlacement",
               "reflects": true
             },
+            {
+              "kind": "field",
+              "name": "desktopModal",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "If declared, the dropdown will behave as a modal dialog when in a desktop viewport size.",
+              "attribute": "desktopModal",
+              "reflects": true
+            },
             {
               "kind": "field",
               "name": "disableEventShow",
@@ -8617,6 +9553,14 @@
               "description": "If declared, bib's position will be automatically calculated where to appear.",
               "fieldName": "autoPlacement"
             },
+            {
+              "name": "desktopModal",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "If declared, the dropdown will behave as a modal dialog when in a desktop viewport size.",
+              "fieldName": "desktopModal"
+            },
             {
               "name": "disableEventShow",
               "type": {
@@ -18793,7 +19737,7 @@
           "type": {
             "text": "object"
           },
-          "default": "{ ArrowDown(component, evt, ctx) { evt.preventDefault(); if (ctx.isExpanded) { if (evt.altKey || evt.ctrlKey || evt.metaKey) { // navigate to last enabled option selectKeyboardStrategy.End(component, evt, ctx); } else { navigateArrow(component, 'down', { ctx }); } } else { component.dropdown.show(); } }, ArrowUp(component, evt, ctx) { evt.preventDefault(); if (ctx.isExpanded) { if (evt.altKey || evt.ctrlKey || evt.metaKey) { // navigate to first enabled option selectKeyboardStrategy.Home(component, evt, ctx); } else { navigateArrow(component, 'up', { ctx }); } } else { component.dropdown.show(); } }, Escape(component, evt, ctx) { if (!ctx.isExpanded) { return; } // Prevent the Escape key from bubbling up and closing any parent dialogs / drawers / popups evt.stopPropagation(); component.dropdown.hide(); }, End(component, evt, ctx) { if (!ctx.isExpanded) { return; } evt.preventDefault(); evt.stopPropagation(); const lastOption = [...component.menu.menuService.menuOptions].reverse().find((option) => !option.disabled); if (lastOption) { component.menu.updateActiveOption(lastOption); } }, Enter(component, evt, ctx) { evt.preventDefault(); evt.stopPropagation(); if (!ctx.isExpanded) { component.dropdown.show(); return; } component.menu.makeSelection(); }, Home(component, evt, ctx) { if (!ctx.isExpanded) { return; } evt.preventDefault(); evt.stopPropagation(); const firstOption = component.menu.menuService.menuOptions.find((option) => !option.disabled); if (firstOption) { component.menu.updateActiveOption(firstOption); } }, Tab(component, evt, ctx) { if (!ctx.isExpanded) { return; } // Tab selects the focused option and closes the popup per the // WAI-ARIA APG select-only combobox / listbox pattern. if (component.optionActive) { component.menu.makeSelection(); } component.dropdown.hide(); }, default(component, evt, ctx) { component.updateActiveOptionBasedOnKey(evt.key); if (evt.key === ' ') { evt.preventDefault(); evt.stopPropagation(); if (ctx.isExpanded) { component.dropdown.hide(); return; } component.dropdown.show(); } }, }"
+          "default": "{ ArrowDown(component, evt, ctx) { evt.preventDefault(); if (evt.altKey || evt.metaKey) { // navigate to last enabled option selectKeyboardStrategy.End(component, evt, ctx); return; } navigateArrow(component, 'down', { ctx, showFn: () => component.dropdown.show(), }); }, ArrowUp(component, evt, ctx) { evt.preventDefault(); if (evt.altKey || evt.metaKey) { // navigate to first enabled option selectKeyboardStrategy.Home(component, evt, ctx); return; } navigateArrow(component, 'up', { ctx, showFn: () => component.dropdown.show(), }); }, Escape(component, evt, ctx) { if (!ctx.isExpanded) { return; } // Prevent the Escape key from bubbling up and closing any parent dialogs / drawers / popups evt.stopPropagation(); component.dropdown.hide(); }, End(component, evt, ctx) { if (!ctx.isExpanded) { return; } evt.preventDefault(); evt.stopPropagation(); const lastOption = [...component.menu.menuService.menuOptions].reverse().find((option) => !option.disabled); if (lastOption) { component.menu.updateActiveOption(lastOption); } }, Enter(component, evt, ctx) { evt.preventDefault(); evt.stopPropagation(); if (!ctx.isExpanded) { component.dropdown.show(); return; } component.menu.makeSelection(); }, Home(component, evt, ctx) { if (!ctx.isExpanded) { return; } evt.preventDefault(); evt.stopPropagation(); const firstOption = component.menu.menuService.menuOptions.find((option) => !option.disabled); if (firstOption) { component.menu.updateActiveOption(firstOption); } }, Tab(component, evt, ctx) { if (!ctx.isExpanded) { return; } // Tab selects the focused option and closes the popup per the // WAI-ARIA APG select-only combobox / listbox pattern. if (component.optionActive) { component.menu.makeSelection(); } component.dropdown.hide(); }, default(component, evt, ctx) { component.updateActiveOptionBasedOnKey(evt.key); if (evt.key === ' ') { evt.preventDefault(); evt.stopPropagation(); if (ctx.isExpanded) { component.dropdown.hide(); return; } component.dropdown.show(); } }, }"
         }
       ],
       "exports": [