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

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": {
@@ -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",
@@ -4413,7 +4514,7 @@
                   }
                 }
               ],
-              "description": "Checks if the current date is a highlighted date.",
+              "description": "Checks if the current date is a referenced date.",
               "return": {
                 "type": {
                   "text": ""
@@ -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 without triggering a Lit re-render.\nNote: buttons stay tabindex=\"-1\" because the grid uses aria-activedescendant.",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "clearActive",
+              "description": "Imperatively marks this cell as inactive without triggering 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": {
@@ -4756,6 +4951,10 @@
           },
           "tagName": "auro-formkit-calendar-cell",
           "customElement": true
+        },
+        {
+          "kind": "variable",
+          "name": "blackout"
         }
       ],
       "exports": [
@@ -4806,19 +5005,107 @@
                 }
               }
             },
+            {
+              "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"
             },
             {
               "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"
+                  }
                 }
-              ]
-            },
+              ],
+              "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": "handleTbodyMouseLeave",
+              "description": "Dispatches a bubbling event when the mouse leaves the date grid body\nso the parent calendar can clear the range hover preview.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "renderWeek",
+              "parameters": [
+                {
+                  "name": "week"
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "renderDay",
+              "parameters": [
+                {
+                  "name": "day"
+                }
+              ]
+            },
             {
               "kind": "field",
               "name": "monthFirst",
@@ -4836,7 +5123,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "BCP 47 locale tag (such as `en-US`) for calendar localization.\nas wc-range-datepicker expects a `locale` prop, we use `localeCode` to avoid conflicts.",
+              "description": "BCP 47 locale tag (such as `en-US`) for calendar localization.\nAs wc-range-datepicker expects a `locale` prop, we use `localeCode` to avoid conflicts.",
               "attribute": "localeCode"
             },
             {
@@ -4850,6 +5137,20 @@
               "attribute": "monthNames"
             }
           ],
+          "events": [
+            {
+              "name": "hovered-date-changed",
+              "type": {
+                "text": "CustomEvent"
+              }
+            },
+            {
+              "name": "calendar-month-mouseleave",
+              "type": {
+                "text": "CustomEvent"
+              }
+            }
+          ],
           "attributes": [
             {
               "name": "monthFirst",
@@ -4863,7 +5164,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "BCP 47 locale tag (such as `en-US`) for calendar localization.\nas wc-range-datepicker expects a `locale` prop, we use `localeCode` to avoid conflicts.",
+              "description": "BCP 47 locale tag (such as `en-US`) for calendar localization.\nAs wc-range-datepicker expects a `locale` prop, we use `localeCode` to avoid conflicts.",
               "fieldName": "localeCode"
             },
             {
@@ -4944,6 +5245,16 @@
             {
               "kind": "method",
               "name": "handlePrevMonth",
+              "parameters": [
+                {
+                  "name": "options",
+                  "description": "Optional settings.",
+                  "optional": true,
+                  "type": {
+                    "text": "@param {boolean} [options.skipActiveUpdate=false] - When true, skip the active cell\n   *   recomputation. Used by arrow key handlers that manage the active cell themselves.\n   * "
+                  }
+                }
+              ],
               "description": "Updates the month and year when the user navigates to the previous calendar month.",
               "privacy": "private",
               "return": {
@@ -4955,6 +5266,16 @@
             {
               "kind": "method",
               "name": "handleNextMonth",
+              "parameters": [
+                {
+                  "name": "options",
+                  "description": "Optional settings.",
+                  "optional": true,
+                  "type": {
+                    "text": "@param {boolean} [options.skipActiveUpdate=false] - When true, skip the active cell\n   *   recomputation. Used by arrow key handlers that manage the active cell themselves.\n   * "
+                  }
+                }
+              ],
               "description": "Updates the month and year when the user navigates to the next calendar month.",
               "privacy": "private",
               "return": {
@@ -4963,6 +5284,28 @@
                 }
               }
             },
+            {
+              "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": "Updates the active cell after month navigation (prev/next buttons).\nAlways moves the active cell to the first enabled date in the newly\nvisible months so that tabbing back to the grid lands on an enabled cell.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
             {
               "kind": "method",
               "name": "renderAllCalendars",
@@ -5003,6 +5346,404 @@
                 }
               }
             },
+            {
+              "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; the aria-live region\ntells the screen reader which cell is \"active\".",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "handleGridFocusIn",
+              "description": "Shows the activeCell ring when the grid gains focus.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "handleGridFocusOut",
+              "description": "Hides the activeCell ring when the grid loses focus.",
+              "privacy": "private",
+              "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": "isDateInRange",
+              "parameters": [
+                {
+                  "name": "targetTs",
+                  "description": "Unix timestamp in seconds.",
+                  "type": {
+                    "text": "Number"
+                  }
+                }
+              ],
+              "description": "Checks if a target date (unix seconds) is within the configured [min, max] range.\nReturns false if the date falls outside the range, preventing navigation\nto months where all dates are disabled.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Boolean"
+                }
+              }
+            },
+            {
+              "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",
+              "parameters": [
+                {
+                  "name": "options",
+                  "description": "Optional settings.",
+                  "optional": true,
+                  "type": {
+                    "text": "@param {boolean} [options.force=false] - When true, clears classes even\n   *   when both dateFrom and dateTo are set. Used by month nav handlers\n   *   since the subsequent re-render re-applies classMap-managed classes,\n   *   while `lastHoveredDate` (not in classMap) would otherwise persist.\n   * "
+                  }
+                }
+              ],
+              "description": "Clears range preview classes from all cells.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "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": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "scrollToActiveCell",
+              "description": "Scrolls the calendar to ensure the month containing the active cell is visible.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "getOrCreateLiveRegion",
+              "description": "Returns (and lazily creates) an aria-live region inside the dropdown's\n<dialog> element. This placement is critical for two reasons:\n\n1. Inside the dialog's accessible scope — dialog.showModal() makes\n   everything outside the top-layer dialog inert, and desktop modal\n   mode uses _setPageInert() on document.body siblings. A live region\n   on document.body would be invisible to screen readers in both cases.\n\n2. Not nested in shadow DOM — Chrome inconsistently observes aria-live\n   mutations inside shadow DOM across machines and versions. The dialog\n   element is only one shadow root deep (the dropdown bib's shadow DOM),\n   which Chrome handles reliably. The calendar's own shadow DOM (nested\n   inside the bib via slotting) is two+ levels deep and unreliable.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "HTMLElement"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "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.\nUses requestAnimationFrame to ensure the clear and set happen in\nseparate rendering frames — Chrome may coalesce synchronous or\nmicrotask-deferred mutations into a single accessibility tree update.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "announceFocusDebounced",
+              "parameters": [
+                {
+                  "name": "dateStr",
+                  "description": "The localized date string to announce.",
+                  "type": {
+                    "text": "String"
+                  }
+                }
+              ],
+              "description": "Debounced version of announceSelection for focus navigation.\nUses the assertive live region with a 150ms debounce so only the\nfinal cell after rapid arrow-key traversal is announced. We\noriginally tried aria-live=\"polite\" here, but VoiceOver treats\npolite as \"wait until idle\" — which never happens during active\nkeyboard navigation — so the announcements were silently dropped.",
+              "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",
@@ -5106,6 +5847,26 @@
               "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": "_gridHasFocus",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Whether the #calendarGrid wrapper currently has focus.\nUsed to determine whether the visualFocus ring should be shown.",
+              "privacy": "private",
+              "default": "false"
+            },
             {
               "kind": "field",
               "name": "firstMonthRenderable",
@@ -5121,6 +5882,16 @@
               "privacy": "private",
               "default": "null"
             },
+            {
+              "kind": "field",
+              "name": "disabledDays",
+              "type": {
+                "text": "array"
+              },
+              "description": "Legacy array of disabled-date timestamps.",
+              "privacy": "private",
+              "default": "[]"
+            },
             {
               "kind": "field",
               "name": "numCalendars",
@@ -5162,6 +5933,12 @@
               "default": "undefined",
               "attribute": "dropdown"
             },
+            {
+              "kind": "field",
+              "name": "_calendarInstanceId",
+              "description": "Unique instance ID for the live region element.",
+              "privacy": "private"
+            },
             {
               "kind": "field",
               "name": "calendarEndMonth",
@@ -5872,6 +6649,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",
@@ -6019,7 +6807,27 @@
               "description": "Clears the current value(s) of the datepicker.",
               "return": {
                 "type": {
-                  "text": "void"
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "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"
                 }
               }
             },
@@ -6192,7 +7000,7 @@
               "parameters": [
                 {
                   "name": "event",
-                  "description": "The click event object.",
+                  "description": "The mouse event from the clear button click.",
                   "type": {
                     "text": "MouseEvent"
                   }
@@ -6365,6 +7173,126 @@
               "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": "calendarGridLabel",
+              "privacy": "public",
+              "type": {
+                "text": "string"
+              },
+              "description": "Accessible label for the calendar grid containing the days of the month.",
+              "default": "'Calendar days of the month'",
+              "attribute": "calendarGridLabel",
+              "reflects": true
+            },
             {
               "kind": "field",
               "name": "stacked",
@@ -6766,6 +7694,15 @@
               "attribute": "minDate",
               "reflects": true
             },
+            {
+              "kind": "field",
+              "name": "monthFirst",
+              "privacy": "private",
+              "type": {
+                "text": "boolean"
+              },
+              "attribute": "monthFirst"
+            },
             {
               "kind": "field",
               "name": "monthNames",
@@ -6826,7 +7763,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"
             },
             {
@@ -6929,8 +7866,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": [
@@ -6952,6 +7892,24 @@
               "default": "false",
               "fieldName": "autoPlacement"
             },
+            {
+              "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": "calendarEndDate",
               "type": {
@@ -6961,6 +7919,15 @@
               "default": "undefined",
               "fieldName": "calendarEndDate"
             },
+            {
+              "name": "calendarGridLabel",
+              "type": {
+                "text": "string"
+              },
+              "description": "Accessible label for the calendar grid containing the days of the month.",
+              "default": "'Calendar days of the month'",
+              "fieldName": "calendarGridLabel"
+            },
             {
               "name": "calendarFocusDate",
               "type": {
@@ -7012,30 +7979,6 @@
               "description": "When defined, sets persistent validity to `customError` and sets the validation message to the attribute value.",
               "fieldName": "error"
             },
-            {
-              "name": "hasFocus",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "fieldName": "hasFocus"
-            },
-            {
-              "name": "hasValue",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "fieldName": "hasValue"
-            },
-            {
-              "name": "hasAllValues",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "fieldName": "hasAllValues"
-            },
             {
               "name": "format",
               "type": {
@@ -7061,6 +8004,30 @@
               "default": "'sm'",
               "fieldName": "fullscreenBreakpoint"
             },
+            {
+              "name": "hasAllValues",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "fieldName": "hasAllValues"
+            },
+            {
+              "name": "hasFocus",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "fieldName": "hasFocus"
+            },
+            {
+              "name": "hasValue",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "fieldName": "hasValue"
+            },
             {
               "name": "inputmode",
               "type": {
@@ -7107,6 +8074,13 @@
               "description": "Minimum date. All dates before will be disabled.",
               "fieldName": "minDate"
             },
+            {
+              "name": "monthFirst",
+              "type": {
+                "text": "boolean"
+              },
+              "fieldName": "monthFirst"
+            },
             {
               "name": "monthNames",
               "type": {
@@ -7116,22 +8090,31 @@
               "fieldName": "monthNames"
             },
             {
-              "name": "noFlip",
+              "name": "navLabelNextMonth",
               "type": {
-                "text": "boolean"
+                "text": "string"
               },
-              "description": "If declared, the bib will NOT flip to an alternate position\nwhen there isn't enough space in the specified `placement`.",
-              "default": "false",
-              "fieldName": "noFlip"
+              "description": "Accessible label for the next month navigation button.",
+              "default": "'Next month'",
+              "fieldName": "navLabelNextMonth"
             },
             {
-              "name": "shift",
+              "name": "navLabelPrevMonth",
+              "type": {
+                "text": "string"
+              },
+              "description": "Accessible label for the previous month navigation button.",
+              "default": "'Previous month'",
+              "fieldName": "navLabelPrevMonth"
+            },
+            {
+              "name": "noFlip",
               "type": {
                 "text": "boolean"
               },
-              "description": "If declared, the dropdown will shift its position to avoid being cut off by the viewport.",
+              "description": "If declared, the bib will NOT flip to an alternate position\nwhen there isn't enough space in the specified `placement`.",
               "default": "false",
-              "fieldName": "shift"
+              "fieldName": "noFlip"
             },
             {
               "name": "noValidate",
@@ -7194,6 +8177,51 @@
               "default": "false",
               "fieldName": "range"
             },
+            {
+              "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": "rangeLabelBeforeRange",
+              "type": {
+                "text": "string"
+              },
+              "description": "Label announced for cells before the range start.",
+              "default": "'before range'",
+              "fieldName": "rangeLabelBeforeRange"
+            },
+            {
+              "name": "rangeLabelEnd",
+              "type": {
+                "text": "string"
+              },
+              "description": "Label announced for the range end date cell.",
+              "default": "'range end'",
+              "fieldName": "rangeLabelEnd"
+            },
+            {
+              "name": "rangeLabelInRange",
+              "type": {
+                "text": "string"
+              },
+              "description": "Label announced for cells within the selected range.",
+              "default": "'in range'",
+              "fieldName": "rangeLabelInRange"
+            },
+            {
+              "name": "rangeLabelStart",
+              "type": {
+                "text": "string"
+              },
+              "description": "Label announced for the range start date cell.",
+              "default": "'range start'",
+              "fieldName": "rangeLabelStart"
+            },
             {
               "name": "referenceDates",
               "type": {
@@ -7224,7 +8252,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"
             },
             {
@@ -7251,6 +8279,15 @@
               "description": "Custom help text message to display when validity = `valueMissing`.",
               "fieldName": "setCustomValidityValueMissing"
             },
+            {
+              "name": "shift",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "If declared, the dropdown will shift its position to avoid being cut off by the viewport.",
+              "default": "false",
+              "fieldName": "shift"
+            },
             {
               "name": "stacked",
               "type": {
@@ -7365,7 +8402,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": [
@@ -8064,6 +9101,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`.\nUses reference counting so inert is only cleared when the last modal\ndropdown releases a given element. Preserves the original inert state\nso externally-inerted elements are not inadvertently re-enabled.",
+              "privacy": "private"
+            },
             {
               "kind": "method",
               "name": "handleFocusout",
@@ -8370,6 +9430,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",
@@ -8676,6 +9747,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": {