@brickclay-org/ui 0.1.87 → 0.1.88

package/index.d.ts

@@ -1,13 +1,13 @@
 import * as _angular_core from '@angular/core';
-import { EventEmitter, OnInit, OnDestroy, OnChanges, ElementRef, Renderer2, SimpleChanges, AfterViewInit, QueryList, ComponentRef, Type, InjectionToken, NgZone, ChangeDetectorRef, TemplateRef, WritableSignal } from '@angular/core';
+import { EventEmitter, OnInit, OnDestroy, OnChanges, ElementRef, SimpleChanges, AfterViewInit, QueryList, ComponentRef, Type, InjectionToken, NgZone, Renderer2, ChangeDetectorRef, TemplateRef, WritableSignal } from '@angular/core';
 import { ControlValueAccessor, Validator, AbstractControl, ValidationErrors, NgControl, NgModel } from '@angular/forms';
+import * as i2 from '@angular/cdk/overlay';
+import { CdkConnectedOverlay, ConnectedPosition, ConnectedOverlayPositionChange, ScrollStrategy } from '@angular/cdk/overlay';
 import * as rxjs from 'rxjs';
 import { Observable } from 'rxjs';
 import * as i1 from '@angular/common';
 import * as i1$3 from '@angular/cdk/drag-drop';
 import { CdkDragDrop, CdkDragMove, CdkDragStart } from '@angular/cdk/drag-drop';
-import * as i2 from '@angular/cdk/overlay';
-import { CdkConnectedOverlay, ConnectedOverlayPositionChange, ConnectedPosition, ScrollStrategy } from '@angular/cdk/overlay';
 import { NgxMaskDirective } from 'ngx-mask';
 import * as i1$2 from '@angular/cdk/dialog';
 import { CdkDialogContainer, DialogRef } from '@angular/cdk/dialog';
@@ -66,6 +66,16 @@ interface CustomRangesConfig {
 }
 declare class BkCalendarManagerService {
     private calendarInstances;
+    /**
+     * Separate from {@link calendarInstances} on purpose: a bk-time-picker embedded inside an open
+     * bk-custom-calendar (enableTimepicker) must NOT close its own parent calendar when it opens.
+     * If time-pickers shared the calendar registry, opening the embedded picker would call
+     * closeAllExcept(thatPicker'sCloseFn) — which closes the parent calendar too, since its
+     * close-fn is in the same set and isn't the "except" one. Keeping the registries independent
+     * means time-pickers only ever coordinate with other time-pickers, calendars only with other
+     * calendars — each family closes its own siblings, never the other family.
+     */
+    private timePickerInstances;
     private closeAllSubject;
     closeAll$: rxjs.Observable<void>;
     customRanges: Record<string, CalendarRange>;
@@ -86,6 +96,16 @@ declare class BkCalendarManagerService {
      * Close all calendars except the one being opened
      */
     closeAllExcept(exceptCloseFn: () => void): void;
+    /**
+     * Register a time-picker instance with its close function — separate registry from calendars,
+     * see {@link timePickerInstances}.
+     */
+    registerTimePicker(closeFn: () => void): () => void;
+    /**
+     * Close all time-pickers except the one being opened. Never touches calendarInstances — see
+     * {@link timePickerInstances}.
+     */
+    closeAllTimePickersExcept(exceptCloseFn: () => void): void;
     /**
      * Close all calendars
      */
@@ -95,6 +115,43 @@ declare class BkCalendarManagerService {
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<BkCalendarManagerService>;
 }
 
+/**
+ * 1-based month numbers (January = 1 … December = 12) — deliberately NOT JS `Date`'s 0-based
+ * `getMonth()` convention, so callers reading `allowedMonths` see the calendar month number they'd
+ * expect. Backs {@link BkCustomCalendar.allowedMonths} so callers can write `CalendarMonth.March`
+ * instead of a bare `3`. {@link BkCustomCalendar.allowedMonthsZeroBased} converts back to 0-based
+ * for every internal comparison against `Date.getMonth()`/the month grid's loop index.
+ */
+declare enum CalendarMonth {
+    January = 1,
+    February = 2,
+    March = 3,
+    April = 4,
+    May = 5,
+    June = 6,
+    July = 7,
+    August = 8,
+    September = 9,
+    October = 10,
+    November = 11,
+    December = 12
+}
+/**
+ * 1-based day-of-week numbers (Sunday = 1 … Saturday = 7) — same reasoning as {@link
+ * CalendarMonth}: deliberately NOT JS `Date`'s 0-based `getDay()` convention, so a bare `0` in
+ * `allowedDaysOfWeek` can't be mistaken for "unset" or silently match the wrong day. Backs
+ * {@link BkCustomCalendar.allowedDaysOfWeek}. {@link BkCustomCalendar.allowedDaysOfWeekZeroBased}
+ * converts back to 0-based for every internal comparison against `Date.getDay()`.
+ */
+declare enum CalendarWeekday {
+    Sunday = 1,
+    Monday = 2,
+    Tuesday = 3,
+    Wednesday = 4,
+    Thursday = 5,
+    Friday = 6,
+    Saturday = 7
+}
 declare class CalendarSelection {
     startDate: string | null;
     endDate: string | null;
@@ -103,23 +160,53 @@ declare class CalendarSelection {
     /** End time in 12-hour format with AM/PM (e.g. "2:00 AM"). */
     endTime: string | null;
     selectedDates?: string[];
+    /**
+     * Set only when `pickerView` is 'month' (paired with {@link selectedYear}) — the selected
+     * month, 0-11. `startDate`/`endDate` stay null in this mode; there is no day-level value.
+     */
+    selectedMonth?: number | null;
+    /** Set when `pickerView` is 'year' (alone) or 'month' (paired with {@link selectedMonth}). */
+    selectedYear?: number | null;
 }
 declare class BkCustomCalendar implements OnInit, OnDestroy, OnChanges, ControlValueAccessor, Validator {
     private calendarManager;
-    private renderer;
     enableTimepicker: boolean;
     autoApply: boolean;
     closeOnAutoApply: boolean;
     showCancel: boolean;
     linkedCalendars: boolean;
     singleDatePicker: boolean;
+    /**
+     * Restricts selection to just a month or just a year, skipping the day grid entirely. Only
+     * takes effect with `singleDatePicker` and `!dualCalendar` — ignored (falls back to normal
+     * day-grid behaviour) for range/dual selection, which isn't supported yet. Picking a
+     * month/year is the final action: it commits immediately (like `autoApply`) and populates only
+     * `selectedMonth`/`selectedYear` on the emitted {@link CalendarSelection} — `startDate` stays
+     * null, there is no day-level value to give it.
+     */
+    pickerView: 'day' | 'month' | 'year';
     showWeekNumbers: boolean;
     showISOWeekNumbers: boolean;
     customRangeDirection: boolean;
     lockStartDate: boolean;
-    position: 'center' | 'left' | 'right';
-    /** Vertical placement relative to the input. When explicitly set, overrides viewport-space detection entirely. */
-    popupPosition?: 'top' | 'bottom';
+    /**
+     * @deprecated Use {@link opens} instead — same 'left' | 'right' | 'center' values, same meaning.
+     * Kept, and still honoured, only so existing `[position]="..."` bindings keep working; when set,
+     * it takes priority over `opens` (see {@link horizontalAlign}). No known consumers currently set
+     * this — safe to remove once none do.
+     */
+    position?: 'center' | 'left' | 'right';
+    /**
+     * Preferred vertical side of the popup relative to the input. The opposite side is always
+     * offered as a CDK flip fallback (see {@link computeCalendarPositions}) — there is no way to
+     * lock the popup to one side regardless of available space.
+     */
+    popupPosition: 'top' | 'bottom';
+    /**
+     * @deprecated No-op. Use {@link popupPosition} ('bottom' | 'top') instead — 'down'/'up' were
+     * renamed to 'bottom'/'top' to match it. Auto-flip is always on now, so this no longer has a
+     * "never flips" mode to opt out of either. Safe to remove from call sites.
+     */
     drop: 'up' | 'down';
     dualCalendar: boolean;
     showRanges: boolean;
@@ -132,25 +219,80 @@ declare class BkCustomCalendar implements OnInit, OnDestroy, OnChanges, ControlV
     multiDateSelection: boolean;
     maxDate?: Date;
     minDate?: Date;
+    /**
+     * Allow-list of selectable months, for the month grid — e.g.
+     * `[CalendarMonth.January, CalendarMonth.March]` for Jan/Mar only. 1-based (January = 1 …
+     * December = 12) — a bare `0` won't match January here, unlike JS `Date.getMonth()`. Unset
+     * (default) means no restriction beyond `minDate`/`maxDate`. Combines with them: a month must
+     * satisfy both to be selectable. Backs every month grid ({@link isMonthDisabled}) — `pickerView`
+     * 'month' and the day grid's own month quick-pick alike.
+     */
+    allowedMonths?: CalendarMonth[];
+    /**
+     * Allow-list of selectable years, for the year grid — e.g. `[2025, 2027]`. Unset (default) means
+     * no restriction beyond `minDate`/`maxDate`. Combines with them the same way as
+     * {@link allowedMonths}. Backs every year grid ({@link isYearDisabled}).
+     */
+    allowedYears?: number[];
+    /**
+     * Allow-list of selectable weekdays, for the day grid — e.g.
+     * `[CalendarWeekday.Monday, ..., CalendarWeekday.Friday]` for business days only. 1-based
+     * (Sunday = 1 … Saturday = 7) — a bare `0` won't match Sunday here, unlike JS `Date.getDay()`.
+     * Unset (default) means no restriction. Unlike `allowedMonths`/`allowedYears`, this is
+     * day-granularity only — it does NOT disable a whole month/year grid cell just because some of
+     * its days fall on a disallowed weekday, since a month/year still has other selectable days.
+     * Combines (AND) with every other constraint. Backs {@link isDateDisabled}.
+     */
+    allowedDaysOfWeek?: CalendarWeekday[];
+    /**
+     * Blackout list — specific dates that are never selectable regardless of every other
+     * constraint (minDate/maxDate/allowedMonths/allowedYears/allowedDaysOfWeek all still apply on
+     * top; this only ever narrows further, e.g. for holidays or dates already booked elsewhere).
+     * Compared by calendar day (year/month/date), time-of-day is ignored. Backs {@link
+     * isDateDisabled}.
+     */
+    disabledDates?: Date[];
+    /**
+     * Allow-list of specific selectable dates — same AND semantics as `allowedMonths`/
+     * `allowedYears`/`allowedDaysOfWeek` (a date must satisfy this AND every other constraint that's
+     * set, not "these dates are selectable regardless of the rest"). Compared by calendar day
+     * (year/month/date), time-of-day is ignored. Backs {@link isDateDisabled}.
+     */
+    allowedDates?: Date[];
     placeholder: string;
     opens: 'left' | 'right' | 'center';
     inline: boolean;
     compact: boolean;
-    autoPosition: boolean;
+    /**
+     * @deprecated No-op, kept only so existing `[appendToBody]="true"` bindings don't break.
+     * The popup now always positions via Angular CDK Overlay, which portals into the shared
+     * `cdk-overlay-container` unconditionally — the exact clipping/stacking escape this input used
+     * to opt into by hand is now the only behaviour there is. Safe to remove from call sites.
+     */
     appendToBody: boolean;
+    /**
+     * Extra px CDK keeps clear of the viewport edges when flipping/pushing the popup. CDK's
+     * flip/push only avoids the window edges — it has no idea a sticky app header or a sticky
+     * table `<thead>` occupies part of that space, and will happily flip/push the popup underneath
+     * one. Set this to the height of any such sticky/fixed chrome the popup must never land under.
+     * Same fix, same reasoning, as `bk-popover.viewportMargin`.
+     */
+    viewportMargin: number;
+    /**
+     * Classes applied to the CDK overlay pane (`cdkConnectedOverlayPanelClass`). z-index overrides
+     * MUST go here (e.g. `panelClass="!z-[1100]"`) — the pane already establishes its own stacking
+     * context once portalled, so setting z-index anywhere else (the calendar's host element, a
+     * consumer's own wrapper) is a no-op. Same convention as `bk-popover.panelClass`.
+     */
+    panelClass: string | string[];
     isDisplayCrossIcon: boolean;
     hasError: boolean;
     errorMessage: string;
     selected: EventEmitter<CalendarSelection>;
     inputWrapper: ElementRef<HTMLDivElement>;
     calendarPopupRef?: ElementRef<HTMLDivElement>;
-    /** Used when appendToBody is true to position the popup in viewport coordinates */
-    dropdownStyle: {
-        top?: string;
-        bottom?: string;
-        left?: string;
-    };
-    /** Resolved after layout; used for CSS `drop-up` and appendToBody positioning with viewport flip */
+    calendarOverlay?: CdkConnectedOverlay;
+    /** Resolved from CDK's (positionChange); drives the CSS `drop-up` class + slide direction. */
     popupPlacementAbove: boolean;
     opened: EventEmitter<void>;
     closed: EventEmitter<void>;
@@ -197,9 +339,21 @@ declare class BkCustomCalendar implements OnInit, OnDestroy, OnChanges, ControlV
         day: number;
         currentMonth: boolean;
     }[][];
+    /** Drill-down state for the header's month/year quick-pick. Independent per side in dual mode. */
+    view: 'days' | 'months' | 'years';
+    leftView: 'days' | 'months' | 'years';
+    rightView: 'days' | 'months' | 'years';
+    /** First year shown in the currently open year-grid (a 12-year page). */
+    yearRangeStart: number;
+    leftYearRangeStart: number;
+    rightYearRangeStart: number;
+    readonly monthNamesShort: string[];
     startDate: Date | null;
     endDate: Date | null;
     selectedDates: Date[];
+    /** Committed selection for `pickerView` 'month' (paired with {@link selectedYearValue}) / 'year'. */
+    selectedMonthValue: number | null;
+    selectedYearValue: number | null;
     disableHighlight: boolean;
     hoveredDate: Date | null;
     minuteInputValues: {
@@ -238,25 +392,32 @@ declare class BkCustomCalendar implements OnInit, OnDestroy, OnChanges, ControlV
     private unregisterFn?;
     private closeAllSubscription?;
     private closeFn?;
-    constructor(calendarManager: BkCalendarManagerService, renderer: Renderer2);
+    constructor(calendarManager: BkCalendarManagerService);
+    /**
+     * CDK connected-overlay positions for the current open. Rebuilt each time the popup opens (see
+     * {@link toggle}) from `opens` (horizontal alignment) and `popupPosition` (which vertical side is
+     * primary). Auto-flip is always on — the opposite vertical side is always offered as a fallback,
+     * the same as `opens`'s horizontal push; there is no opt-out flag, matching `bk-select`/
+     * `bk-popover`. `cdkConnectedOverlayPush` (see the template) stays on regardless, so CDK slides
+     * the popup back on-screen horizontally instead of the old hand-rolled flip-then-clamp in
+     * computePopupLeft() — the same push-based approach bk-popover uses.
+     */
+    calendarPositions: ConnectedPosition[];
+    /** Tags each entry in {@link calendarPositions} with whether it places the popup above the
+     *  trigger, so `onPositionChange` can read back which one CDK actually used. Matched by field
+     *  value, not object identity — CDK reconstructs its own ConnectedPosition objects internally. */
+    private positionMeta;
+    /** Horizontal alignment from `opens` (deprecated `position` wins when explicitly set — see its
+     *  JSDoc): 'left' aligns left edges (opens rightwards, the default), 'right' aligns right edges
+     *  (opens leftwards), 'center' centers on the trigger. */
+    private horizontalAlign;
+    private buildVerticalPosition;
     /**
-     * appendToBody popup relocation.
-     *
-     * `appendToBody` uses `position: fixed`, which only anchors to the viewport when NO ancestor
-     * establishes a containing block (transform / filter / perspective / will-change / contain /
-     * backdrop-filter). Consumers frequently place the calendar inside such an ancestor (an animated
-     * panel, a CSS-transformed modal, etc.), which silently re-anchors the fixed popup and pushes it
-     * off-position. To be robust everywhere we physically move the popup node to <body> while it is
-     * open, then move it back before Angular's *ngIf tears it down. Angular keeps managing the node by
-     * reference after the move, so its event bindings, change detection, and emulated-encapsulation
-     * styles all continue to work.
-     */
-    private popupMovedToBody;
-    private popupOriginalParent;
-    private popupOriginalNextSibling;
-    private movePopupToBody;
-    /** Return the popup to its original DOM slot so *ngIf can destroy it cleanly (safe to call twice). */
-    private restorePopupFromBody;
+     * (Re)computes {@link calendarPositions}: `popupPosition` picks the preferred/primary side, and
+     * the opposite side always follows as CDK's flip fallback — used only when the preferred side
+     * genuinely doesn't fit the viewport (`viewportMargin` included).
+     */
+    private computeCalendarPositions;
     /** Weekday headers; falls back to Mon–Sun if the input is not length 7. */
     get resolvedWeekDayLabels(): string[];
     /** When dual range mode, Apply is blocked until both endpoints exist. */
@@ -270,8 +431,6 @@ declare class BkCustomCalendar implements OnInit, OnDestroy, OnChanges, ControlV
     /** Discard in-popup draft and restore last committed value from {@link selectedValue}. */
     private revertSingleDateDraftIfNeeded;
     private finishPopupDismissal;
-    /** User preference before viewport adjustment (only used when popupPosition is not explicitly set). */
-    private preferPopupAbove;
     private resolveCustomRangesFromInputsOrService;
     private labelToJsWeekday;
     private getWeekStartDayIndex;
@@ -289,15 +448,27 @@ declare class BkCustomCalendar implements OnInit, OnDestroy, OnChanges, ControlV
     private applyValueToState;
     /** Format to "H:MM AM/PM" string. */
     private formatTimeToAmPm;
-    onClickOutside(event: MouseEvent): void;
-    /** True while capture-phase scroll + resize listeners are attached (only while the popup is open). */
+    /**
+     * CDK's overlay origin already excludes clicks on the trigger from outside-click dispatch by
+     * design (same note in bk-popover's onOverlayOutsideClick), so the input's own (click)="toggle()"
+     * stays the sole opener/closer via the trigger.
+     */
+    onOverlayOutsideClick(): void;
+    /** Fires whenever CDK (re)applies a position, including the first one after open. Reads back
+     *  which of `positionMeta`'s tagged entries CDK actually used, to drive the `drop-up` CSS class
+     *  (and its slide-up/slide-down animation) — the same value computePlacementAbove() used to. */
+    onPositionChange(event: ConnectedOverlayPositionChange): void;
+    /** True while the capture-phase scroll/resize listener is attached (only while the popup is open). */
     private viewportListenersAttached;
     /** Pending rAF id so bursts of scroll events collapse into one layout pass. */
     private viewportRafId;
     /**
-     * Recipe steps 2 & 4: while the popup is open, keep it glued to the trigger as the page
-     * (or any nested scroll container) scrolls, and dismiss it once the trigger leaves the viewport.
-     * Throttled through requestAnimationFrame to avoid layout thrash during fast scrolling.
+     * CDK's own scroll strategy only reacts to real `document`/`window` scroll — it has no way to
+     * know an app shell might scroll a nested container instead (a dashboard layout with a fixed
+     * header/sidebar and a scrollable content pane, a dialog body, etc). A capture-phase listener on
+     * `document` still sees scroll events fired on any descendant scrollable element (scroll doesn't
+     * bubble, but capture does) — the same trick bk-popover uses. Throttled through
+     * requestAnimationFrame to avoid layout thrash during fast scrolling.
      */
     private readonly onViewportChange;
     private handleViewportChange;
@@ -318,32 +489,102 @@ declare class BkCustomCalendar implements OnInit, OnDestroy, OnChanges, ControlV
     ngOnDestroy(): void;
     checkAndSetActiveRange(): void;
     initializeTimeFromDate(date: Date, isStart: boolean): void;
+    /** True while the trigger input itself has DOM focus — tracked because a click on an already-
+     *  focused-but-closed input doesn't re-fire `focus` (no actual focus change happens), so
+     *  onTriggerMouseDown needs another way to know it should still open. Set/cleared by
+     *  onTriggerFocus/onTriggerBlur. */
+    private triggerHasFocus;
+    /** Set immediately before {@link returnFocusToTrigger} programmatically refocuses the input, so
+     *  the resulting onTriggerFocus() doesn't treat "focus we just gave back after closing" as a
+     *  request to reopen the very popup it was asked to close. Consumed (cleared) by the next
+     *  onTriggerFocus() call — see its own comment. */
+    private suppressNextTriggerAutoOpen;
+    /**
+     * Opens the popup as soon as the trigger input receives focus — including via Tab, not just a
+     * click. Guarded on `!this.show` so it's a no-op if something else already opened it. Also
+     * consumes {@link suppressNextTriggerAutoOpen}: when {@link returnFocusToTrigger} refocuses the
+     * input after Cancel/Apply closed the popup, this fires too (a genuine focus transition, same
+     * as any other) — without the guard it would immediately reopen the popup right after closing
+     * it.
+     */
+    onTriggerFocus(): void;
+    /** Pairs with (blur)="onTriggerBlur()" on the trigger input — keeps {@link triggerHasFocus} in
+     *  sync, on top of the pre-existing markAsTouched() call this replaces inline. */
+    onTriggerBlur(): void;
+    /**
+     * `mousedown` (not `click`) so this cooperates with {@link onTriggerFocus} instead of racing
+     * it: `mousedown` fires *before* the browser's default focus shift, `focus` fires *after* it —
+     * same click sequence, different moments.
+     * - Not yet focused, closed: do nothing here — let the mousedown's own default focus shift
+     *   fire `onTriggerFocus` right after, which opens it. Exactly one open, no double-handling.
+     * - Already focused (so `focus` won't fire again — no actual focus change) but somehow closed
+     *   (e.g. Cancel/Apply just closed it while focus was returned here): open it explicitly, since
+     *   nothing else will.
+     * - Already open (and therefore already focused, since focus always opens): this click means
+     *   close — toggle closed, and preventDefault so the browser doesn't do anything odd with a
+     *   mousedown on an already-focused field it's about to lose visually.
+     */
+    onTriggerMouseDown(event: MouseEvent): void;
+    /**
+     * Opens the popup from the keyboard once the trigger input has focus — Enter, Space, or
+     * ArrowDown, the standard combobox/datepicker open keys. Focus alone already opens it (see
+     * onTriggerFocus), so in practice this only matters if focus is regained without opening for
+     * some other reason. Guarded on `!this.show` so it never re-closes an already-open popup.
+     */
+    onTriggerKeydownOpen(event: Event): void;
     toggle(): void;
-    /** Update popup position when appendToBody is true (fixed positioning relative to viewport). */
-    updatePosition(): void;
-    /**
-     * Horizontal placement for the fixed (appendToBody) popup.
-     *
-     * The base edge follows the author's {@link opens} preference:
-     *   • 'left'   → align left edges, panel opens rightwards (default)
-     *   • 'right'  → align right edges, panel opens leftwards
-     *   • 'center' → centred on the trigger
-     * When {@link autoPosition} is on, the panel auto-flips to the opposite edge if the preferred
-     * side would overflow the viewport, then clamps to an 8px margin so it can never leave the screen.
-     * When autoPosition is off, the explicit `opens` value is honoured as-is.
-     */
-    private computePopupLeft;
-    /** Non–append-to-body: set `popupPlacementAbove` for CSS `drop-up` with viewport flip. */
-    refreshPopupPlacement(): void;
-    private computePlacementAbove;
-    /** Normalize to local midnight and clamp to min/max selectable day. */
+    /** minDate/maxDate day clamp, factored out so {@link clampCalendarDayToSelectableRange} can
+     *  apply it a second time after jumping to a different month (see there for why). */
+    private clampToMinMax;
+    /** Nearest month (year+month pair) to `month`/`year` that isn't disabled — i.e. that has at
+     *  least one selectable day once minDate/maxDate AND allowedMonths AND allowedYears are all
+     *  applied (see isMonthDisabled). Searches outward a month at a time, forward and back in
+     *  lockstep, so it finds the true nearest regardless of which side the given month missed on.
+     *  Bounded to 50 years either way as a safety net against a contradictory config (e.g.
+     *  allowedYears entirely outside minDate/maxDate) that has no answer at all — returns the
+     *  original month/year unchanged in that case. */
+    private nearestSelectableMonth;
+    /**
+     * Normalize to local midnight, clamp into [minDate, maxDate], then — if that alone still lands
+     * on a month allowedMonths/allowedYears excludes — jump to the nearest month that actually has
+     * a selectable day. Without this, opening the calendar (or narrowing allowedMonths/allowedYears
+     * while a stale view was showing) could land squarely on a dead month: minDate/maxDate-valid but
+     * allowedMonths-disabled, e.g. minDate falls in August with allowedMonths excluding it — since
+     * month/year nav stays deliberately unguarded (see nextMonth/prevMonth), the user would have to
+     * page there by hand with no indication which direction to go. Re-clamps to minDate/maxDate
+     * after the jump too, in case the nearest allowed month is the very month minDate or maxDate
+     * falls in (the 1st of that month alone could still sit outside the day-level bound). If
+     * nearestSelectableMonth can't find anything better at all (a self-contradictory config, e.g.
+     * allowedYears entirely outside minDate/maxDate — it then returns the same month/year back
+     * unchanged), this leaves the original clamped day exactly as-is instead of needlessly
+     * resetting it to the 1st for no actual improvement.
+     */
     private clampCalendarDayToSelectableRange;
     private initKeyboardFocus;
+    /**
+     * Re-centers the visible month(s) and keyboard focus on `date` (clamped into the selectable
+     * range). Shared by {@link resetCalendarFocusAfterClear} and
+     * {@link revalidateSelectionAgainstConstraints} — callers differ only in whether they also
+     * steal DOM focus afterwards.
+     */
+    private recenterCalendarOn;
     /**
      * After clearing values, drop stale keyboard highlight (was last start/end) and reset the
      * visible month(s) to today (clamped). Move DOM focus to the popup when open, else the input.
      */
     private resetCalendarFocusAfterClear;
+    /**
+     * Called from {@link ngOnChanges} when any of `minDate`/`maxDate`/`allowedMonths`/
+     * `allowedYears`/`allowedDaysOfWeek`/`disabledDates`/`allowedDates` change: clears any existing
+     * selection that no longer satisfies all of them — e.g. a date picked before the range was
+     * tightened, or before allowedMonths excluded its month — instead of leaving it displayed as
+     * "selected" while every cell that could represent it is now disabled. Delegates to {@link
+     * isDateDisabled} so this can never drift from what the day grid itself considers selectable.
+     * Re-emits so the bound model stays in sync with what's actually shown, and re-centers the
+     * visible month(s) on the closest still-valid day so the user isn't left staring at a month
+     * that no longer contains their selection.
+     */
+    private revalidateSelectionAgainstConstraints;
     private scheduleDomFocusAfterClear;
     private ensureKeyboardFocusVisible;
     private moveKeyboardFocus;
@@ -354,6 +595,20 @@ declare class BkCustomCalendar implements OnInit, OnDestroy, OnChanges, ControlV
      */
     private isKeyboardEventFromInteractiveDescendant;
     onCalendarPopupKeydown(event: KeyboardEvent): void;
+    /**
+     * CDK portals the popup into `.cdk-overlay-container` (position: fixed, full-viewport). Some
+     * browsers don't chain a wheel scroll from inside that fixed container back out to the page
+     * underneath, so hovering the (non-inline) popup and scrolling silently does nothing instead of
+     * scrolling the page — breaking the "popup follows the trigger as the page scrolls" behaviour
+     * the viewport-tracking above exists for. Forward the wheel delta to the page manually, but only
+     * once nothing inside the popup can still consume it: walk up from the actual wheel target
+     * looking for a genuinely scrollable ancestor with room left in that direction — e.g. the time
+     * picker's minute/second `.time-scroll` wheel, or the whole popup once `@media
+     * (max-width:1024px)` makes it scroll — and let that handle it natively instead.
+     */
+    onCalendarPopupWheel(event: WheelEvent): void;
+    /** True when `el` is a scroll container with room left to move further in `deltaY`'s direction. */
+    private canElementConsumeWheel;
     private applyKeyboardSelection;
     isKeyboardFocusedCell(year: number, month: number, day: number): boolean;
     onRangeButtonKeydown(event: KeyboardEvent, rangeKey: string): void;
@@ -366,7 +621,27 @@ declare class BkCustomCalendar implements OnInit, OnDestroy, OnChanges, ControlV
     isDateInMultiSelection(year: number, month: number, day: number): boolean;
     apply(): void;
     cancel(): void;
+    /**
+     * Returns keyboard focus to the trigger input after an explicit in-popup dismissal (Cancel /
+     * Apply). Without this, focus is left on the Cancel/Apply button as the (portalled) popup tears
+     * down out from under it — the browser then drops focus to <body>, so a keyboard user loses
+     * their place entirely and Tab restarts from the top of the page instead of continuing from the
+     * calendar. Not called from the generic outside-click/scroll-out dismissal path (finishPopupDismissal) —
+     * there the user's own click already established where focus should go; forcing it back to the
+     * trigger would fight that. setTimeout(0) mirrors scheduleDomFocusAfterClear: it defers past the
+     * click's own default focus handling (which would otherwise re-focus the Cancel/Apply button
+     * right after and win the race against a synchronous call here).
+     */
+    private returnFocusToTrigger;
     clear(): void;
+    /**
+     * Applies a preset range (Today/Yesterday/Last 7 days/etc.) or activates "Custom Range".
+     * Deliberately does NOT check minDate/maxDate/allowedMonths/allowedYears/allowedDaysOfWeek/
+     * disabledDates/allowedDates — those constraints are scoped to manual day-grid picking only
+     * (selectDate() routes through isDateDisabled before ever setting startDate/endDate; this does
+     * not). A preset always applies exactly as configured, even if part of it falls outside those
+     * constraints — isDateSelected() has a matching note on why it doesn't re-check them either.
+     */
     chooseRange(key: string): void;
     emitSelection(): void;
     addDays(date: Date, days: number): Date;
@@ -377,6 +652,86 @@ declare class BkCustomCalendar implements OnInit, OnDestroy, OnChanges, ControlV
     prevLeftMonth(): void;
     nextRightMonth(): void;
     prevRightMonth(): void;
+    nextYear(): void;
+    prevYear(): void;
+    nextLeftYear(): void;
+    prevLeftYear(): void;
+    nextRightYear(): void;
+    prevRightYear(): void;
+    /** Drives both the click guard and the `<<`/`>>` chevrons' disabled state. */
+    isNextYearDisabled(currentYear: number): boolean;
+    isPrevYearDisabled(currentYear: number): boolean;
+    private computeYearRangeStart;
+    /** The 12 years shown in an open year-grid, given its page anchor. */
+    getYearGridYears(rangeStart: number): number[];
+    /** {@link allowedMonths} (1-based) converted to the 0-based month indices used everywhere
+     *  internally — JS `Date.getMonth()`, `this.month`, the month grid's own loop index. */
+    private get allowedMonthsZeroBased();
+    /** {@link allowedDaysOfWeek} (1-based) converted to the 0-based weekday indices JS
+     *  `Date.getDay()` uses. */
+    private get allowedDaysOfWeekZeroBased();
+    /** True if `list` contains a Date matching `year`/`month`/`day` — compared by calendar day
+     *  only, same normalize-to-midnight reasoning as every other date comparison in this file (see
+     *  isDateDisabled). Backs {@link disabledDates}/{@link allowedDates}. */
+    private dateListIncludes;
+    /** minDate/maxDate checked first, then allowedMonths — same precedence as isDateDisabled/
+     *  isYearDisabled (AND overall, so check order doesn't change the result, only readability). */
+    isMonthDisabled(month: number, year: number): boolean;
+    /** minDate/maxDate checked first, then allowedYears — see isMonthDisabled's note on ordering. */
+    isYearDisabled(year: number): boolean;
+    /** 0-based entry in {@link allowedMonthsZeroBased} nearest to `month`, ties broken toward the
+     *  earlier one. */
+    private nearestAllowedMonth;
+    /** If switching to `year` would leave the current month disabled, snap it back inside range. */
+    private clampMonthForYear;
+    /** True when `pickerView` actually restricts this calendar to a month/year grid — single-date
+     *  only, per its JSDoc; dual/range calendars always use the day grid regardless of the input. */
+    isPickerViewActive(): boolean;
+    /** The view a single calendar starts on / collapses back to: the day grid, unless `pickerView`
+     *  pins it to the month or year grid instead — there is no day grid to fall back to there. */
+    private baseView;
+    /** Collapse any open month/year grid back to {@link baseView} (called whenever the popup resets).
+     *  When that lands on the year grid, also re-centers {@link yearRangeStart} on `this.year` — the
+     *  grid is otherwise never reached via {@link openYearView} (the only other place that sets it),
+     *  so it would stay at its `0` default and show the wrong 12-year page. */
+    private resetDrillDownViews;
+    openMonthView(): void;
+    /** Year-changing chevrons shown alongside the month grid — shift its year without leaving the view. */
+    prevMonthGridYear(): void;
+    nextMonthGridYear(): void;
+    openYearView(): void;
+    prevYearRange(): void;
+    nextYearRange(): void;
+    selectMonthFromGrid(month: number): void;
+    selectYearFromGrid(year: number): void;
+    /** Commits a `pickerView` 'month'/'year' selection: populates {@link selectedMonthValue}/
+     *  {@link selectedYearValue}, emits, and closes the popup (unless inline) — the same "pick →
+     *  done" flow `autoApply` gives the day grid. */
+    private commitMonthYearSelection;
+    /** "Today" quick-jump shown at the bottom of the month/year grids — jumps to today's month/year.
+     *  In `pickerView` 'month'/'year' mode this finalizes the selection there; otherwise it jumps
+     *  back to the day grid and selects today's date. */
+    goToToday(): void;
+    openLeftMonthView(): void;
+    prevLeftMonthGridYear(): void;
+    nextLeftMonthGridYear(): void;
+    openLeftYearView(): void;
+    prevLeftYearRange(): void;
+    nextLeftYearRange(): void;
+    selectLeftMonthFromGrid(month: number): void;
+    selectLeftYearFromGrid(year: number): void;
+    /** "Today" quick-jump for the left calendar's month/year grids. */
+    goToLeftToday(): void;
+    openRightMonthView(): void;
+    prevRightMonthGridYear(): void;
+    nextRightMonthGridYear(): void;
+    openRightYearView(): void;
+    prevRightYearRange(): void;
+    nextRightYearRange(): void;
+    selectRightMonthFromGrid(month: number): void;
+    selectRightYearFromGrid(year: number): void;
+    /** "Today" quick-jump for the right calendar's month/year grids. */
+    goToRightToday(): void;
     initializeDual(): void;
     generateDualCalendars(): void;
     buildCalendar(year: number, month: number): {
@@ -385,8 +740,23 @@ declare class BkCustomCalendar implements OnInit, OnDestroy, OnChanges, ControlV
     }[][];
     isDateSelected(year: number, month: number, day: number): boolean;
     isDateInRange(year: number, month: number, day: number): boolean;
+    /**
+     * A cell is disabled unless it satisfies EVERY constraint that's set — minDate AND maxDate AND
+     * allowedMonths AND allowedYears AND allowedDaysOfWeek AND NOT-in-disabledDates AND (if set)
+     * in-allowedDates. Checked in that order, matching isMonthDisabled/isYearDisabled's own
+     * minDate/maxDate-first ordering below — purely for readability, since AND makes the overall
+     * result order-independent. This is the single source of truth for day-level selectability:
+     * selectDate() routes through it too (rather than re-checking constraints on its own), so a
+     * value can never be committed — including via keyboard Enter, which bypasses the template's
+     * click guard — that this marks disabled.
+     */
     isDateDisabled(year: number, month: number, day: number): boolean;
     isToday(year: number, month: number, day: number): boolean;
+    /** Today's month cell in the month grid — same "current" marker as {@link isToday} gives the
+     *  day grid, independent of `active` (the picked/displayed month). */
+    isCurrentMonth(month: number, year: number): boolean;
+    /** Today's year cell in the year grid — same idea as {@link isCurrentMonth}. */
+    isCurrentYear(year: number): boolean;
     getDisplayValue(): string;
     getTimeInputValue(isStart?: boolean): string;
     getSingleTimeInputValue(): string;
@@ -427,7 +797,7 @@ declare class BkCustomCalendar implements OnInit, OnDestroy, OnChanges, ControlV
     private parseDateString;
     formatDateToString(date: Date): string;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<BkCustomCalendar, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<BkCustomCalendar, "bk-custom-calendar", never, { "enableTimepicker": { "alias": "enableTimepicker"; "required": false; }; "autoApply": { "alias": "autoApply"; "required": false; }; "closeOnAutoApply": { "alias": "closeOnAutoApply"; "required": false; }; "showCancel": { "alias": "showCancel"; "required": false; }; "linkedCalendars": { "alias": "linkedCalendars"; "required": false; }; "singleDatePicker": { "alias": "singleDatePicker"; "required": false; }; "showWeekNumbers": { "alias": "showWeekNumbers"; "required": false; }; "showISOWeekNumbers": { "alias": "showISOWeekNumbers"; "required": false; }; "customRangeDirection": { "alias": "customRangeDirection"; "required": false; }; "lockStartDate": { "alias": "lockStartDate"; "required": false; }; "position": { "alias": "position"; "required": false; }; "popupPosition": { "alias": "popupPosition"; "required": false; }; "drop": { "alias": "drop"; "required": false; }; "dualCalendar": { "alias": "dualCalendar"; "required": false; }; "showRanges": { "alias": "showRanges"; "required": false; }; "timeFormat": { "alias": "timeFormat"; "required": false; }; "clearableTime": { "alias": "clearableTime"; "required": false; }; "enableSeconds": { "alias": "enableSeconds"; "required": false; }; "customRanges": { "alias": "customRanges"; "required": false; }; "weekDayLabels": { "alias": "weekDayLabels"; "required": false; }; "multiDateSelection": { "alias": "multiDateSelection"; "required": false; }; "maxDate": { "alias": "maxDate"; "required": false; }; "minDate": { "alias": "minDate"; "required": false; }; "placeholder": { "alias": "placeholder"; "required": false; }; "opens": { "alias": "opens"; "required": false; }; "inline": { "alias": "inline"; "required": false; }; "compact": { "alias": "compact"; "required": false; }; "autoPosition": { "alias": "autoPosition"; "required": false; }; "appendToBody": { "alias": "appendToBody"; "required": false; }; "isDisplayCrossIcon": { "alias": "isDisplayCrossIcon"; "required": false; }; "hasError": { "alias": "hasError"; "required": false; }; "errorMessage": { "alias": "errorMessage"; "required": false; }; "showCancelApply": { "alias": "showCancelApply"; "required": false; }; "selectedValue": { "alias": "selectedValue"; "required": false; }; "displayFormat": { "alias": "displayFormat"; "required": false; }; "required": { "alias": "required"; "required": false; }; "rangeOrder": { "alias": "rangeOrder"; "required": false; }; }, { "selected": "selected"; "opened": "opened"; "closed": "closed"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<BkCustomCalendar, "bk-custom-calendar", never, { "enableTimepicker": { "alias": "enableTimepicker"; "required": false; }; "autoApply": { "alias": "autoApply"; "required": false; }; "closeOnAutoApply": { "alias": "closeOnAutoApply"; "required": false; }; "showCancel": { "alias": "showCancel"; "required": false; }; "linkedCalendars": { "alias": "linkedCalendars"; "required": false; }; "singleDatePicker": { "alias": "singleDatePicker"; "required": false; }; "pickerView": { "alias": "pickerView"; "required": false; }; "showWeekNumbers": { "alias": "showWeekNumbers"; "required": false; }; "showISOWeekNumbers": { "alias": "showISOWeekNumbers"; "required": false; }; "customRangeDirection": { "alias": "customRangeDirection"; "required": false; }; "lockStartDate": { "alias": "lockStartDate"; "required": false; }; "position": { "alias": "position"; "required": false; }; "popupPosition": { "alias": "popupPosition"; "required": false; }; "drop": { "alias": "drop"; "required": false; }; "dualCalendar": { "alias": "dualCalendar"; "required": false; }; "showRanges": { "alias": "showRanges"; "required": false; }; "timeFormat": { "alias": "timeFormat"; "required": false; }; "clearableTime": { "alias": "clearableTime"; "required": false; }; "enableSeconds": { "alias": "enableSeconds"; "required": false; }; "customRanges": { "alias": "customRanges"; "required": false; }; "weekDayLabels": { "alias": "weekDayLabels"; "required": false; }; "multiDateSelection": { "alias": "multiDateSelection"; "required": false; }; "maxDate": { "alias": "maxDate"; "required": false; }; "minDate": { "alias": "minDate"; "required": false; }; "allowedMonths": { "alias": "allowedMonths"; "required": false; }; "allowedYears": { "alias": "allowedYears"; "required": false; }; "allowedDaysOfWeek": { "alias": "allowedDaysOfWeek"; "required": false; }; "disabledDates": { "alias": "disabledDates"; "required": false; }; "allowedDates": { "alias": "allowedDates"; "required": false; }; "placeholder": { "alias": "placeholder"; "required": false; }; "opens": { "alias": "opens"; "required": false; }; "inline": { "alias": "inline"; "required": false; }; "compact": { "alias": "compact"; "required": false; }; "appendToBody": { "alias": "appendToBody"; "required": false; }; "viewportMargin": { "alias": "viewportMargin"; "required": false; }; "panelClass": { "alias": "panelClass"; "required": false; }; "isDisplayCrossIcon": { "alias": "isDisplayCrossIcon"; "required": false; }; "hasError": { "alias": "hasError"; "required": false; }; "errorMessage": { "alias": "errorMessage"; "required": false; }; "showCancelApply": { "alias": "showCancelApply"; "required": false; }; "selectedValue": { "alias": "selectedValue"; "required": false; }; "displayFormat": { "alias": "displayFormat"; "required": false; }; "required": { "alias": "required"; "required": false; }; "rangeOrder": { "alias": "rangeOrder"; "required": false; }; }, { "selected": "selected"; "opened": "opened"; "closed": "closed"; }, never, never, true, never>;
 }
 
 interface TimeConfiguration {
@@ -507,7 +877,7 @@ declare class BkScheduledDatePicker implements OnInit {
 }
 
 declare class BkTimePicker implements OnInit, OnChanges, OnDestroy, AfterViewInit, ControlValueAccessor {
-    private renderer;
+    private calendarManager;
     required: boolean;
     /** @deprecated Prefer [(ngModel)] */
     value: string | null;
@@ -520,11 +890,30 @@ declare class BkTimePicker implements OnInit, OnChanges, OnDestroy, AfterViewIni
     closePicker: number;
     timeFormat: 12 | 24;
     showSeconds: boolean;
-    /** When true, auto-flip the dropdown above/below and left/right based on available viewport space. */
+    /**
+     * When true, offers a flipped-above fallback if there isn't room below the trigger (CDK only
+     * uses it when the preferred side genuinely doesn't fit). When false, the dropdown always opens
+     * below, never flipping — matches this input's original (pre-CDK) semantics.
+     */
     autoPosition: boolean;
-    /** When true, position the dropdown with `fixed` so it escapes ancestor overflow (dialogs, scroll containers),
-     *  follows the trigger on scroll, and closes when the trigger is scrolled out of view. */
+    /**
+     * @deprecated No-op, kept only so existing `[appendToBody]="true"` bindings don't break. The
+     * dropdown now always positions via Angular CDK Overlay, which portals into the shared
+     * `cdk-overlay-container` unconditionally — the exact clipping/stacking escape this input used
+     * to opt into by hand is now the only behaviour there is. Safe to remove from call sites.
+     */
     appendToBody: boolean;
+    /**
+     * Extra px CDK keeps clear of the viewport edges when flipping/pushing the dropdown. Same fix,
+     * same reasoning, as `bk-popover.viewportMargin` / `bk-custom-calendar.viewportMargin`.
+     */
+    viewportMargin: number;
+    /**
+     * Classes applied to the CDK overlay pane (`cdkConnectedOverlayPanelClass`). z-index overrides
+     * MUST go here — the pane already establishes its own stacking context once portalled. Same
+     * convention as `bk-popover.panelClass` / `bk-custom-calendar.panelClass`.
+     */
+    panelClass: string | string[];
     change: EventEmitter<string | null>;
     timeChange: EventEmitter<string | null>;
     pickerOpened: EventEmitter<string>;
@@ -535,14 +924,28 @@ declare class BkTimePicker implements OnInit, OnChanges, OnDestroy, AfterViewIni
     hourScrollEl?: ElementRef<HTMLElement>;
     minuteScrollEl?: ElementRef<HTMLElement>;
     secondScrollEl?: ElementRef<HTMLElement>;
-    /** The positioned trigger (its rect anchors the dropdown). */
+    /** The trigger — also the CDK connected-overlay origin (see #tpOrigin in the template). */
     tpWrapper?: ElementRef<HTMLElement>;
-    /** The dropdown panel element (measured for flip decisions). */
-    tpDropdown?: ElementRef<HTMLElement>;
-    /** Resolved placement state, driven by updatePosition(). */
+    tpOverlay?: CdkConnectedOverlay;
+    /** Resolved from CDK's (positionChange); drives the CSS flip-direction class. */
     placeAbove: boolean;
-    resolvedPosition: 'left' | 'right';
-    dropdownStyle: Record<string, string>;
+    /**
+     * CDK connected-overlay positions for the current open. Rebuilt each time the dropdown opens
+     * (see {@link togglePicker}) from `position` (horizontal side, fixed — never flips; CDK's push,
+     * always on, handles keeping it on-screen instead, same approach `bk-popover`/
+     * `bk-custom-calendar` use for their own horizontal axis) and `autoPosition` (whether a flipped
+     * vertical fallback is offered at all — matches this input's original semantics exactly).
+     */
+    pickerPositions: ConnectedPosition[];
+    /** Tags each entry in {@link pickerPositions} with whether it places the dropdown above the
+     *  trigger, so `onPositionChange` can read back which one CDK actually used. Matched by field
+     *  value, not object identity — CDK reconstructs its own ConnectedPosition objects internally. */
+    private positionMeta;
+    private buildVerticalPosition;
+    /** (Re)computes {@link pickerPositions}: always tries `position`'s side below the trigger first;
+     *  `autoPosition` additionally offers the same side flipped above as a fallback CDK only falls
+     *  back to when below genuinely doesn't fit. */
+    private computePickerPositions;
     /** Row height in px. MUST match the .time-item height in CSS for the active variation. */
     private get ITEM_HEIGHT();
     /** Finite lists (no cyclic loop) — same as the hours column, so 00..59 has a hard start/end. */
@@ -570,21 +973,6 @@ declare class BkTimePicker implements OnInit, OnChanges, OnDestroy, AfterViewIni
         readonly calenderIcon: "assets/icons/custom-calender.svg";
         readonly timerIcon: "assets/icons/timer.svg";
     };
-    constructor(renderer: Renderer2);
-    /**
-     * `appendToBody` anchors the dropdown with `position: fixed`, which only tracks the viewport when
-     * NO ancestor establishes a containing block (transform / filter / perspective / will-change /
-     * contain / backdrop-filter). Inside such an ancestor the fixed coordinates resolve against that
-     * ancestor instead and the dropdown drifts off-position. To be robust we physically move the panel
-     * to <body> while open (Angular keeps managing it by reference) and move it back before *ngIf
-     * tears it down. The panel carries a `tp-compact` self-class so its `default`-variation sizing —
-     * otherwise scoped under the `.time-input-group.default` ancestor it just left — still applies.
-     */
-    private dropdownMovedToBody;
-    private dropdownOriginalParent;
-    private moveDropdownToBody;
-    /** Return the dropdown to its original slot so *ngIf can destroy it cleanly (safe to call twice). */
-    private restoreDropdownFromBody;
     writeValue(value: string | null): void;
     registerOnChange(fn: (value: string | null) => void): void;
     registerOnTouched(fn: () => void): void;
@@ -594,6 +982,9 @@ declare class BkTimePicker implements OnInit, OnChanges, OnDestroy, AfterViewIni
     private setDefaultsForDropdown;
     clear(): void;
     markAsTouched(): void;
+    constructor(calendarManager: BkCalendarManagerService);
+    private closeFn?;
+    private unregisterFn?;
     ngOnInit(): void;
     ngAfterViewInit(): void;
     ngOnChanges(changes: SimpleChanges): void;
@@ -605,37 +996,102 @@ declare class BkTimePicker implements OnInit, OnChanges, OnDestroy, AfterViewIni
         ampm: string;
     };
     formatTimeFromComponents(hour: number, minute: number, second: number, ampm: string): string;
+    /** True while the trigger input itself has DOM focus — see onTriggerMouseDown for why this is
+     *  tracked (same reasoning as bk-custom-calendar's triggerHasFocus). */
+    private triggerHasFocus;
+    /** Opens the dropdown as soon as the trigger input receives focus — including via Tab, not
+     *  just a click. Guarded on `!this.showPicker` so it's a no-op if already open. */
+    onTriggerFocus(): void;
+    /** Pairs with (blur) — keeps triggerHasFocus in sync alongside the pre-existing
+     *  markAsTouched() call this replaces inline. */
+    onTriggerBlur(): void;
+    /**
+     * `mousedown` (not `click`) so this cooperates with {@link onTriggerFocus} instead of racing
+     * it — same pattern and reasoning as bk-custom-calendar's onTriggerMouseDown: not-yet-focused
+     * clicks are left to the default focus shift (which opens via onTriggerFocus); an
+     * already-focused click means close (or, if somehow already focused but closed, open — `focus`
+     * won't re-fire without an actual focus change).
+     */
+    onTriggerMouseDown(event: MouseEvent): void;
+    /**
+     * Opens the dropdown from the keyboard once the trigger input has focus — Enter, Space, or
+     * ArrowDown, the standard combobox/datepicker open keys. Focus alone already opens it (see
+     * onTriggerFocus); this mainly matters if focus is regained without opening for some other
+     * reason.
+     */
+    onTriggerKeydownOpen(event: Event): void;
     togglePicker(): void;
-    /** Central close path so listeners are always detached and events emitted once. */
-    private dismiss;
+    /** Central close path so listeners are always detached and events emitted once. Not private:
+     *  the template's own (detach) binding on cdkConnectedOverlay calls it directly. */
+    dismiss(): void;
+    /** Cancels every pending scroll-related timer/rAF (deferred open-scroll, snap-settle debounce,
+     *  active-highlight rAF throttle) so none of them fire against a picker that has since closed
+     *  or been destroyed. */
+    private clearScrollTimers;
     onHourChange(hour: number): void;
     onMinuteChange(minute: number): void;
     onSecondChange(second: number): void;
     onAMPMChange(ampm: string): void;
     updateTime(): void;
+    /** Defers scrollToSelectedTimes() until the just-opened overlay's columns have rendered.
+     *  Clears any previously pending call first, so opening/closing/reopening in quick succession
+     *  can never stack more than one pending scroll (each would otherwise reset the columns to the
+     *  committed value, undoing any scrolling the user did in between). */
+    private scheduleScrollToSelectedTimes;
     /** Position each column so the committed value sits at the top of its viewport. */
     scrollToSelectedTimes(): void;
     private scrollColumnTo;
     /** Item nearest the viewport center for the current scroll position, clamped to [0, count - 1]. */
     private scrollIndex;
-    onDocumentClick(event: MouseEvent): void;
+    /** CDK's overlay origin already excludes clicks on the trigger from outside-click dispatch by
+     *  design (same note in bk-popover/bk-custom-calendar's onOverlayOutsideClick), so the input's
+     *  own (click)="togglePicker()" stays the sole opener/closer via the trigger. */
+    onOverlayOutsideClick(): void;
     private previousCloseCounter;
+    /** Handle for the deferred scrollToSelectedTimes() (see togglePicker/ngAfterViewInit). Stored
+     *  so a stale timer never fires after the picker has already closed, and so opening/closing in
+     *  quick succession never stacks more than one pending call. */
+    private scrollToSelectedTimeoutId;
+    /** rAF handles throttling the active-highlight update to at most once per frame during fast
+     *  wheel/trackpad scrolling — same pattern as {@link onViewportChange}. Without this, a scroll
+     *  event firing many times per frame drove Angular change detection just as often, which is
+     *  what made the wheel feel like it was "sticking" during a fast scroll. */
+    private hourScrollRafId;
+    private minuteScrollRafId;
+    private secondScrollRafId;
+    /** Debounce handles for {@link settleColumn} — row-boundary snapping now happens in JS, only
+     *  once scrolling has actually stopped, instead of via CSS scroll-snap-type. CSS snapping on a
+     *  list this short fights real-time mouse-wheel input in Chrome/Windows (the browser re-snaps
+     *  after every wheel tick), which is what actually caused the "gets stuck" symptom. */
+    private hourSnapTimeoutId;
+    private minuteSnapTimeoutId;
+    private secondSnapTimeoutId;
     getHours(): number[];
     getAMPMOptions(): string[];
     onHourScroll(): void;
     onMinuteScroll(): void;
     onSecondScroll(): void;
-    /**
-     * Resolve the dropdown placement against the current viewport.
-     * - autoPosition: flip above when there isn't room below, and flip the horizontal
-     *   side when the preferred side would overflow.
-     * - appendToBody: additionally anchor with `position: fixed` (inline style) so the
-     *   dropdown escapes ancestor overflow and follows the trigger on scroll.
-     */
-    private updatePosition;
+    /** Debounces settleColumn() to 120ms after the last scroll event on that column — i.e. it only
+     *  runs once the user has actually stopped scrolling, never mid-gesture. */
+    private scheduleSnapSettle;
+    /** Snaps a column to the row boundary nearest its current scroll position — the JS equivalent
+     *  of what `scroll-snap-align: center` used to do, minus the mouse-wheel "stuck" bug that came
+     *  with doing it via CSS on a list this short (see .time-scroll's CSS comment). */
+    private settleColumn;
+    /** Fires whenever CDK (re)applies a position, including the first one after open. Reads back
+     *  which of `positionMeta`'s tagged entries CDK actually used, to drive the CSS flip-direction
+     *  class the same value the old manual updatePosition() used to. */
+    onPositionChange(event: ConnectedOverlayPositionChange): void;
     private viewportListenersAttached;
     private viewportRafId;
     private readonly onViewportChange;
+    /**
+     * CDK's own scroll strategy only reacts to real `document`/`window` scroll — it has no way to
+     * know an app shell might scroll a nested container instead. A capture-phase listener on
+     * `document` still sees scroll events fired on any descendant scrollable element (scroll
+     * doesn't bubble, but capture does) — the same trick `bk-custom-calendar` uses. Throttled
+     * through requestAnimationFrame to avoid layout thrash during fast scrolling.
+     */
     private handleViewportChange;
     /** True when the trigger has scrolled out of the viewport or out of any clipping ancestor. */
     private isTriggerOutOfView;
@@ -644,7 +1100,7 @@ declare class BkTimePicker implements OnInit, OnChanges, OnDestroy, AfterViewIni
     private detachViewportListeners;
     ngOnDestroy(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<BkTimePicker, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<BkTimePicker, "bk-time-picker", never, { "required": { "alias": "required"; "required": false; }; "value": { "alias": "value"; "required": false; }; "label": { "alias": "label"; "required": false; }; "placeholder": { "alias": "placeholder"; "required": false; }; "clearable": { "alias": "clearable"; "required": false; }; "position": { "alias": "position"; "required": false; }; "variation": { "alias": "variation"; "required": false; }; "pickerId": { "alias": "pickerId"; "required": false; }; "closePicker": { "alias": "closePicker"; "required": false; }; "timeFormat": { "alias": "timeFormat"; "required": false; }; "showSeconds": { "alias": "showSeconds"; "required": false; }; "autoPosition": { "alias": "autoPosition"; "required": false; }; "appendToBody": { "alias": "appendToBody"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; }, { "change": "change"; "timeChange": "timeChange"; "pickerOpened": "pickerOpened"; "pickerClosed": "pickerClosed"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<BkTimePicker, "bk-time-picker", never, { "required": { "alias": "required"; "required": false; }; "value": { "alias": "value"; "required": false; }; "label": { "alias": "label"; "required": false; }; "placeholder": { "alias": "placeholder"; "required": false; }; "clearable": { "alias": "clearable"; "required": false; }; "position": { "alias": "position"; "required": false; }; "variation": { "alias": "variation"; "required": false; }; "pickerId": { "alias": "pickerId"; "required": false; }; "closePicker": { "alias": "closePicker"; "required": false; }; "timeFormat": { "alias": "timeFormat"; "required": false; }; "showSeconds": { "alias": "showSeconds"; "required": false; }; "autoPosition": { "alias": "autoPosition"; "required": false; }; "appendToBody": { "alias": "appendToBody"; "required": false; }; "viewportMargin": { "alias": "viewportMargin"; "required": false; }; "panelClass": { "alias": "panelClass"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; }, { "change": "change"; "timeChange": "timeChange"; "pickerOpened": "pickerOpened"; "pickerClosed": "pickerClosed"; }, never, never, true, never>;
 }
 
 /**
@@ -4112,7 +4568,7 @@ declare class BkTd extends BkCellBase implements AfterViewInit, OnDestroy {
      */
     protected readonly truncatedTooltip: _angular_core.WritableSignal<string>;
     /** Forwarded to the content wrapper's `bkTooltip`. Override on a column whose default 'right' would run into its neighbour. */
-    tooltipPosition: _angular_core.InputSignal<"top" | "bottom" | "left" | "right">;
+    tooltipPosition: _angular_core.InputSignal<"left" | "right" | "top" | "bottom">;
     /** Only present when `ellipsis()` is true — see the `@else` branch in the template. */
     private ellipsisTextRef?;
     checkbox: _angular_core.InputSignal<boolean>;
@@ -4429,5 +4885,5 @@ declare class BkTreeDrag<T = any> extends BkTableDrag implements OnDestroy {
 
 declare const BK_TABLE: readonly [typeof BkTable, typeof BkTableTitle, typeof BkTableFooter, typeof BkVirtualScroll, typeof BkTh, typeof BkTd, typeof BkTrExpand, typeof BkTableSummary, typeof BkTableDrag, typeof BkDragHandle, typeof BkTreeDrag];
 
-export { ARROW_CORNER_GAP, BKTooltipDirective, BK_DEFAULT_DIALOG_CONFIG, BK_DIALOG_DATA, BK_DIALOG_GLOBAL_CONFIG, BK_TABLE, BkAvatar, BkAvatarGroup, BkAvatarUploader, BkBadge, BkBreadcrumb, BkButton, BkButtonGroup, BkCalendarManagerService, BkCheckbox, BkColumnFilterService, BkColumnSelect, BkCustomCalendar, BkDialogActions, BkDialogClose, BkDialogContent, BkDialogModule, BkDialogRef, BkDialogService, BkDialogTitle, BkDragHandle, BkDropdown, BkFileCard, BkFilePicker, BkGrid, BkHierarchicalSelect, BkIconButton, BkInput, BkInputChips, BkLoader, BkMenu, BkPagination, BkPill, BkPopover, BkRadioButton, BkScheduledDatePicker, BkSelect, BkSpinner, BkTable, BkTableDrag, BkTableFooter, BkTableSummary, BkTableTitle, BkTabs, BkTd, BkTextarea, BkTh, BkTimePicker, BkToastr, BkToastrService, BkToggle, BkTooltipInteractionService, BkTrExpand, BkTreeDrag, BkValidator, BkVirtualScroll, BrickclayIcons, BrickclayLib, CalendarModule, CalendarSelection, ColumnFilterOption, DEFAULT_COUNTRY_OPTIONS, NEUTRAL_APPEARANCE, OPPOSITE_SIDE, POPOVER_PLACEMENTS, clamp, containsBkTreeNode, deriveAppearance, flattenBkTreeData, getDialogBackdropAnimation, getDialogPanelAnimation, joinPlacement, moveBkTreeNode, normalizeBkTableSize, parseColor, splitPlacement };
+export { ARROW_CORNER_GAP, BKTooltipDirective, BK_DEFAULT_DIALOG_CONFIG, BK_DIALOG_DATA, BK_DIALOG_GLOBAL_CONFIG, BK_TABLE, BkAvatar, BkAvatarGroup, BkAvatarUploader, BkBadge, BkBreadcrumb, BkButton, BkButtonGroup, BkCalendarManagerService, BkCheckbox, BkColumnFilterService, BkColumnSelect, BkCustomCalendar, BkDialogActions, BkDialogClose, BkDialogContent, BkDialogModule, BkDialogRef, BkDialogService, BkDialogTitle, BkDragHandle, BkDropdown, BkFileCard, BkFilePicker, BkGrid, BkHierarchicalSelect, BkIconButton, BkInput, BkInputChips, BkLoader, BkMenu, BkPagination, BkPill, BkPopover, BkRadioButton, BkScheduledDatePicker, BkSelect, BkSpinner, BkTable, BkTableDrag, BkTableFooter, BkTableSummary, BkTableTitle, BkTabs, BkTd, BkTextarea, BkTh, BkTimePicker, BkToastr, BkToastrService, BkToggle, BkTooltipInteractionService, BkTrExpand, BkTreeDrag, BkValidator, BkVirtualScroll, BrickclayIcons, BrickclayLib, CalendarModule, CalendarMonth, CalendarSelection, CalendarWeekday, ColumnFilterOption, DEFAULT_COUNTRY_OPTIONS, NEUTRAL_APPEARANCE, OPPOSITE_SIDE, POPOVER_PLACEMENTS, clamp, containsBkTreeNode, deriveAppearance, flattenBkTreeData, getDialogBackdropAnimation, getDialogPanelAnimation, joinPlacement, moveBkTreeNode, normalizeBkTableSize, parseColor, splitPlacement };
 export type { AvatarFallback, AvatarGroupItem, AvatarSize, AvatarVariant, BadgeColor, BadgeSize, BadgeVariant, BkAnimationKeyframes, BkAvatarFallback, BkAvatarSize, BkCellAlign, BkColumnRef, BkColumnSelectPosition, BkDialogAnimation, BkDialogConfig, BkDialogPosition, BkFilterFn, BkFilterOption, BkInputAutoCapitalize, BkInputAutoComplete, BkInputMode, BkInputSize, BkInputType, BkLoaderVariant, BkPageSize, BkPageSizeVisibility, BkSelectGridColumn, BkSortDirection, BkSortFn, BkSortOrder, BkTableNoResult, BkTableQueryParams, BkTableScroll, BkTableSelection, BkTableSize, BkTableSizeToken, BkTextAreaAutoCapitalize, BkTextAreaAutoComplete, BkTextAreaInputMode, BkTooltipDismissible, BkTreeDragScope, BkTreeDropEvent, BkTreeDropPosition, BkTreeRow, BreadcrumbItem, ButtonSize, ButtonVariant, CalendarRange, ColorAppearance, ColorFill, CountryOption, CustomRangesConfig, DotPosition, DotStatus, DropdownItem, DropdownPlacement, DropdownSize, DropdownTrigger, DropdownVariant, FileState, GroupItem, GroupMode, HierarchicalNode, IconButtonSize, IconButtonVariant, IconOrientation, MenuItem, MenuOrientation, MenuPopupSide, MenuSize, MenuSubmenuMode, MenuTrigger, PillColor, PillSize, PillVariant, PopoverAlign, PopoverPlacement, PopoverSide, ScheduledDateSelection, SortDirection, SpinnerSize, TabIconDirection, TabItem, TableAction, TableBadge, TableColumn, TableIcon, TableRows, TabsColors, TabsOrientation, TabsVariant, TimeConfiguration, ToastConfig, ToastMessage, ToastMethodOptions, ToastPosition, ToastSeverity };