@beeq/core 1.12.14-beta.0 → 1.13.0

package/dist/types/components/date-picker/bq-date-picker.d.ts

@@ -1,33 +1,31 @@
 import type { EventEmitter } from '../../stencil-public-runtime';
 import type { Placement } from '../../services/interfaces';
-import type { TInputValidation } from '../input/bq-input.types';
-import type { DaysOfWeek, TDatePickerType } from './bq-date-picker.types';
+import { type TInputValidation } from '../input/bq-input.types';
+import type { DaysOfWeek, TCalendarView, TDatePickerType, TDatePrecision, TFloatingStrategy, TMonthsPerView } from './bq-date-picker.types';
 /**
- * The Date Picker is a intuitive UI element component allows users to select dates from a visual calendar interface, providing an intuitive way to input date information.
+ * The Date Picker is a pure-Stencil calendar input.
+ *
+ * It supports single, multi, and range selection, three navigation views
+ * (days → months → years), full localization via `Intl.DateTimeFormat`,
+ * multi-month side-by-side rendering, and RTL layouts.
  *
  * @example How to use it
  * ```html
  * <bq-date-picker
  *   first-day-of-week="1"
  *   locale="en-GB"
- *   months-per-view="single"
- *   months="2"
  *   name="bq-date-picker"
  *   placeholder="Enter your date"
- *   placement="bottom-end"
- *   show-outside-days="false"
- *   type="range"
- *   validation-status="none"
- *   value="2024-05-25"
+ *   type="single"
+ *   value="2026-07-15"
  * >
- *   <label class="flex flex-grow items-center" slot="label">
- *     Date picker label
- *   </label>
+ *   <label slot="label">Date picker label</label>
  * </bq-date-picker>
  * ```
  *
- * @documentation https://www.beeq.design/3d466e231/p/5793a9-date-picker
- * @status stable
+ * @documentation https://storybook.beeq.design/?path=/docs/components-date-picker--docs
+ *
+ * @status experimental
  *
  * @dependency bq-button
  * @dependency bq-dropdown
@@ -35,307 +33,401 @@ import type { DaysOfWeek, TDatePickerType } from './bq-date-picker.types';
  *
  * @attr {boolean} autofocus - If `true`, the Date picker input will be focused on component render.
  * @attr {string} clear-button-label - The clear button aria label.
+ * @attr {string} calendar-button-label - The aria-label for the calendar trigger button.
  * @attr {boolean} disable-clear - If `true`, the clear button won't be displayed.
  * @attr {boolean} disabled - Indicates whether the Date picker input is disabled or not.
- * @attr {number} distance - Represents the distance (gutter or margin) between the Date picker panel and the input element.
- * @attr {0 | 1 | 2 | 3 | 4 | 5 | 6} first-day-of-week - The first day of the week, where Sunday is 0, Monday is 1, etc.
- * @attr {Intl.DateTimeFormatOptions} format-options - The options to use when formatting the displayed value. Details: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat#using_options
- * @attr {string} form - The ID of the form that the Date picker input belongs to.
- * @attr {string} form-validation-message - The native form validation message (mandatory if `required` is set).
- * @attr {function} is-date-disallowed - A function that takes a date and returns true if the date should not be selectable.
- * @attr {Intl.LocalesArgument} locale - The locale for formatting dates. If not set, will use the browser's locale. Details: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument
- * @attr {string} max - The latest date that can be selected.
- * @attr {string} min - The earliest date that can be selected.
- * @attr {number} months - Number of months to show when range is `true`.
- * @attr {string} name - The Date picker input name.
- * @attr {boolean} open - If `true`, the Date picker panel will be visible.
- * @attr {string} panel-height - When set, it will override the height of the Date picker panel.
- * @attr {"top" | "right" | "bottom" | "left" | "top-start" | "top-end" | "right-start" | "right-end" | "bottom-start" | "bottom-end" | "left-start" | "left-end"} placement - Position of the Date picker panel.
- * @attr {boolean} required - Indicates whether or not the Date picker input is required to be filled out before submitting the form.
- * @attr {number} skidding - Represents the skidding between the Date picker panel and the input element.
- * @attr {boolean} show-outside-days - Whether to show days outside the month.
- * @attr {string} strategy - Defines the strategy to position the Date picker panel.
- * @attr {string} tentative - The date that is tentatively selected, e.g. the start of a range selection.
- * @attr {"single" | "multi" | "range"} type - It defines how the calendar will behave, allowing single date selection, range selection, or multiple date selection.
- * @attr {"error" | "none" | "success" | "warning"} validation-status - The validation status of the Select input.
- * @attr {string} value - The select input value represents the currently selected date or range and can be used to reset the field to a previous value.
+ * @attr {number} distance - Represents the distance between the panel and the input.
+ * @attr {0 | 1 | 2 | 3 | 4 | 5 | 6} first-day-of-week - The first day of the week (0 = Sunday).
+ * @attr {Intl.DateTimeFormatOptions} format-options - Display formatting options.
+ * @attr {string} form - The form ID the input belongs to.
+ * @attr {string} form-validation-message - Custom native form validation message.
+ * @attr {"days" | "months" | "years"} initial-view - The view to open when the panel first opens.
+ * @attr {function} is-date-disallowed - Predicate that marks specific dates as unselectable.
+ * @attr {Intl.LocalesArgument} locale - Locale used for formatting.
+ * @attr {string} max - Latest selectable date (ISO).
+ * @attr {string} min - Earliest selectable date (ISO).
+ * @attr {number} months - Number of month panels to render side by side (range/multi). Capped at 2.
+ * @attr {"single" | "months"} months-per-view - Prev/Next step size when multi-month is enabled.
+ * @attr {string} name - Input name.
+ * @attr {boolean} open - If `true`, the panel is visible.
+ * @attr {string} panel-height - Overrides the height of the panel.
+ * @attr {string} placeholder - Input placeholder text.
+ * @attr {"top" | "right" | "bottom" | "left" | "top-start" | "top-end" | "right-start" | "right-end" | "bottom-start" | "bottom-end" | "left-start" | "left-end"} placement - Placement of the panel.
+ * @attr {boolean} required - Whether a value must be selected before submitting the form.
+ * @attr {boolean} show-outside-days - Whether to render days that belong to adjacent months.
+ * @attr {number} skidding - Skidding between the panel and the trigger.
+ * @attr {"fixed" | "absolute"} strategy - Positioning strategy for the panel.
+ * @attr {"single" | "multi" | "range"} type - Selection mode.
+ * @attr {"error" | "none" | "success" | "warning"} validation-status - Validation state.
+ * @attr {string} value - The current selection, as a wire-format string. Shape depends on `type` and `precision`:
+ *   • **single**: a single ISO token — `YYYY-MM-DD` (precision `day`), `YYYY-MM` (precision `month`), `YYYY` (precision `year`).
+ *   • **range**: `start/end` (two tokens joined with `/`) at the same precision.
+ *   • **multi**: space-separated tokens at the same precision.
+ *   Bounds (`min`/`max`) may be supplied at any of these precisions and are honoured accordingly.
+ * @attr {"day" | "month" | "year"} precision - Granularity of the value and of the calendar's initial view. Also drives which cells are selectable (day cells at `day`, month cells at `month`, year cells at `year`). Defaults to `"day"`.
  *
  * @method clear - Clears the selected value.
  *
- * @event bqBlur - Callback handler emitted when the input loses focus.
- * @event bqChange - Callback handler emitted when the input value has changed and the input loses focus.
- * @event bqClear - Callback handler emitted when the input value has been cleared.
- * @event bqFocus - Callback handler emitted when the input has received focus.
+ * @event bqBlur - Emitted when the input loses focus.
+ * @event bqChange - Emitted when the value changes.
+ * @event bqClear - Emitted when the value is cleared.
+ * @event bqFocus - Emitted when the input receives focus.
+ * @event bqViewChange - Emitted when the internal calendar view changes (days ↔ months ↔ years).
+ *
+ * @slot label - The label displayed above the input.
+ * @slot prefix - Content rendered before the input value.
+ * @slot suffix - Icon rendered inside the calendar trigger button (defaults to a calendar icon).
+ * @slot clear-icon - Icon used inside the clear button.
  *
  * @part base - The component's base wrapper.
- * @part button - The native HTML button used under the hood in the clear button.
- * @part calendar__button - Any button used in the calendar-month component.
- * @part calendar__button - Any button within the calendar-range component.
- * @part calendar__container - The calendar-range container for the entire component.
- * @part calendar__day - The buttons corresponding to each day in the calendar-month grid.
- * @part calendar__disabled - A button that is disabled due to min/max on the calendar-range component.
- * @part calendar__disallowed - Any day that has been disallowed via isDateDisallowed.
- * @part calendar__head - The calendar-month table's header row.
- * @part calendar__header - The calendar-range container for the heading and buttons.
- * @part calendar__heading - The calendar-month heading container that labels the month.
- * @part calendar__heading - The calendar-range heading containing the month and year.
- * @part calendar__next - The next page button on the calendar-range component.
- * @part calendar__outside - Any days which are outside the current month.
- * @part calendar__previous - The previous page button on the calendar-range component.
- * @part calendar__range-end - The day at the end of a date range.
- * @part calendar__range-inner - Any days between the start and end of a date range.
- * @part calendar__range-start - The day at the start of a date range.
- * @part calendar__selected - Any days which are selected.
- * @part calendar__table - The calendar-month <table> element.
- * @part calendar__td - The calendar-month table's body cells.
- * @part calendar__th - The calendar-month table's header cells.
- * @part calendar__today - The Today's day.
- * @part calendar__tr - Any row within the table on the calendar-month component.
- * @part calendar__week - The calendar-month table's body rows.
- * @part clear-btn - The clear button.
- * @part control - The input control wrapper.
- * @part input - The native HTML input element used under the hood.
  * @part label - The label slot container.
- * @part panel - The date picker panel container
+ * @part control - The input control wrapper.
  * @part prefix - The prefix slot container.
  * @part suffix - The suffix slot container.
+ * @part input - The native input element.
+ * @part clear-btn - The clear button.
+ * @part calendar-trigger - The calendar icon trigger button.
+ * @part button - Any button rendered inside the calendar (nav or day/month/year cell).
+ * @part panel - The dropdown panel container.
+ * @part calendar__container - The calendar panels wrapper.
+ * @part calendar__header - The header row (prev / title / next).
+ * @part calendar__heading - The header title button (or month label above a panel).
+ * @part calendar__previous - The previous navigation button.
+ * @part calendar__next - The next navigation button.
+ * @part calendar__table - The day-view `<table>` element.
+ * @part calendar__head - The day-view table header row wrapper.
+ * @part calendar__tr - Any row within the day-view table.
+ * @part calendar__th - The day-view weekday header cells.
+ * @part calendar__week - Body rows in the day-view table.
+ * @part calendar__td - Body cells in the day-view table.
+ * @part calendar__day - Any day button in the day view.
+ * @part calendar__today - The button representing today's date.
+ * @part calendar__selected - Any selected day.
+ * @part calendar__outside - Any day outside the visible month.
+ * @part calendar__disallowed - Any day rejected by `isDateDisallowed`.
+ * @part calendar__disabled - Any button disabled by min/max.
+ * @part calendar__range-start - The first day of a range selection.
+ * @part calendar__range-end - The last day of a range selection.
+ * @part calendar__range-inner - Days between the start and end of a range.
+ * @part calendar__months - The month-view grid.
+ * @part calendar__month - Any month button.
+ * @part calendar__month-selected - The currently selected month.
+ * @part calendar__years - The year-view grid.
+ * @part calendar__year - Any year button.
+ * @part calendar__year-selected - The currently selected year.
  *
- * @cssprop --bq-date-picker--background-color - Date picker background color.
- * @cssprop --bq-date-picker--border-color - Date picker border color.
- * @cssprop --bq-date-picker--border-color-disabled - Date picker border color when disabled.
- * @cssprop --bq-date-picker--border-color-focus - Date picker border color on focus.
- * @cssprop --bq-date-picker--border-radius - Date picker border radius.
- * @cssprop --bq-date-picker--border-style - Date picker border style.
- * @cssprop --bq-date-picker--border-width - Date picker border width.
- * @cssprop --bq-date-picker--currentDate-border-color - Date picker border color for current date.
- * @cssprop --bq-date-picker--currentDate-border-width - Date picker border width for current date.
- * @cssprop --bq-date-picker--day-size - Date picker button day size.
- * @cssprop --bq-date-picker--gap - Gap between Date picker content and prefix/suffix.
- * @cssprop --bq-date-picker--icon-size - Icon size to use in prefix/suffix and clear button.
- * @cssprop --bq-date-picker--label-margin-bottom - Date picker label margin bottom.
- * @cssprop --bq-date-picker--label-text-color - Date picker label text color.
- * @cssprop --bq-date-picker--label-text-size - Date picker label text size.
- * @cssprop --bq-date-picker--padding-end - Date picker padding end.
- * @cssprop --bq-date-picker--padding-start - Date picker padding start.
- * @cssprop --bq-date-picker--paddingY - Date picker padding top and bottom.
- * @cssprop --bq-date-picker--range-background-color - Background color for the selected date range in the date picker.
- * @cssprop --bq-date-picker--range-inner-background-color - Background color for the selected dates inside the date range in the date picker.
- * @cssprop --bq-date-picker--text-color - Date picker text color.
- * @cssprop --bq-date-picker--text-placeholder-color - Date picker placeholder text color.
- * @cssprop --bq-date-picker--text-size - Date picker text size.
+ * @cssprop --bq-date-picker--background-color - Input background color.
+ * @cssprop --bq-date-picker--border-color - Input border color.
+ * @cssprop --bq-date-picker--border-color-disabled - Border color when disabled.
+ * @cssprop --bq-date-picker--border-color-focus - Border color on focus.
+ * @cssprop --bq-date-picker--border-radius - Input border radius.
+ * @cssprop --bq-date-picker--border-style - Border style.
+ * @cssprop --bq-date-picker--border-width - Border width.
+ * @cssprop --bq-date-picker--currentDate-border-color - Border color for today's date.
+ * @cssprop --bq-date-picker--currentDate-border-width - Border width for today's date.
+ * @cssprop --bq-date-picker--day-size - Size of a day cell in the calendar.
+ * @cssprop --bq-date-picker--gap - Gap between the input content and prefix/suffix.
+ * @cssprop --bq-date-picker--header-title-color - Color of the per-panel month label in multi-panel view.
+ * @cssprop --bq-date-picker--icon-size - Size of the icons used in prefix/suffix/clear.
+ * @cssprop --bq-date-picker--label-margin-bottom - Space below the label.
+ * @cssprop --bq-date-picker--label-text-color - Label text color.
+ * @cssprop --bq-date-picker--label-text-size - Label text size.
+ * @cssprop --bq-date-picker--padding-end - Input padding end.
+ * @cssprop --bq-date-picker--padding-start - Input padding start.
+ * @cssprop --bq-date-picker--paddingY - Input vertical padding.
+ * @cssprop --bq-date-picker--range-background-color - Background color for range start/end days.
+ * @cssprop --bq-date-picker--range-inner-background-color - Background color for inner range days.
+ * @cssprop --bq-date-picker--row-gap - Vertical space between day-grid rows.
+ * @cssprop --bq-date-picker--text-color - Input text color.
+ * @cssprop --bq-date-picker--text-placeholder-color - Placeholder text color.
+ * @cssprop --bq-date-picker--text-size - Input text size.
+ * @cssprop --bq-date-picker--view-cell-background-hover - Hover background for day/month/year cells.
+ * @cssprop --bq-date-picker--view-cell-background-selected - Selected background for day/month/year cells.
+ * @cssprop --bq-date-picker--view-cell-height - Height of month/year cells.
+ * @cssprop --bq-date-picker--view-cell-radius - Border radius of day/month/year cells.
+ * @cssprop --bq-date-picker--view-cell-text-selected - Text color for selected day/month/year cells.
  */
 export declare class BqDatePicker {
-    private callyElem?;
+    /**
+     * Memoized parsed selection. Key encodes both `value` and `type` so cache
+     * misses invalidate correctly. Value derives from `value`; not promoted to
+     * `@State()` to preserve a single source of truth.
+     */
+    private cachedSelection?;
+    /** Sticky flag: last typed input couldn't be parsed. Cleared on next successful commit or `clear()`. */
+    private hasBadInput;
+    /** Initial `value` captured at load time, restored on form reset. */
+    private initialValue?;
     private inputElem?;
-    private isInternalUpdate;
+    /** Set while `commitSelection` writes back to `this.value`. */
+    private isCommittingSelection;
     private labelElem?;
+    /** Pending requestAnimationFrame id used by `focusButton`. */
+    private pendingFocusRAF?;
     private prefixElem?;
-    private suffixElem?;
+    private triggerBtnElem?;
     internals: ElementInternals;
     el: HTMLBqDatePickerElement;
-    isCallyLoaded: boolean;
-    focusedDate: string;
-    displayDate: string;
+    decadeStart: number;
+    displayDate?: string;
+    focusedISO: string;
+    focusedMonth: number;
+    focusedYear: number;
+    hasConstraintError: boolean;
     hasLabel: boolean;
     hasPrefix: boolean;
-    hasRangeEnd: boolean;
-    hasSuffix: boolean;
     hasValue: boolean;
-    /** If `true`, the Date picker input will be focused on component render */
+    tentativeHover?: string;
+    view: TCalendarView;
+    viewDate: Date;
+    /** If `true`, the Date picker input will be focused on component render. */
     autofocus: boolean;
-    /** The clear button aria label */
-    clearButtonLabel?: string;
-    /** If `true`, the clear button won't be displayed */
-    disableClear?: boolean;
+    /** The clear button aria label. */
+    clearButtonLabel: string;
+    /** The aria-label for the calendar trigger button. */
+    calendarButtonLabel: string;
+    /** If `true`, the clear button won't be displayed. */
+    disableClear: boolean;
+    /** Indicates whether the Date picker input is disabled or not. */
+    disabled: boolean;
+    /** Distance (gutter) between the Date picker panel and the input element. */
+    distance: number;
+    /** The first day of the week, where Sunday is 0, Monday is 1, etc. */
+    firstDayOfWeek: DaysOfWeek;
     /**
-     * Indicates whether the Date picker input is disabled or not.
-     * If `true`, the Date picker is disabled and cannot be interacted with.
-     */
-    disabled?: boolean;
-    /** Represents the distance (gutter or margin) between the Date picker panel and the input element. */
-    distance?: number;
-    /** The first day of the week, where Sunday is 0, Monday is 1, etc */
-    firstDayOfWeek?: DaysOfWeek;
-    /** The options to use when formatting the displayed value.
-     * Details: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat#using_options
+     * Options used when formatting the displayed value.
+     *
+     * When omitted, sensible defaults are picked based on `precision`:
+     * - `day`   → `{ day: 'numeric', month: 'short', year: 'numeric' }`
+     * - `month` → `{ month: 'long', year: 'numeric' }`
+     * - `year`  → `{ year: 'numeric' }`
      */
-    formatOptions: Intl.DateTimeFormatOptions;
-    /** The ID of the form that the Date picker input belongs to. */
+    formatOptions?: Intl.DateTimeFormatOptions;
+    /** The ID of the form the input belongs to. */
     form?: string;
-    /** The native form validation message (mandatory if `required` is set) */
+    /** Native form validation message (mandatory if `required` is set). */
     formValidationMessage?: string;
-    /** A function that takes a date and returns true if the date should not be selectable */
+    /** The view opened first when the panel becomes visible. */
+    initialView: TCalendarView;
+    /** Predicate that marks specific dates as unselectable. */
     isDateDisallowed?: (date: Date) => boolean;
-    /** The locale for formatting dates. If not set, will use the browser's locale.
-     * Details: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument
-     */
+    /** Locale used for formatting dates. */
     locale: Intl.LocalesArgument;
-    /** The latest date that can be selected */
+    /** Latest date that can be selected (ISO). */
     max?: string;
-    /** The earliest date that can be selected */
+    /** Earliest date that can be selected (ISO). */
     min?: string;
-    /** Number of months to show when range is `true` */
+    /**
+     * Number of months to show side by side (range / multi). Capped at 2.
+     * Larger values are silently clamped to keep the popover from overflowing
+     * the viewport and to preserve keyboard navigation semantics.
+     */
     months: number;
     /**
-     * Specifies how the next/previous buttons should navigate the calendar.
-     * - single: The buttons will navigate by a single month at a time.
-     * - months: The buttons will navigate by the number of months displayed per view.
+     * How the next/previous buttons should navigate the calendar.
+     * - single: navigate one month at a time.
+     * - months: navigate by the number of months displayed.
      */
-    monthsPerView: 'single' | 'months';
+    monthsPerView: TMonthsPerView;
     /** The Date picker input name. */
     name: string;
-    /** If `true`, the Date picker panel will be visible. */
-    open?: boolean;
-    /** When set, it will override the height of the Date picker panel. */
+    /** If `true`, the panel is visible. */
+    open: boolean;
+    /** Overrides the height of the Date picker panel. */
     panelHeight?: string;
-    /** The Date picker input placeholder text value */
+    /** Placeholder text shown when no value is selected. */
     placeholder?: string;
-    /** Position of the Date picker panel */
-    placement?: Placement;
-    /** Indicates whether or not the Date picker input is required to be filled out before submitting the form. */
-    required?: boolean;
-    /** Represents the skidding between the Date picker panel and the input element. */
-    skidding?: number;
-    /** Whether to show days outside the month */
+    /** Position of the Date picker panel. */
+    placement: Placement;
+    /**
+     * Precision of the value produced by the picker.
+     *
+     * - `day`   → `YYYY-MM-DD` (default). Standard drill-down.
+     * - `month` → `YYYY-MM`. Selection commits on the months view; no days view.
+     * - `year`  → `YYYY`. Selection commits on the years view; no months/days view.
+     *
+     * When precision is coarser than day, `initialView` is forced to match and
+     * the header title cycles through the views available for that precision.
+     */
+    precision: TDatePrecision;
+    /** Whether a value must be selected before submitting the form. */
+    required: boolean;
+    /** Skidding between the panel and the input element. */
+    skidding: number;
+    /** Whether to render days outside the current month. */
     showOutsideDays: boolean;
-    /** Defines the strategy to position the Date picker panel */
-    strategy?: 'fixed' | 'absolute';
-    /** The date that is tentatively selected e.g. the start of a range selection  */
-    tentative?: string;
-    /** It defines how the calendar will behave, allowing single date selection, range selection, or multiple date selection */
+    /** Positioning strategy for the panel. */
+    strategy: TFloatingStrategy;
+    /**
+     * Selection type.
+     * - `single`: single date.
+     * - `multi`: multiple discrete dates.
+     * - `range`: contiguous range.
+     */
     type: TDatePickerType;
+    /** Validation state applied to the input. */
+    validationStatus: TInputValidation;
     /**
-     * The validation status of the Select input.
+     * Currently selected value, in the precision-aware wire format:
+     * - `precision="day"`   → tokens are `YYYY-MM-DD`
+     * - `precision="month"` → tokens are `YYYY-MM`
+     * - `precision="year"`  → tokens are `YYYY`
      *
-     * @remarks
-     * This property is used to indicate the validation status of the select input. It can be set to one of the following values:
-     * - `'none'`: No validation status is set.
-     * - `'error'`: The input has a validation error.
-     * - `'warning'`: The input has a validation warning.
-     * - `'success'`: The input has passed validation.
+     * How multiple tokens are combined depends on `type`:
+     * - `single` → a single token (e.g. `"2025-05-15"`, `"2025-05"`, `"2025"`)
+     * - `range`  → `"start/end"` — two tokens joined with `/`
+     * - `multi`  → space-separated tokens (e.g. `"2025-05-15 2025-05-20"`)
      */
-    validationStatus: TInputValidation;
-    /** The select input value represents the currently selected date or range and can be used to reset the field to a previous value.
-     * All dates are expected in ISO-8601 format (YYYY-MM-DD). */
-    value: string;
-    handleValueChange(newValue: string, oldValue: string): void;
+    value: string | undefined;
+    handleValueChange(newValue: string | undefined, oldValue: string | undefined): void;
+    handleFormattingChange(): void;
+    handleTypeChange(): void;
+    handlePrecisionChange(): void;
+    handleBoundsChange(): void;
+    handleRequiredChange(): void;
     checkPropValues(): void;
-    /** Callback handler emitted when the input loses focus */
+    handleMonthsChange(): void;
+    handleOpen(open: boolean): void;
+    handleViewChange(next: TCalendarView, prev: TCalendarView): void;
+    /** Callback handler emitted when the input loses focus. */
     bqBlur: EventEmitter<HTMLBqDatePickerElement>;
     /**
-     * Callback handler emitted when the input value has changed and the input loses focus.
-     * This handler is called whenever the user finishes typing or pasting text into the input field and then clicks outside of the input field.
+     * Callback handler emitted when the input value changes.
      */
     bqChange: EventEmitter<{
-        value: string;
+        value: string | undefined;
         el: HTMLBqDatePickerElement;
     }>;
-    /** Callback handler emitted when the input value has been cleared */
+    /** Callback handler emitted when the value is cleared. */
     bqClear: EventEmitter<HTMLBqDatePickerElement>;
-    /** Callback handler emitted when the input has received focus */
+    /** Callback handler emitted when the input receives focus. */
     bqFocus: EventEmitter<HTMLBqDatePickerElement>;
-    componentWillLoad(): Promise<void>;
+    /**
+     * Callback handler emitted when the internal calendar view changes
+     * (e.g. from `days` to `months`, or from `years` back to `days`).
+     */
+    bqViewChange: EventEmitter<{
+        view: TCalendarView;
+        el: HTMLBqDatePickerElement;
+    }>;
+    componentWillLoad(): void;
     componentDidLoad(): void;
-    componentDidRender(): void;
+    disconnectedCallback(): void;
     formAssociatedCallback(): void;
     formResetCallback(): void;
     handleOpenChange(ev: CustomEvent<{
         open: boolean;
     }>): void;
-    handleClickOutside(ev: MouseEvent): void;
     /**
-     * Clears the selected value.
-     * @returns {Promise<void>}
+     * Clears the selected value and any pending validation state (bad input,
+     * bounds overflow). Emits `bqClear`. No-op when the component is disabled.
+     *
+     * @returns A promise that resolves once the value has been cleared.
      */
     clear(): Promise<void>;
-    /**
-     * Handles the blur event for the date picker input.
-     * @returns {void}
-     */
     private handleBlur;
-    /**
-     * Handles the focus event for the date picker input.
-     * @returns {void}
-     */
     private handleFocus;
+    private handleInputChange;
+    private handleClearClick;
+    /** Toggles the calendar panel open/closed when the trigger button is activated. */
+    private handleTriggerClick;
     /**
-     * Updates the focused date in the calendar component.
-     * Falls back to today's date if no value is set.
-     * @returns {void}
-     */
-    private setFocusedDate;
-    /**
-     * Handles user input changes with locale-aware date parsing.
-     * Validates against disallowed dates and min/max constraints.
-     * @param {Event} ev - The change event.
-     * @returns {void}
-     */
-    private handleChange;
-    /**
-     * Handles the change event when the user selects a date in the calendar component.
-     * @param {Event} ev - The change event.
-     * @returns {void}
-     */
-    private handleCalendarChange;
-    /**
-     * Handles the range start event when the user starts selecting a date range
-     * @param {CustomEvent} ev - The range start event.
-     * @returns {void}
-     */
-    private handleCalendarRangeStart;
-    /**
-     * Handles the range end event when the user finishes selecting a date range
-     * @returns {void}
+     * Handles keyboard shortcuts on the text input.
+     * - `ArrowDown` / `Alt+ArrowDown` → open panel and focus active cell.
+     * - `Escape` → close panel (focus stays on input).
      */
-    private handleCalendarRangeEnd;
+    private handleInputKeyDown;
+    private clearValue;
+    private handleSlotChange;
+    private updateFormValidity;
     /**
-     * Handles the clear click event when the user clicks the clear button
-     * @param {CustomEvent} ev - The clear click event.
-     * @returns {void}
+     * Recompute all state derived from the public `value` (form value,
+     * `hasValue`, formatted display). Called from `value` and any prop that
+     * affects display formatting (`type`, `locale`, `formatOptions`).
      */
-    private handleClearClick;
+    private syncDerivedFromValue;
     /**
-     * Clears the value of the date picker input.
-     * @returns {void}
+     * Runs the full form-validity pipeline in a consistent order: `required`
+     * → bounds → `badInput`. Multiple failing constraints are unioned into a
+     * single `setValidity` call.
      */
-    private clearValue;
+    private syncValidity;
+    /** Returns `rangeUnderflow` / `rangeOverflow` flags for the current selection. */
+    private computeBoundsValidityFlags;
+    private clampMonths;
     /**
-     * Handles the slot change event when the slots content changes
-     * @returns {void}
+     * Align the internal `viewDate` / `focused*` state with the current value.
+     * Called when the panel opens and whenever an *external* prop change
+     * invalidates the current view (value, type, precision, min/max). Internal
+     * commits skip this via `isCommittingSelection` so the user's navigated
+     * year isn't clobbered by a subsequent multi/range selection.
+     *
+     * Uses `parseValue` (precision-aware, always returns full ISO dates) rather
+     * than a raw `YYYY-MM-DD` regex so that month/year wire values like
+     * `"2025-05"` or `"2025"` land on the right cell instead of falling back
+     * to today.
      */
-    private handleSlotChange;
+    private syncViewToValue;
+    private get selection();
     /**
-     * Generates a calendar month element
-     * @param {number} offset - The offset of the calendar month.
-     * @param {string} className - The class name of the calendar month.
-     * @returns {JSX.Element | null} The calendar month element.
+     * Effective `Intl.DateTimeFormatOptions` — user-provided when set, otherwise
+     * the precision-appropriate default. Prevents a `month` picker from
+     * accidentally rendering "1 May 2026" when the consumer just sets
+     * `precision="month"` without overriding `formatOptions`.
      */
-    private generateCalendarMonth;
+    private get effectiveFormatOptions();
+    /** Map a precision value to the calendar view that commits selections. */
+    private precisionToView;
+    private get tentativeRange();
     /**
-     * Generates an array of Elements representing the calendar months.
-     *
-     * If the type of the date picker is 'range' or 'multi' and the number of months is specified,
-     * it generates an array of calendar months with the specified length. Each month will have an offset
-     * and a class name based on its position in the array. The offset is used to determine the month to display,
-     * and the class name is used for responsive design.
+     * Return the date that view transitions (days ⇄ months ⇄ years) should
+     * center the focus on.
      *
-     * If the type of the date picker is not 'range' or 'multi', or if the number of months is not specified,
-     * it generates an array with a single calendar month.
-     *
-     * @returns {JSX.Element[]} An array of elements representing the calendar months.
+     * Priority:
+     * 1. First entry of the current selection — for `range` this is the start
+     *    date (selection is sorted on parse), for `multi` it is the earliest.
+     * 2. Otherwise the currently displayed `viewDate` (i.e. the month/year the
+     *    user has navigated to with prev/next).
      */
-    private generateCalendarMonths;
+    private getViewFocusReference;
+    private handleHeaderTitleClick;
+    private handleHeaderPrev;
+    private handleHeaderNext;
+    private handleMonthSelect;
+    private handleYearSelect;
+    private handleDaySelect;
     /**
-     * Updates the form validity of the date picker input.
-     * @returns {void}
+     * Shared commit path used by day / month / year selection. Keeps the
+     * selection logic (single/multi/range) and post-commit behaviour (event,
+     * open state, tentative hover, view sync) identical across precisions.
      */
-    private updateFormValidity;
+    private commitSelection;
+    private handleDayHover;
+    private handleDayFocus;
+    private getRTLDirection;
+    private moveFocusedDay;
+    private moveFocusedDayHome;
+    private moveFocusedDayEnd;
+    private pageFocusedMonth;
+    private selectFocusedDay;
+    private handleDayGridKeyDown;
+    private getGridColumns;
+    private handleMonthGridKeyDown;
+    private handleYearGridKeyDown;
+    private focusButton;
     /**
-     * Returns the Cally calendar component tag name based on the picker type.
-     * Maps 'single' → 'calendar-date', 'multi' → 'calendar-multi', 'range' → 'calendar-range'
-     *
-     * @returns The Cally calendar component tag name.
+     * Focus the currently active cell for the visible view. Called after the
+     * popup opens so keyboard users don't have to tab into the calendar.
      */
-    private get calendarType();
+    private focusActiveCell;
+    private getMonthCount;
+    private getHeaderLabel;
+    private getHeaderTitleLabel;
+    private getPreviousLabel;
+    private getNextLabel;
+    private renderDayPanels;
+    private renderMonthsView;
+    private renderYearsView;
+    private renderView;
     render(): any;
 }