@brickclay-org/ui 0.1.85 → 0.1.87

package/index.d.ts

@@ -1,24 +1,25 @@
 import * as _angular_core from '@angular/core';
-import { EventEmitter, OnInit, OnDestroy, OnChanges, ElementRef, Renderer2, SimpleChanges, AfterViewInit, QueryList, ComponentRef, Type, InjectionToken, NgZone, ApplicationRef, EnvironmentInjector, ChangeDetectorRef, TemplateRef, WritableSignal } from '@angular/core';
+import { EventEmitter, OnInit, OnDestroy, OnChanges, ElementRef, Renderer2, SimpleChanges, AfterViewInit, QueryList, ComponentRef, Type, InjectionToken, NgZone, ChangeDetectorRef, TemplateRef, WritableSignal } from '@angular/core';
 import { ControlValueAccessor, Validator, AbstractControl, ValidationErrors, NgControl, NgModel } from '@angular/forms';
 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';
-import * as i2 from '@angular/cdk/overlay';
-import { ScrollStrategy } from '@angular/cdk/overlay';
 import * as i3 from '@angular/cdk/portal';
 import { ComponentPortal } from '@angular/cdk/portal';
 import * as i1$1 from '@angular/cdk/scrolling';
-import * as _brickclay_org_ui from '@brickclay-org/ui';
 
 declare const BrickclayIcons: {
     readonly arrowleft: "assets/icons/chevron-left.svg";
     readonly arrowRight: "assets/icons/chevron-right.svg";
+    readonly arrowLeftDouble: "assets/icons/double-chevron-left.svg";
+    readonly arrowRightDouble: "assets/icons/double-chevron-right.svg";
     readonly calenderIcon: "assets/icons/custom-calender.svg";
     readonly timerIcon: "assets/icons/timer.svg";
 };
@@ -171,6 +172,8 @@ declare class BkCustomCalendar implements OnInit, OnDestroy, OnChanges, ControlV
     brickclayIcons: {
         readonly arrowleft: "assets/icons/chevron-left.svg";
         readonly arrowRight: "assets/icons/chevron-right.svg";
+        readonly arrowLeftDouble: "assets/icons/double-chevron-left.svg";
+        readonly arrowRightDouble: "assets/icons/double-chevron-right.svg";
         readonly calenderIcon: "assets/icons/custom-calender.svg";
         readonly timerIcon: "assets/icons/timer.svg";
     };
@@ -562,6 +565,8 @@ declare class BkTimePicker implements OnInit, OnChanges, OnDestroy, AfterViewIni
     brickclayIcons: {
         readonly arrowleft: "assets/icons/chevron-left.svg";
         readonly arrowRight: "assets/icons/chevron-right.svg";
+        readonly arrowLeftDouble: "assets/icons/double-chevron-left.svg";
+        readonly arrowRightDouble: "assets/icons/double-chevron-right.svg";
         readonly calenderIcon: "assets/icons/custom-calender.svg";
         readonly timerIcon: "assets/icons/timer.svg";
     };
@@ -954,6 +959,8 @@ declare class BkGrid<T = any> {
     noRecordFoundHeight: string;
     /** Custom illustration for the empty state. Falls back to a built-in SVG when omitted. */
     noRecordImgUrl?: string;
+    /** Show the empty-state illustration above the message. Set false to show the message only. */
+    showNoRecordImg: boolean;
     noRecordMessage: string;
     /** Static row class or a function that returns a class per row. Row data may also include `class` via TableRows. */
     rows?: string | ((row: T) => string | undefined);
@@ -994,7 +1001,7 @@ declare class BkGrid<T = any> {
     onDragStart(event: CdkDragStart<any>): void;
     get noRecordImagePath(): string;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<BkGrid<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<BkGrid<any>, "bk-grid", never, { "draggable": { "alias": "draggable"; "required": false; }; "columns": { "alias": "columns"; "required": false; }; "result": { "alias": "result"; "required": false; }; "actions": { "alias": "actions"; "required": false; }; "customClass": { "alias": "customClass"; "required": false; }; "actionIconClass": { "alias": "actionIconClass"; "required": false; }; "actionClass": { "alias": "actionClass"; "required": false; }; "showNoRecords": { "alias": "showNoRecords"; "required": false; }; "noRecordFoundHeight": { "alias": "noRecordFoundHeight"; "required": false; }; "noRecordImgUrl": { "alias": "noRecordImgUrl"; "required": false; }; "noRecordMessage": { "alias": "noRecordMessage"; "required": false; }; "rows": { "alias": "rows"; "required": false; }; }, { "change": "change"; "actionClick": "actionClick"; "sortChange": "sortChange"; "dragDropChange": "dragDropChange"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<BkGrid<any>, "bk-grid", never, { "draggable": { "alias": "draggable"; "required": false; }; "columns": { "alias": "columns"; "required": false; }; "result": { "alias": "result"; "required": false; }; "actions": { "alias": "actions"; "required": false; }; "customClass": { "alias": "customClass"; "required": false; }; "actionIconClass": { "alias": "actionIconClass"; "required": false; }; "actionClass": { "alias": "actionClass"; "required": false; }; "showNoRecords": { "alias": "showNoRecords"; "required": false; }; "noRecordFoundHeight": { "alias": "noRecordFoundHeight"; "required": false; }; "noRecordImgUrl": { "alias": "noRecordImgUrl"; "required": false; }; "showNoRecordImg": { "alias": "showNoRecordImg"; "required": false; }; "noRecordMessage": { "alias": "noRecordMessage"; "required": false; }; "rows": { "alias": "rows"; "required": false; }; }, { "change": "change"; "actionClick": "actionClick"; "sortChange": "sortChange"; "dragDropChange": "dragDropChange"; }, never, never, true, never>;
 }
 
 /** How an accent colour is applied to a control. */
@@ -1060,7 +1067,7 @@ declare class BkSelect implements ControlValueAccessor, AfterViewInit, OnDestroy
     dropdownView: _angular_core.InputSignal<"list" | "grid">;
     gridColumns: _angular_core.InputSignal<BkSelectGridColumn[]>;
     /** Grid density. `inherit` follows the trigger's existing `variation`. */
-    gridVariation: _angular_core.InputSignal<"sm" | "default" | "inherit">;
+    gridVariation: _angular_core.InputSignal<"default" | "sm" | "inherit">;
     /** Stage multi-grid changes until Apply is clicked. */
     gridSelectionActions: _angular_core.InputSignal<boolean>;
     gridMinWidth: _angular_core.InputSignal<string>;
@@ -1110,9 +1117,21 @@ declare class BkSelect implements ControlValueAccessor, AfterViewInit, OnDestroy
     disabled: _angular_core.ModelSignal<boolean>;
     loading: _angular_core.InputSignal<boolean>;
     closeOnSelect: _angular_core.InputSignal<boolean>;
+    /**
+     * When on, the dropdown opens as soon as the control receives keyboard focus
+     * (e.g. tabbing to it) and closes once focus leaves it. Off by default so the
+     * existing click/Enter-to-open behaviour is unchanged.
+     */
+    openOnFocus: _angular_core.InputSignal<boolean>;
     dropdownPosition: _angular_core.InputSignal<"top" | "bottom">;
     hasError: boolean;
     errorMessage: string;
+    /**
+     * @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: _angular_core.InputSignal<boolean>;
     open: _angular_core.OutputEmitterRef<void>;
     close: _angular_core.OutputEmitterRef<void>;
@@ -1130,6 +1149,7 @@ declare class BkSelect implements ControlValueAccessor, AfterViewInit, OnDestroy
     optionsRef: QueryList<ElementRef>;
     controlWrapper: ElementRef<HTMLDivElement>;
     dropdownPanel?: ElementRef<HTMLDivElement>;
+    selectOverlay?: CdkConnectedOverlay;
     chipsViewport?: ElementRef<HTMLDivElement>;
     measureChips?: QueryList<ElementRef<HTMLElement>>;
     measurePlus?: ElementRef<HTMLElement>;
@@ -1143,17 +1163,15 @@ declare class BkSelect implements ControlValueAccessor, AfterViewInit, OnDestroy
     searchTerm: _angular_core.WritableSignal<string>;
     markedIndex: _angular_core.WritableSignal<number>;
     placement: _angular_core.WritableSignal<"top" | "bottom">;
-    private originalPanelParent;
-    private originalPanelAnchor;
-    private panelInBody;
     visibleCount: _angular_core.WritableSignal<number>;
     private resizeObserver?;
-    dropdownStyle: _angular_core.WritableSignal<{
-        top?: string;
-        bottom?: string;
-        left: string;
-        width: string;
-    }>;
+    /**
+     * Panel width, kept equal to the control's — matches the old `dropdownStyle().width`
+     * behaviour. Set on open and re-measured by the same ResizeObserver that already tracks
+     * the control for chip recomputation, so a responsive layout keeps the panel in sync while
+     * it's open.
+     */
+    dropdownWidth: _angular_core.WritableSignal<number | null>;
     filteredItems: _angular_core.Signal<any[]>;
     /**
      * True when the user is allowed to change the selection. Both disabled and
@@ -1164,25 +1182,23 @@ declare class BkSelect implements ControlValueAccessor, AfterViewInit, OnDestroy
     constructor();
     ngAfterViewInit(): void;
     ngOnDestroy(): void;
-    private reposition;
     /**
-     * True when the control is fully outside the visible area — either the
-     * viewport or a scrollable/clipping ancestor (e.g. a dialog's scroll body).
-     * Used to close the floating (append-to-body) panel once its anchor is no
-     * longer on screen, instead of leaving it hanging.
-     */
-    private isControlClipped;
-    /**
-     * Relocate the panel node to <body> so it truly escapes any transformed or
-     * overflow-clipped ancestor (dialogs, drawers, cards with overflow, etc.).
-     * Setting position:fixed alone is not enough when an ancestor has a transform.
-     */
-    private movePanelToBody;
-    /**
-     * Return the panel to its original DOM position so Angular's @if can remove
-     * it cleanly on close. Must run before isOpen is set to false.
-     */
-    private restorePanel;
+     * CDK's default `reposition` scroll strategy only reacts to real `document`/`window` scroll —
+     * it has no way to know an app shell might scroll a nested container instead (this one
+     * commonly does — dashboard layouts with a fixed header/sidebar and a scrollable content pane).
+     * A capture-phase listener on `document` still sees scroll events fired on any descendant
+     * scrollable element (scroll doesn't bubble, but capture does) — same trick `bk-custom-calendar`
+     * and the `bk-input` phone dropdown already use. rAF-throttled so a fast scroll doesn't force
+     * layout on every tick.
+     */
+    private overlayScrollRafId;
+    private readonly onOverlayScroll;
+    private attachOverlayScrollTracking;
+    private detachOverlayScrollTracking;
+    /** Derives `placement` (for the `[data-position="top"]` CSS margin tweak) from which of
+     *  `selectDropdownPositions` CDK actually applied — replaces the old hand-rolled space
+     *  comparison now that the fit/flip decision itself lives in CDK. */
+    onPositionChange(event: ConnectedOverlayPositionChange): void;
     private scheduleRecompute;
     /**
      * Measures the off-screen chip row and works out how many chips fit on a
@@ -1207,15 +1223,12 @@ declare class BkSelect implements ControlValueAccessor, AfterViewInit, OnDestroy
     toggleDropdown(event: Event | null): void;
     openDropdown(): void;
     closeDropdown(): void;
-    getTop(): string | null;
-    getBottom(): string | null;
     /**
-     * Decides which side the panel should open on (auto-flip) and, for
-     * append-to-body mode, computes the fixed coordinates. Shared by both modes
-     * and re-run on open and on every scroll/resize so the panel snaps to
-     * whichever side has room — honouring `dropdownPosition` when it fits.
+     * Preferred position list handed to CDK, in try-order — honours `dropdownPosition` first,
+     * falling back to the other side only when the preferred one genuinely doesn't fit. Replaces
+     * the old hand-rolled `applyPlacement()` space comparison entirely.
      */
-    applyPlacement(): void;
+    get selectDropdownPositions(): ConnectedPosition[];
     toggleSelectAll(event: Event): void;
     handleSelection(item: any, event?: Event): void;
     handleGridSelection(item: any, event?: Event): void;
@@ -1225,6 +1238,29 @@ declare class BkSelect implements ControlValueAccessor, AfterViewInit, OnDestroy
     handleClear(event: Event): void;
     private updateModel;
     onSearchInput(event: Event): void;
+    /**
+     * Options in the exact order they are rendered (groups flattened). This is the
+     * space Up/Down navigation and the marked-index operate in — using the flat
+     * `filteredItems()` would desync from the on-screen order once grouping
+     * reshuffles rows. For an ungrouped list this equals `filteredItems()`.
+     */
+    flatOptions: _angular_core.Signal<any[]>;
+    /** The option the marker currently sits on, or null. */
+    private markedOption;
+    /**
+     * Whether an option carries the keyboard/hover marker. Matched by identity
+     * rather than by row position so two groups can't share a highlight just
+     * because the marked item sits at the same index within each group.
+     */
+    isMarked(item: any): boolean;
+    /** Move the marker to a hovered option by its position in the rendered order. */
+    markOption(item: any): void;
+    /**
+     * Rendered-order index that Up/Down navigation starts from when the dropdown
+     * opens: the first already-selected option, or the first option when nothing
+     * is selected. Returns -1 only for an empty list.
+     */
+    private initialMarkedIndex;
     onKeyDown(event: KeyboardEvent): void;
     onTabPress(event: KeyboardEvent): void;
     onScroll(event: Event): void;
@@ -1237,7 +1273,27 @@ declare class BkSelect implements ControlValueAccessor, AfterViewInit, OnDestroy
     setDisabledState(d: boolean): void;
     private resolveSelectedOptions;
     private el;
-    onClickOutside(e: Event): void;
+    onOverlayOutsideClick(): void;
+    private pointerFocus;
+    private opening;
+    onPointerDown(): void;
+    /**
+     * Open when *keyboard* focus arrives from outside the control (tabbing to it).
+     * Pointer-initiated focus is ignored — a click opens via its own toggle, so
+     * this stays a keyboard affordance. Focus moves that originate inside the
+     * control or its panel — the panel handing focus to the search field, or focus
+     * falling back to the trigger as the panel closes — must not (re)open it,
+     * which would otherwise trap the user when tabbing backwards out of it.
+     */
+    onFocusIn(event: FocusEvent): void;
+    /**
+     * Close when focus leaves the control entirely — tabbing away, or focus moving
+     * to any element outside the control and its (possibly body-appended) panel.
+     * Internal focus moves keep it open.
+     */
+    onFocusOut(): void;
+    /** True when a node lives inside the control host or its detached panel. */
+    private isFocusInside;
     openFromLabel(event: MouseEvent): void;
     groupedItems: _angular_core.Signal<{
         group: string;
@@ -1285,7 +1341,7 @@ declare class BkSelect implements ControlValueAccessor, AfterViewInit, OnDestroy
     getTooltipIfEllipsed(el: HTMLElement, text: string): string;
     onOptionHover(index: number): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<BkSelect, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<BkSelect, "bk-select", never, { "items": { "alias": "items"; "required": false; "isSignal": true; }; "bindLabel": { "alias": "bindLabel"; "required": false; "isSignal": true; }; "bindValue": { "alias": "bindValue"; "required": false; "isSignal": true; }; "bindIcon": { "alias": "bindIcon"; "required": false; "isSignal": true; }; "isResponsive": { "alias": "isResponsive"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "notFoundText": { "alias": "notFoundText"; "required": false; "isSignal": true; }; "loadingText": { "alias": "loadingText"; "required": false; "isSignal": true; }; "clearAllText": { "alias": "clearAllText"; "required": false; "isSignal": true; }; "groupBy": { "alias": "groupBy"; "required": false; "isSignal": true; }; "colorKey": { "alias": "colorKey"; "required": false; "isSignal": true; }; "dropdownView": { "alias": "dropdownView"; "required": false; "isSignal": true; }; "gridColumns": { "alias": "gridColumns"; "required": false; "isSignal": true; }; "gridVariation": { "alias": "gridVariation"; "required": false; "isSignal": true; }; "gridSelectionActions": { "alias": "gridSelectionActions"; "required": false; "isSignal": true; }; "gridMinWidth": { "alias": "gridMinWidth"; "required": false; "isSignal": true; }; "gridMaxHeight": { "alias": "gridMaxHeight"; "required": false; "isSignal": true; }; "gridSelectedLabelKeys": { "alias": "gridSelectedLabelKeys"; "required": false; "isSignal": true; }; "gridSelectedLabelSeparator": { "alias": "gridSelectedLabelSeparator"; "required": false; "isSignal": true; }; "gridApplyText": { "alias": "gridApplyText"; "required": false; "isSignal": true; }; "gridClearText": { "alias": "gridClearText"; "required": false; "isSignal": true; }; "showDots": { "alias": "showDots"; "required": false; "isSignal": true; }; "showAvatar": { "alias": "showAvatar"; "required": false; "isSignal": true; }; "avatarKey": { "alias": "avatarKey"; "required": false; "isSignal": true; }; "iconAlt": { "alias": "iconAlt"; "required": false; }; "label": { "alias": "label"; "required": false; }; "required": { "alias": "required"; "required": false; }; "variation": { "alias": "variation"; "required": false; }; "iconSrc": { "alias": "iconSrc"; "required": false; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "maxLabels": { "alias": "maxLabels"; "required": false; "isSignal": true; }; "searchable": { "alias": "searchable"; "required": false; "isSignal": true; }; "allSelect": { "alias": "allSelect"; "required": false; "isSignal": true; }; "clearable": { "alias": "clearable"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "closeOnSelect": { "alias": "closeOnSelect"; "required": false; "isSignal": true; }; "dropdownPosition": { "alias": "dropdownPosition"; "required": false; "isSignal": true; }; "hasError": { "alias": "hasError"; "required": false; }; "errorMessage": { "alias": "errorMessage"; "required": false; }; "appendToBody": { "alias": "appendToBody"; "required": false; "isSignal": true; }; "compareWith": { "alias": "compareWith"; "required": false; "isSignal": true; }; }, { "disabled": "disabledChange"; "open": "open"; "close": "close"; "focus": "focus"; "blur": "blur"; "search": "search"; "clear": "clear"; "change": "change"; "scrollToEnd": "scrollToEnd"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<BkSelect, "bk-select", never, { "items": { "alias": "items"; "required": false; "isSignal": true; }; "bindLabel": { "alias": "bindLabel"; "required": false; "isSignal": true; }; "bindValue": { "alias": "bindValue"; "required": false; "isSignal": true; }; "bindIcon": { "alias": "bindIcon"; "required": false; "isSignal": true; }; "isResponsive": { "alias": "isResponsive"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "notFoundText": { "alias": "notFoundText"; "required": false; "isSignal": true; }; "loadingText": { "alias": "loadingText"; "required": false; "isSignal": true; }; "clearAllText": { "alias": "clearAllText"; "required": false; "isSignal": true; }; "groupBy": { "alias": "groupBy"; "required": false; "isSignal": true; }; "colorKey": { "alias": "colorKey"; "required": false; "isSignal": true; }; "dropdownView": { "alias": "dropdownView"; "required": false; "isSignal": true; }; "gridColumns": { "alias": "gridColumns"; "required": false; "isSignal": true; }; "gridVariation": { "alias": "gridVariation"; "required": false; "isSignal": true; }; "gridSelectionActions": { "alias": "gridSelectionActions"; "required": false; "isSignal": true; }; "gridMinWidth": { "alias": "gridMinWidth"; "required": false; "isSignal": true; }; "gridMaxHeight": { "alias": "gridMaxHeight"; "required": false; "isSignal": true; }; "gridSelectedLabelKeys": { "alias": "gridSelectedLabelKeys"; "required": false; "isSignal": true; }; "gridSelectedLabelSeparator": { "alias": "gridSelectedLabelSeparator"; "required": false; "isSignal": true; }; "gridApplyText": { "alias": "gridApplyText"; "required": false; "isSignal": true; }; "gridClearText": { "alias": "gridClearText"; "required": false; "isSignal": true; }; "showDots": { "alias": "showDots"; "required": false; "isSignal": true; }; "showAvatar": { "alias": "showAvatar"; "required": false; "isSignal": true; }; "avatarKey": { "alias": "avatarKey"; "required": false; "isSignal": true; }; "iconAlt": { "alias": "iconAlt"; "required": false; }; "label": { "alias": "label"; "required": false; }; "required": { "alias": "required"; "required": false; }; "variation": { "alias": "variation"; "required": false; }; "iconSrc": { "alias": "iconSrc"; "required": false; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "maxLabels": { "alias": "maxLabels"; "required": false; "isSignal": true; }; "searchable": { "alias": "searchable"; "required": false; "isSignal": true; }; "allSelect": { "alias": "allSelect"; "required": false; "isSignal": true; }; "clearable": { "alias": "clearable"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "closeOnSelect": { "alias": "closeOnSelect"; "required": false; "isSignal": true; }; "openOnFocus": { "alias": "openOnFocus"; "required": false; "isSignal": true; }; "dropdownPosition": { "alias": "dropdownPosition"; "required": false; "isSignal": true; }; "hasError": { "alias": "hasError"; "required": false; }; "errorMessage": { "alias": "errorMessage"; "required": false; }; "appendToBody": { "alias": "appendToBody"; "required": false; "isSignal": true; }; "compareWith": { "alias": "compareWith"; "required": false; "isSignal": true; }; }, { "disabled": "disabledChange"; "open": "open"; "close": "close"; "focus": "focus"; "blur": "blur"; "search": "search"; "clear": "clear"; "change": "change"; "scrollToEnd": "scrollToEnd"; }, never, never, true, never>;
 }
 
 type BkInputType = 'text' | 'email' | 'password' | 'number' | 'url' | 'tel';
@@ -1301,6 +1357,8 @@ interface CountryOption {
     prefix: string;
     placeholder: string;
 }
+/** Default country list used when a consumer does not provide their own via `[countryOptions]`. */
+declare const DEFAULT_COUNTRY_OPTIONS: CountryOption[];
 declare class BkInput implements OnInit, OnDestroy, AfterViewInit, ControlValueAccessor {
     id: string;
     name: string;
@@ -1331,7 +1389,14 @@ declare class BkInput implements OnInit, OnDestroy, AfterViewInit, ControlValueA
     currencyDecimals: number;
     allowNegative: boolean;
     countryCode: string;
-    countryOptions: CountryOption[];
+    /**
+     * Consumer-supplied country list. When a non-empty list is provided it replaces the
+     * built-in list; when omitted (or given a null/empty value) the DEFAULT_COUNTRY_OPTIONS
+     * are used so the selector always has values to show.
+     */
+    private _countryOptions;
+    set countryOptions(value: CountryOption[] | null | undefined);
+    get countryOptions(): CountryOption[];
     selectedCountry: CountryOption;
     iconOrientation: IconOrientation;
     password: boolean;
@@ -1342,15 +1407,22 @@ declare class BkInput implements OnInit, OnDestroy, AfterViewInit, ControlValueA
     step: number | null;
     maxlength: number | null;
     minlength: number | null;
-    dropdownRef?: ElementRef;
-    selectRef?: ElementRef;
     inputField?: ElementRef<HTMLInputElement>;
     maskDirective?: NgxMaskDirective;
+    phoneOverlay?: CdkConnectedOverlay;
     isFocused: boolean;
     inputValue: string;
     isDropdownOpen: boolean;
     private pendingMaskedValue;
     private isPropagatingViewValue;
+    /**
+     * Country dropdown panel, positioned via CDK Overlay instead of an inline absolute-positioned
+     * div. This escapes clipping inside dialogs/scroll containers and stacks correctly above CDK
+     * Overlay-based content (e.g. `bk-dialog`) regardless of Angular version — see the
+     * "Dropdown & Calendar Overlay Strategy" doc. Primary: below the trigger, left-aligned (mirrors
+     * the old `top-full left-0 mt-1`). Fallback: above the trigger when there's no room below.
+     */
+    readonly phoneDropdownPositions: ConnectedPosition[];
     input: EventEmitter<Event>;
     change: EventEmitter<Event>;
     focus: EventEmitter<Event>;
@@ -1375,13 +1447,31 @@ declare class BkInput implements OnInit, OnDestroy, AfterViewInit, ControlValueA
     ngOnInit(): void;
     ngAfterViewInit(): void;
     ngOnDestroy(): void;
-    onDocumentClick(event: MouseEvent): void;
     handleFocus(event: Event): void;
     handleBlur(event: Event): void;
     handleInput(event: Event): void;
     handleClicked(): void;
     handleChange(event: Event): void;
     toggleDropdown(event?: Event): void;
+    /**
+     * Shared close path for the CDK overlay: outside click, the overlay detaching (e.g. on
+     * destroy), and another `bk-input` phone field opening (see closeAllDropdownsHandler).
+     */
+    closeDropdown(): void;
+    /**
+     * CDK's `reposition` scroll strategy (the default, and what we want — no `block`/`close`
+     * behaviour) only reacts to real `document`/`window` scroll. It has no way to know about an
+     * app shell that scrolls a nested container instead (this one does — see the layout's
+     * `overflow-y-auto` content wrapper), so without this the panel would stay frozen in place
+     * while its trigger scrolls out from under it. A capture-phase listener on `document` still
+     * sees scroll events fired on any descendant scrollable element (scroll doesn't bubble, but
+     * capture does), same trick `bk-custom-calendar` uses for its own popup. rAF-throttled so a
+     * fast scroll doesn't force layout on every tick.
+     */
+    private phoneOverlayScrollRafId;
+    private readonly onPhoneOverlayScroll;
+    private attachPhoneOverlayScrollTracking;
+    private detachPhoneOverlayScrollTracking;
     selectCountry(country: CountryOption): void;
     togglePasswordVisibility(event: Event): void;
     handleIconClick(event: Event): void;
@@ -2367,7 +2457,12 @@ declare class BkHierarchicalSelect implements ControlValueAccessor, AfterViewIni
     /** Search placeholder. */
     searchPlaceholder: _angular_core.InputSignal<string>;
     searchable: _angular_core.InputSignal<boolean>;
-    /** When true, dropdown is positioned fixed and sized to the trigger (use inside modals/popups). */
+    /**
+     * @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: _angular_core.InputSignal<boolean>;
     /** Open above or below the trigger (also used when appendToBody is true for fixed coordinates). */
     dropdownPosition: _angular_core.InputSignal<"top" | "bottom">;
@@ -2398,38 +2493,66 @@ declare class BkHierarchicalSelect implements ControlValueAccessor, AfterViewIni
     searchInput: ElementRef<HTMLInputElement>;
     controlWrapper: ElementRef<HTMLDivElement>;
     dropdownPanel?: ElementRef<HTMLDivElement>;
+    optionsListContainer?: ElementRef<HTMLDivElement>;
+    optionEls?: QueryList<ElementRef<HTMLElement>>;
+    hierarchicalOverlay?: CdkConnectedOverlay;
+    /** Index of the keyboard-highlighted option within the current level (`filteredItems`). */
+    markedIndex: _angular_core.WritableSignal<number>;
     private el;
     placement: _angular_core.WritableSignal<"top" | "bottom">;
-    private originalPanelParent;
-    private originalPanelAnchor;
-    private panelInBody;
+    /**
+     * Panel width, kept equal to the control's — matches the old `dropdownStyle().width`
+     * behaviour. Set on open and re-measured by a ResizeObserver on the control while open, so a
+     * responsive layout keeps the panel in sync.
+     */
+    dropdownWidth: _angular_core.WritableSignal<number | null>;
+    private resizeObserver?;
     constructor();
     ngAfterViewInit(): void;
     ngOnDestroy(): void;
-    private reposition;
     /**
-     * True when the control is fully outside the visible area — either the
-     * viewport or a scrollable/clipping ancestor (e.g. a dialog's scroll body).
+     * CDK's default `reposition` scroll strategy only reacts to real `document`/`window` scroll —
+     * it has no way to know an app shell might scroll a nested container instead (this one
+     * commonly does — dashboard layouts with a fixed header/sidebar and a scrollable content pane).
+     * A capture-phase listener on `document` still sees scroll events fired on any descendant
+     * scrollable element (scroll doesn't bubble, but capture does) — same trick `bk-custom-calendar`,
+     * `bk-input`'s phone dropdown, and `bk-select` already use. rAF-throttled so a fast scroll
+     * doesn't force layout on every tick.
+     */
+    private overlayScrollRafId;
+    private readonly onOverlayScroll;
+    private attachOverlayScrollTracking;
+    private detachOverlayScrollTracking;
+    /** Derives `placement` (for the `[data-position]` inset CSS) from which of
+     *  `hierarchicalDropdownPositions` CDK actually applied — replaces the old hand-rolled space
+     *  comparison now that the fit/flip decision itself lives in CDK. */
+    onPositionChange(event: ConnectedOverlayPositionChange): void;
+    /** Runs after the panel has rendered: reset the level highlight + focus. Position/flip is
+     *  entirely CDK's job now (see hierarchicalDropdownPositions + onPositionChange). */
+    private afterOpenInit;
+    /**
+     * Set the keyboard highlight for the level now on screen: the selected node if
+     * it's in this level, otherwise the first option. -1 when the level is empty,
+     * which keeps nothing highlighted.
      */
-    private isControlClipped;
+    private resetMarked;
     /**
-     * Relocate the panel node to <body> so it truly escapes any transformed or
-     * overflow-clipped ancestor (dialogs, drawers, overflow cards, etc.).
+     * Keyboard navigation. Up/Down move the highlight within the current level;
+     * Right (or Enter on a parent) drills into children; Left goes back a level;
+     * Enter on a leaf selects it; Escape/Tab close.
      */
-    private movePanelToBody;
-    /** Return the panel to its original DOM position before Angular removes it. */
-    private restorePanel;
-    /** Runs after the panel has rendered: relocate (append mode) + position + focus. */
-    private afterOpenInit;
+    onKeyDown(event: KeyboardEvent): void;
+    /** Sync the highlight to a hovered option so mouse and keyboard agree. */
+    markOption(index: number): void;
+    /** Scroll the highlighted option into view within the options list (immediate). */
+    private scrollMarkedIntoView;
+    /** Defer a scroll to the marked option (after a keyboard move re-lays the row). */
+    private scrollToMarked;
+    /** Navigate into a node's children and reset the highlight for the new level. */
+    private enterNode;
     isOpen: _angular_core.WritableSignal<boolean>;
     /** Hidden until its real height has been measured and final placement applied. */
     panelReady: _angular_core.WritableSignal<boolean>;
-    dropdownStyle: _angular_core.WritableSignal<{
-        top?: string;
-        bottom?: string;
-        left: string;
-        width: string;
-    }>;
     searchTerm: _angular_core.WritableSignal<string>;
     /** Breadcrumb stack: each entry is the parent node we navigated into. */
     breadcrumb: _angular_core.WritableSignal<HierarchicalNode[]>;
@@ -2473,16 +2596,16 @@ declare class BkHierarchicalSelect implements ControlValueAccessor, AfterViewIni
     private buildPathTo;
     toggleDropdown(event?: Event): void;
     openDropdown(): void;
+    /** Shared tail of openDropdown(): keep the panel exactly as wide as the control (matches the
+     *  old dropdownStyle().width), start scroll tracking, and flip on. Position/flip itself is
+     *  entirely CDK's job — see hierarchicalDropdownPositions + onPositionChange. */
+    private openPanel;
     /**
-     * Decides which side the panel opens on (auto-flip) and, for append-to-body
-     * mode, computes the fixed coordinates. Re-run on open and on scroll/resize so
-     * the panel snaps to whichever side has room — honouring `dropdownPosition`
-     * when it fits. Inline mode is positioned by CSS via the `placement` signal.
+     * Preferred position list handed to CDK, in try-order — honours `dropdownPosition` first,
+     * falling back to the other side only when the preferred one genuinely doesn't fit. Replaces
+     * the old hand-rolled `applyPlacement()` space comparison entirely.
      */
-    applyPlacement(): void;
-    /** Fixed positioning when appendToBody; inset placement uses CSS + .hierarchical-select-field. */
-    getTop(): string | null;
-    getBottom(): string | null;
+    get hierarchicalDropdownPositions(): ConnectedPosition[];
     closeDropdown(): void;
     goBack(): void;
     onSearchInput(event: Event): void;
@@ -2494,7 +2617,7 @@ declare class BkHierarchicalSelect implements ControlValueAccessor, AfterViewIni
      */
     toggleParentSelection(node: HierarchicalNode, event?: Event): void;
     openFromLabel(event: MouseEvent): void;
-    onClickOutside(e: Event): void;
+    onOverlayOutsideClick(): void;
     private _value;
     private valueSignal;
     onChange: (value: any) => void;
@@ -2535,15 +2658,26 @@ interface ToastMessage extends ToastConfig {
     readonly inline?: boolean;
     leaving: boolean;
 }
+/**
+ * Renders through Angular CDK's Overlay (same primitive `bk-select` / `bk-dialog` / `bk-popover`
+ * already use), positioned with a `GlobalPositionStrategy` rather than a connected one — a toast
+ * has no trigger element to anchor to, it docks to a viewport corner, which is exactly what the
+ * global strategy is for (Angular Material's own snack bar is built the same way).
+ *
+ * The win over the old `document.body.appendChild()` approach isn't just consistency: CDK sets
+ * top/left/right/bottom as inline styles from JS at runtime, via its own prebuilt overlay CSS
+ * (`@angular/cdk/overlay-prebuilt.css`, already imported by consumers) — positioning no longer
+ * depends on this library's own Tailwind `@apply` classes surviving the build pipeline at all.
+ */
 declare class BkToastrService {
-    private readonly appRef;
-    private readonly injector;
+    private readonly overlay;
     private readonly _toasts;
     readonly toasts: _angular_core.Signal<ToastMessage[]>;
     private readonly _position;
     readonly position: _angular_core.Signal<ToastPosition>;
+    private overlayRef;
     private componentRef;
-    constructor(appRef: ApplicationRef, injector: EnvironmentInjector);
+    private buildPositionStrategy;
     private initializeContainer;
     /** Show a toast with full config */
     show(config: ToastConfig): string;
@@ -2981,6 +3115,8 @@ declare class BkMenu implements OnChanges, OnDestroy {
      * already sets it apart from the page.
      */
     submenuBackground: boolean;
+    /** Emit parent clicks as selections as well as toggling their inline submenu. */
+    emitParentClick: boolean;
     /** Id of the currently selected leaf item. Two-way bindable. */
     activeItemId: string;
     /** Tint item icons: dark by default, white on the active (dark) row. */
@@ -3069,7 +3205,7 @@ declare class BkMenu implements OnChanges, OnDestroy {
     onDocumentClick(event: MouseEvent): void;
     onViewportChange(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<BkMenu, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<BkMenu, "bk-menu", never, { "items": { "alias": "items"; "required": false; }; "orientation": { "alias": "orientation"; "required": false; }; "submenuMode": { "alias": "submenuMode"; "required": false; }; "trigger": { "alias": "trigger"; "required": false; }; "size": { "alias": "size"; "required": false; }; "hoverCloseDelay": { "alias": "hoverCloseDelay"; "required": false; }; "singleOpen": { "alias": "singleOpen"; "required": false; }; "submenuBackground": { "alias": "submenuBackground"; "required": false; }; "activeItemId": { "alias": "activeItemId"; "required": false; }; "tintIcons": { "alias": "tintIcons"; "required": false; }; "maxHeight": { "alias": "maxHeight"; "required": false; }; }, { "activeItemIdChange": "activeItemIdChange"; "itemClick": "itemClick"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<BkMenu, "bk-menu", never, { "items": { "alias": "items"; "required": false; }; "orientation": { "alias": "orientation"; "required": false; }; "submenuMode": { "alias": "submenuMode"; "required": false; }; "trigger": { "alias": "trigger"; "required": false; }; "size": { "alias": "size"; "required": false; }; "hoverCloseDelay": { "alias": "hoverCloseDelay"; "required": false; }; "singleOpen": { "alias": "singleOpen"; "required": false; }; "submenuBackground": { "alias": "submenuBackground"; "required": false; }; "emitParentClick": { "alias": "emitParentClick"; "required": false; }; "activeItemId": { "alias": "activeItemId"; "required": false; }; "tintIcons": { "alias": "tintIcons"; "required": false; }; "maxHeight": { "alias": "maxHeight"; "required": false; }; }, { "activeItemIdChange": "activeItemIdChange"; "itemClick": "itemClick"; }, never, never, true, never>;
 }
 
 /** Which edge of the anchor the panel sits against. */
@@ -3092,41 +3228,14 @@ type PopoverAlign = 'start' | 'center' | 'end';
 type PopoverPlacement = 'top' | 'top-left' | 'top-right' | 'bottom' | 'bottom-left' | 'bottom-right' | 'left' | 'left-top' | 'left-bottom' | 'right' | 'right-top' | 'right-bottom';
 /** Every placement, in the order a placement picker should show them. */
 declare const POPOVER_PLACEMENTS: readonly PopoverPlacement[];
-interface Rect {
-    top: number;
-    left: number;
-    width: number;
-    height: number;
-}
-interface Size {
-    width: number;
-    height: number;
-}
-interface PopoverPositionOptions {
-    /** Gap between the anchor and the panel, in px. */
-    offset: number;
-    /** Smallest gap to leave between the panel and the viewport edge, in px. */
-    viewportPadding: number;
-    /** Edge length of the (unrotated) arrow square, in px. */
-    arrowSize: number;
-    /** Whether a panel that doesn't fit may move to the opposite side. */
-    flip: boolean;
-    viewport: Size;
-}
-interface PopoverPosition {
-    /** Viewport coordinates for the panel (it is positioned `fixed`). */
-    top: number;
-    left: number;
-    /** Where the panel actually landed — not necessarily what was requested. */
-    side: PopoverSide;
-    align: PopoverAlign;
-    placement: PopoverPlacement;
-    /**
-     * Distance from the panel's leading edge to the arrow's centre, along the
-     * panel's cross axis (x for top/bottom, y for left/right).
-     */
-    arrowOffset: number;
-}
+/** The side CDK should try when the requested one doesn't fit — only ever the direct
+ *  opposite, never a diagonal, so the alignment word stays meaningful after a flip. */
+declare const OPPOSITE_SIDE: Record<PopoverSide, PopoverSide>;
+/**
+ * How close the arrow's centre may get to a panel corner. The panel is rounded,
+ * so an arrow any nearer would grow out of the curve instead of a flat edge.
+ */
+declare const ARROW_CORNER_GAP = 14;
 /** `top-left` → side `top`, align `start`. A bare side means centred. */
 declare function splitPlacement(placement: PopoverPlacement): {
     side: PopoverSide;
@@ -3138,19 +3247,12 @@ declare function splitPlacement(placement: PopoverPlacement): {
  * the same cross axis, so the alignment word stays meaningful.
  */
 declare function joinPlacement(side: PopoverSide, align: PopoverAlign): PopoverPlacement;
-/**
- * Places the panel against the anchor, then keeps it on screen in two ways:
- *
- * - flip: a panel with no room on the requested side moves to the opposite one,
- *   but only if it actually fits there — flipping into a second bad fit just
- *   trades one clipped edge for another.
- * - shift: the panel slides along its cross axis to stay inside the viewport.
- *   The arrow is measured against the *anchor*, not the panel, so it keeps
- *   pointing at the trigger however far the panel had to slide.
- */
-declare function computePopoverPosition(anchor: Rect, panel: Size, placement: PopoverPlacement, options: PopoverPositionOptions): PopoverPosition;
+/** min wins when the range is inverted (arrow limit wider than the panel itself on a very
+ *  narrow/maxWidth-constrained panel), which keeps the arrow at the panel's leading edge
+ *  rather than pushing it past the trailing one. */
+declare function clamp(value: number, min: number, max: number): number;
 
-declare class BkPopover implements AfterViewInit, OnDestroy {
+declare class BkPopover implements OnDestroy {
     /**
      * One of the 12 placements (`top-left`, `right`, `bottom-right`, …). It is a
      * preference, not a guarantee: a panel with no room moves to the opposite
@@ -3182,11 +3284,33 @@ declare class BkPopover implements AfterViewInit, OnDestroy {
     openDelay: _angular_core.InputSignal<number>;
     closeDelay: _angular_core.InputSignal<number>;
     maxWidth: _angular_core.InputSignal<string>;
+    /**
+     * Fixed panel width, e.g. `'320px'`. Unset by default, so the panel sizes to its content
+     * (capped by `maxWidth`) as before. Set this when the content's natural width shouldn't drive
+     * layout — a form, a fixed-column list — so the panel doesn't reflow between opens as content
+     * changes.
+     *
+     * Overrides `maxWidth` entirely while set — a plain CSS `max-width` would otherwise silently
+     * cap a `width` larger than it (280px default), which is never what setting an exact width was
+     * asking for. Raise `maxWidth` too only if you want *both* a starting width and a cap it can
+     * still grow past for some other reason (e.g. a responsive breakpoint override elsewhere).
+     */
+    width: _angular_core.InputSignal<string | null>;
     panelClass: _angular_core.InputSignal<string>;
     /**
-     * Relocate the panel to <body> while open. `position: fixed` alone resolves
-     * against a transformed ancestor rather than the viewport, so a popover
-     * inside an animated dialog or a transformed card needs this to escape.
+     * The max-width actually applied to the panel: whichever of `width`/`maxWidth` is in effect,
+     * additionally capped to the viewport so the panel can never extend past the screen edge — an
+     * oversized `width` (or a placement CDK could only push so far before running out of room)
+     * shrinks to fit instead of overflowing. Mirrors the old hand-rolled positioner's clamp(), which
+     * guaranteed the panel stayed fully on-screen; a bare CSS `max-width` alone doesn't provide that
+     * once the requested size is close to (or exceeds) the viewport itself.
+     */
+    effectiveMaxWidth: _angular_core.Signal<string>;
+    /**
+     * @deprecated No-op, kept only so existing `[appendToBody]="true"` bindings don't break.
+     * The panel 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: _angular_core.InputSignal<boolean>;
     opened: _angular_core.OutputEmitterRef<void>;
@@ -3194,27 +3318,46 @@ declare class BkPopover implements AfterViewInit, OnDestroy {
     openChange: _angular_core.OutputEmitterRef<boolean>;
     anchorRef: ElementRef<HTMLElement>;
     panelRef?: ElementRef<HTMLElement>;
+    popoverOverlay?: CdkConnectedOverlay;
     private static activeInstance;
-    private readonly host;
     isOpen: _angular_core.WritableSignal<boolean>;
-    /**
-     * Null until the panel has been measured. The template keeps the panel
-     * hidden while it is null: the first frame exists only to measure, and
-     * showing it at 0,0 first would flash it in the corner.
-     */
-    position: _angular_core.WritableSignal<PopoverPosition | null>;
+    /** True once CDK has positioned the panel at least once since open() — the template keeps
+     *  the panel hidden until then, so the first frame (only there to be measured) never flashes
+     *  in the corner. */
+    panelReady: _angular_core.WritableSignal<boolean>;
+    /** Placement actually applied, once known — null before the first (positionChange) fires
+     *  (or once closed), in which case activePlacement()/side() fall back to the requested one. */
+    private resolvedPlacement;
     /** Where the panel actually is, once positioned — may differ from `placement`. */
     activePlacement: _angular_core.Signal<PopoverPlacement>;
     /** Side the panel sits on. Drives which edge the arrow hangs off (see CSS). */
-    side: _angular_core.Signal<_brickclay_org_ui.PopoverSide>;
+    side: _angular_core.Signal<PopoverSide>;
+    /** Distance from the panel's leading edge to the arrow's centre, along the panel's cross
+     *  axis — null until measured. Recomputed from the *actual rendered rects*, not derived from
+     *  CDK's position strategy, so it's correct however CDK had to push/clamp the panel. */
+    private arrowOffsetPx;
+    /** Arrow offset along the panel's cross axis — x on top/bottom, y on left/right. */
+    arrowLeft: _angular_core.Signal<number | null>;
+    arrowTop: _angular_core.Signal<number | null>;
+    /**
+     * Requested position first, its opposite side as a fallback when `flip` allows it — CDK tries
+     * these in order and only falls to the second when the first genuinely doesn't fit. Push (on
+     * by default) then keeps whichever one it lands on inside the viewport, matching the old
+     * hand-rolled shift-along-the-edge behaviour. Each entry is tagged with the side/align it came
+     * from (see positionMeta) so onPositionChange can read back which one CDK actually used.
+     *
+     * A stable field, computed once per open() — not a template-bound getter. A getter re-runs on
+     * every change-detection pass (several times before CDK ever reads it), reassigning
+     * `positionMeta` with fresh object references each time; onPositionChange would then be matching
+     * against an array CDK was never actually given.
+     */
+    popoverPositions: ConnectedPosition[];
+    private positionMeta;
+    private computePositions;
     private openTimer;
     private closeTimer;
     private pointerInPanel;
     private resizeObserver?;
-    private originalPanelParent;
-    private originalPanelAnchor;
-    private panelInBody;
-    ngAfterViewInit(): void;
     ngOnDestroy(): void;
     open(): void;
     close(): void;
@@ -3224,23 +3367,51 @@ declare class BkPopover implements AfterViewInit, OnDestroy {
     onAnchorLeave(): void;
     onPanelEnter(): void;
     onPanelLeave(): void;
-    /** Only attached while open — see open(). Arrow fn so it can be removed. */
-    private onDocumentClick;
+    /**
+     * Click-outside-to-close, driven by CDK's document-level outside-pointer-event dispatcher —
+     * it already excludes clicks on the cdkOverlayOrigin (the anchor) by design, so onAnchorClick()
+     * stays the sole opener/toggler. No backdrop involved, so it doesn't block page/nested-scroll-
+     * container scroll the way a modal's would (see the phone-dropdown writeup for why that matters).
+     */
+    onOverlayOutsideClick(): void;
     onEscape(): void;
-    private reposition;
-    /** Measures the anchor and panel, then hands the maths to the utility. */
-    private measure;
-    /** Arrow offset along the panel's cross axis — x on top/bottom, y on left/right. */
-    arrowLeft: _angular_core.Signal<number | null>;
-    arrowTop: _angular_core.Signal<number | null>;
-    private movePanelToBody;
-    private restorePanel;
+    /**
+     * CDK's default `reposition` scroll strategy only reacts to real `document`/`window` scroll —
+     * it has no way to know an app shell might scroll a nested container instead (this one
+     * commonly does — dashboard layouts with a fixed header/sidebar and a scrollable content pane).
+     * A capture-phase listener on `document` still sees scroll events fired on any descendant
+     * scrollable element (scroll doesn't bubble, but capture does) — same trick `bk-select` and the
+     * `bk-input` phone dropdown already use. Also recomputes the arrow, since `updatePosition()`
+     * sliding the panel along the same side doesn't necessarily fire (positionChange) — that only
+     * fires when the *side* changes, not every pixel of a push/slide. rAF-throttled so a fast
+     * scroll doesn't force layout on every tick.
+     */
+    private overlayScrollRafId;
+    private readonly onOverlayScroll;
+    private attachOverlayScrollTracking;
+    private detachOverlayScrollTracking;
+    /**
+     * Fires whenever CDK (re)applies a position, including the first one after open. Reads back
+     * which of `popoverPositions`' tagged entries CDK actually used — matched by field value
+     * (positionsEqual), not object reference: CDK's position strategy reconstructs its own
+     * ConnectedPosition objects internally, so `event.connectionPair` is never `===` to the object
+     * we handed it even when it's the exact same logical position. Recomputes the arrow from the
+     * real rendered rects, and — on the very first call — starts observing the panel for
+     * content-size changes and reveals it.
+     */
+    onPositionChange(event: ConnectedOverlayPositionChange): void;
+    /**
+     * Arrow offset along the panel's cross axis, measured from the actual rendered anchor/panel
+     * rects rather than reverse-engineered from CDK's position strategy — correct however far CDK
+     * had to push/clamp the panel to stay on screen.
+     */
+    private computeArrowOffset;
     private scheduleClose;
     private cancelOpen;
     private cancelClose;
     private clearTimers;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<BkPopover, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<BkPopover, "bk-popover", ["bkPopover"], { "placement": { "alias": "placement"; "required": false; "isSignal": true; }; "trigger": { "alias": "trigger"; "required": false; "isSignal": true; }; "title": { "alias": "title"; "required": false; "isSignal": true; }; "closable": { "alias": "closable"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "showArrow": { "alias": "showArrow"; "required": false; "isSignal": true; }; "offset": { "alias": "offset"; "required": false; "isSignal": true; }; "flip": { "alias": "flip"; "required": false; "isSignal": true; }; "closeOnClickOutside": { "alias": "closeOnClickOutside"; "required": false; "isSignal": true; }; "closeOnEscape": { "alias": "closeOnEscape"; "required": false; "isSignal": true; }; "openDelay": { "alias": "openDelay"; "required": false; "isSignal": true; }; "closeDelay": { "alias": "closeDelay"; "required": false; "isSignal": true; }; "maxWidth": { "alias": "maxWidth"; "required": false; "isSignal": true; }; "panelClass": { "alias": "panelClass"; "required": false; "isSignal": true; }; "appendToBody": { "alias": "appendToBody"; "required": false; "isSignal": true; }; }, { "opened": "opened"; "closed": "closed"; "openChange": "openChange"; }, never, ["[bkPopoverTrigger]", "*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<BkPopover, "bk-popover", ["bkPopover"], { "placement": { "alias": "placement"; "required": false; "isSignal": true; }; "trigger": { "alias": "trigger"; "required": false; "isSignal": true; }; "title": { "alias": "title"; "required": false; "isSignal": true; }; "closable": { "alias": "closable"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "showArrow": { "alias": "showArrow"; "required": false; "isSignal": true; }; "offset": { "alias": "offset"; "required": false; "isSignal": true; }; "flip": { "alias": "flip"; "required": false; "isSignal": true; }; "closeOnClickOutside": { "alias": "closeOnClickOutside"; "required": false; "isSignal": true; }; "closeOnEscape": { "alias": "closeOnEscape"; "required": false; "isSignal": true; }; "openDelay": { "alias": "openDelay"; "required": false; "isSignal": true; }; "closeDelay": { "alias": "closeDelay"; "required": false; "isSignal": true; }; "maxWidth": { "alias": "maxWidth"; "required": false; "isSignal": true; }; "width": { "alias": "width"; "required": false; "isSignal": true; }; "panelClass": { "alias": "panelClass"; "required": false; "isSignal": true; }; "appendToBody": { "alias": "appendToBody"; "required": false; "isSignal": true; }; }, { "opened": "opened"; "closed": "closed"; "openChange": "openChange"; }, never, ["[bkPopoverTrigger]", "*"], true, never>;
 }
 
 /** One entry in a stacked avatar group. Mirrors the display inputs of bk-avatar. */
@@ -3941,7 +4112,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<"left" | "right" | "top" | "bottom">;
+    tooltipPosition: _angular_core.InputSignal<"top" | "bottom" | "left" | "right">;
     /** Only present when `ellipsis()` is true — see the `@else` branch in the template. */
     private ellipsisTextRef?;
     checkbox: _angular_core.InputSignal<boolean>;
@@ -4258,5 +4429,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 { 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, NEUTRAL_APPEARANCE, POPOVER_PLACEMENTS, computePopoverPosition, 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, PopoverPosition, PopoverPositionOptions, PopoverSide, Rect, ScheduledDateSelection, Size, SortDirection, SpinnerSize, TabIconDirection, TabItem, TableAction, TableBadge, TableColumn, TableIcon, TableRows, TabsColors, TabsOrientation, TabsVariant, TimeConfiguration, ToastConfig, ToastMessage, ToastMethodOptions, ToastPosition, ToastSeverity };
+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 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 };