@koobiq/components 20.1.0 → 20.3.0

package/dropdown/index.d.ts

@@ -1,12 +1,13 @@
 import { AnimationTriggerMetadata, AnimationEvent } from '@angular/animations';
 import * as i0 from '@angular/core';
-import { OnDestroy, TemplateRef, EventEmitter, QueryList, InjectionToken, AfterViewInit, ElementRef, AfterContentInit, OnInit } from '@angular/core';
+import { OnDestroy, Signal, InjectionToken, TemplateRef, EventEmitter, QueryList, ElementRef, AfterContentInit, OnInit } from '@angular/core';
 import { Subject, Observable } from 'rxjs';
 import { FocusOrigin } from '@angular/cdk/a11y';
-import { KbqTitleTextRef, IFocusableOption, KbqComponentColors } from '@koobiq/components/core';
+import { KbqPanelWidth, KbqPanelMinWidth, KbqPanelMaxWidth, KbqTitleTextRef, IFocusableOption, Highlightable, KbqComponentColors, KbqSiblingPopup, KbqPanelWidthOrigin, KbqTriangle } from '@koobiq/components/core';
 import * as i2 from '@koobiq/components/icon';
 import { KbqIcon } from '@koobiq/components/icon';
 import { Direction } from '@angular/cdk/bidi';
+import * as _angular_forms from '@angular/forms';
 import * as i1 from '@angular/cdk/overlay';
 import { ScrollStrategy, Overlay } from '@angular/cdk/overlay';
 
@@ -66,6 +67,62 @@ declare function throwKbqDropdownInvalidPositionX(): void;
  * @docs-private
  */
 declare function throwKbqDropdownInvalidPositionY(): void;
+/**
+ * Throws an exception for the case when `kbqDropdownSearch` is applied to a form field that doesn't
+ * host a `kbqInput`.
+ * @docs-private
+ */
+declare function throwKbqDropdownSearchMissingInputError(): void;
+/**
+ * Throws an exception for the case when `kbqDropdownSearch`'s input isn't bound to a form control, so
+ * there is no query to react to.
+ * @docs-private
+ */
+declare function throwKbqDropdownSearchMissingNgControlError(): void;
+
+/**
+ * Narrow view of `KbqDropdownItem` that `KbqDropdownItemAction` needs. Read through
+ * `KBQ_DROPDOWN_ITEM_ACTION_HOST` instead of importing `KbqDropdownItem` directly: the item
+ * imports `KbqDropdownItemAction` for its `contentChild` query, so an import back from here would
+ * form a circular dependency between the two files, which breaks the query at runtime (the
+ * predicate ends up captured as `undefined`).
+ * @docs-private
+ */
+interface KbqDropdownItemActionHost {
+    readonly disabled: boolean;
+    readonly progress: Signal<boolean>;
+}
+/**
+ * Marks a secondary, independently-focusable/clickable element (e.g. a settings link) projected
+ * inside a `kbq-dropdown-item` alongside the item's own primary action. Requires the item's host
+ * element to be non-interactive (e.g. `<div kbq-dropdown-item>`), since interactive content
+ * cannot validly nest inside another interactive element.
+ */
+declare class KbqDropdownItemAction {
+    private readonly elementRef;
+    private readonly dropdownItem;
+    /**
+     * The `tabindex` this element had before `isInactive()` first forced it to `-1`, so it can be
+     * restored instead of left removed. Plain `[attr.tabindex]` can't do this: co-located host
+     * bindings for the same attribute (e.g. `KbqIconButton`'s own `tabindex`) apply in directive
+     * order and the last one always wins outright, so writing `null` here on the active branch
+     * would strip whatever tabindex the host component set, not just leave it alone.
+     */
+    private originalTabindex;
+    constructor();
+    /** Returns the host DOM element. */
+    getHostElement(): HTMLElement;
+    /** `progress` takes priority over the action, same as `disabled`. */
+    protected isInactive(): boolean;
+    /**
+     * Always stops the click from bubbling to the item's own primary click handler.
+     * Additionally, blocks the action's own default behavior when the parent item is
+     * disabled/loading — `<a>` has no native `disabled`.
+     */
+    protected onClick(event: MouseEvent): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<KbqDropdownItemAction, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<KbqDropdownItemAction, "[kbqDropdownItemAction]", never, {}, {}, never, never, true, never>;
+}
 
 /** Position of the dropdown panel along the x-axis. */
 type KbqDropdownPositionX = 'before' | 'after' | 'center';
@@ -95,12 +152,21 @@ interface KbqDropdownPanel {
     templateRef: TemplateRef<any>;
     closed: EventEmitter<DropdownCloseReason>;
     parent?: KbqDropdownPanel | undefined;
+    /**
+     * @deprecated Has no effect. Use `KbqDropdownTrigger.widthOrigin` to make the panel match
+     * an element other than the trigger. Will be removed in v21.
+     */
     triggerWidth?: string;
+    panelWidth?: Signal<KbqPanelWidth>;
+    panelMinWidth?: Signal<KbqPanelMinWidth>;
+    panelMaxWidth?: Signal<KbqPanelMaxWidth>;
     direction?: Direction;
     lazyContent?: KbqDropdownContent;
     backdropClass?: string;
     hasBackdrop?: boolean;
     items: QueryList<KbqDropdownItem>;
+    /** Whether the panel highlights the active item instead of focusing it, see `KbqDropdownSearch`. */
+    readonly inSearchMode?: Signal<boolean>;
     focusFirstItem(origin?: FocusOrigin): void;
     resetActiveItem(): void;
     setPositionClasses?(x: KbqDropdownPositionX, y: KbqDropdownPositionY): void;
@@ -119,6 +185,24 @@ interface KbqDropdownDefaultOptions {
     backdropClass: string;
     /** Whether the dropdown has a backdrop. */
     hasBackdrop: boolean;
+    /**
+     * Whether nested dropdowns opened from this dropdown's items use a "safe area": while the
+     * pointer moves from a trigger toward its open submenu, sibling items it crosses over on the way
+     * don't prematurely close the submenu.
+     */
+    safeArea?: boolean;
+    /**
+     * Width of the panel. If set to `auto`, the panel will match the trigger width.
+     * If set to null, the panel will grow to match its content.
+     */
+    panelWidth?: KbqPanelWidth;
+    /** Minimum width of the panel. If set to null, only the trigger width applies. */
+    panelMinWidth?: KbqPanelMinWidth;
+    /**
+     * Maximum width of the panel. Caps growth by content only — it never overrides the trigger width or an
+     * explicit `panelWidth`. If null, the `--kbq-dropdown-size-container-width-max` token applies.
+     */
+    panelMaxWidth?: KbqPanelMaxWidth;
 }
 /**
  * Injection token used to provide the parent dropdown to dropdown-specific components.
@@ -134,29 +218,45 @@ declare function KBQ_DROPDOWN_DEFAULT_OPTIONS_FACTORY(): KbqDropdownDefaultOptio
  * This directive is intended to be used inside an kbq-dropdown tag.
  * It exists mostly to set the role attribute.
  */
-declare class KbqDropdownItem implements KbqTitleTextRef, IFocusableOption, AfterViewInit, OnDestroy {
+declare class KbqDropdownItem implements KbqTitleTextRef, KbqDropdownItemActionHost, IFocusableOption, Highlightable, OnDestroy {
     private elementRef;
     private focusMonitor;
     parentDropdownPanel?: KbqDropdownPanel | null | undefined;
     textElement: ElementRef;
     icon: KbqIcon;
+    /** Secondary, independently-focusable icon action projected into the item (e.g. a settings link). */
+    readonly itemAction: i0.Signal<KbqDropdownItemAction | undefined>;
     get disabled(): boolean;
     set disabled(value: boolean);
     private _disabled;
+    /** Whether the dropdown item is in a loading state. */
+    readonly progress: i0.InputSignalWithTransform<boolean, unknown>;
     /** Stream that emits when the dropdown item is hovered. */
     readonly hovered: Subject<KbqDropdownItem>;
     /** Stream that emits when the menu item is focused. */
     readonly focused: Subject<KbqDropdownItem>;
     /** Whether the dropdown item is highlighted. */
     highlighted: boolean;
+    /** Whether the item is the panel's active item while DOM focus is held elsewhere. */
+    protected readonly active: i0.WritableSignal<boolean>;
     /** Whether the dropdown item acts as a trigger for a nested dropdown. */
     isNested: boolean;
     /** @docs-private */
     protected readonly componentColors: typeof KbqComponentColors;
-    ngAfterViewInit(): void;
+    constructor();
     ngOnDestroy(): void;
     resetStyles(): void;
-    /** Focuses the dropdown item. */
+    /** Styles the item as active without focusing it. */
+    setActiveStyles(): void;
+    /** Removes the styles applied by `setActiveStyles`. */
+    setInactiveStyles(): void;
+    /**
+     * Focuses the dropdown item and reveals it.
+     *
+     * The reveal is explicit because the one `focus()` performs implicitly is not portable: WebKit defers
+     * it to a later rendering update, where it lands after — and undoes — any scrolling the reader did in
+     * the meantime. `preventScroll` is therefore always forced on, overriding `options`.
+     */
     focus(origin?: FocusOrigin, options?: FocusOptions): void;
     /** Returns the host DOM element. */
     getHostElement(): HTMLElement;
@@ -166,15 +266,58 @@ declare class KbqDropdownItem implements KbqTitleTextRef, IFocusableOption, Afte
     checkDisabled(event: Event): void;
     /** Emits to the hover stream. Bound via `host` metadata. */
     handleMouseEnter(): void;
+    /**
+     * Lets Tab move focus between the host and `itemAction` without leaving the dropdown
+     * (`stopPropagation` only — the browser's native focus move still happens). Any other Tab
+     * press, i.e. actually leaving the item, is left untouched and still closes the dropdown via
+     * the panel's `FocusKeyManager.tabOut`. Bound via `host` metadata.
+     */
+    protected handleActionKeydown(event: KeyboardEvent): void;
     /** Gets the label to be used when determining whether the option should be focused. */
     getLabel(): string;
     haltDisabledEvents(event: Event): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<KbqDropdownItem, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<KbqDropdownItem, "kbq-dropdown-item, [kbq-dropdown-item]", ["kbqDropdownItem"], { "disabled": { "alias": "disabled"; "required": false; }; }, {}, ["icon"], ["[kbq-icon]", "*"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<KbqDropdownItem, "kbq-dropdown-item, [kbq-dropdown-item]", ["kbqDropdownItem"], { "disabled": { "alias": "disabled"; "required": false; }; "progress": { "alias": "progress"; "required": false; "isSignal": true; }; }, {}, ["itemAction", "icon"], ["[kbq-icon]", "*", "[kbqDropdownItemAction]"], true, never>;
     static ngAcceptInputType_disabled: unknown;
 }
 
-/** Injection token that determines the scroll handling while the dropdown is open. */
+/**
+ * Marks a `kbq-form-field` projected into a `kbq-dropdown` as the panel's search field.
+ *
+ * The panel keeps DOM focus in the field, so arrow keys move the highlighted item while the query
+ * stays editable.
+ */
+declare class KbqDropdownSearch implements AfterContentInit {
+    private readonly formField;
+    /**
+     * Panel this field searches. A nested panel declared inside its parent's content shares the view with
+     * it, so the parent has to be able to tell which of the projected fields is its own.
+     * @docs-private
+     */
+    readonly panel: KbqDropdownPanel | null;
+    /** The form control the query is bound to. */
+    get ngControl(): _angular_forms.NgControl | null;
+    ngAfterContentInit(): void;
+    /** Focuses the search field. */
+    focus(): void;
+    /** Clears the search query. */
+    reset(): void;
+    /** The current search query. */
+    value(): string;
+    /** @docs-private */
+    protected handleClick(event: MouseEvent): void;
+    /** @docs-private */
+    protected handleKeydown(event: KeyboardEvent): void;
+    /** Whether the key still has caret to travel inside the field, rather than acting on the panel. */
+    private movesCaret;
+    static ɵfac: i0.ɵɵFactoryDeclaration<KbqDropdownSearch, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<KbqDropdownSearch, "[kbqDropdownSearch]", ["kbqDropdownSearch"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Injection token that determines the scroll handling while the dropdown is open. The root default keeps the
+ * trigger usable outside `KbqDropdownModule`'s injector; providing the token anywhere still wins over it.
+ */
 declare const KBQ_DROPDOWN_SCROLL_STRATEGY: InjectionToken<() => ScrollStrategy>;
 /** @docs-private */
 declare function KBQ_DROPDOWN_SCROLL_STRATEGY_FACTORY(overlay: Overlay): () => ScrollStrategy;
@@ -201,7 +344,7 @@ declare const NESTED_PANEL_LEFT_PADDING = 8;
  * This directive is intended to be used in conjunction with an kbq-dropdown tag.  It is
  * responsible for toggling the display of the provided dropdown instance.
  */
-declare class KbqDropdownTrigger implements AfterContentInit, OnDestroy {
+declare class KbqDropdownTrigger implements AfterContentInit, OnDestroy, KbqSiblingPopup {
     private overlay;
     private elementRef;
     private viewContainerRef;
@@ -213,10 +356,16 @@ declare class KbqDropdownTrigger implements AfterContentInit, OnDestroy {
     private focusMonitor;
     private readonly overlayContainer;
     private readonly renderer;
+    private readonly ngZone;
     protected readonly isBrowser: boolean;
-    private readonly window;
     private readonly host;
     lastDestroyReason: DropdownCloseReason;
+    /**
+     * Element whose width the panel should match. Defaults to the trigger itself.
+     * Useful when the trigger is only a part of a larger control, e.g. `kbq-split-button`.
+     * @docs-private
+     */
+    widthOrigin?: KbqPanelWidthOrigin;
     /** Position offset of the dropdown in the X axis. */
     offsetX: number;
     /** Position offset of the dropdown in the Y axis. */
@@ -248,16 +397,27 @@ declare class KbqDropdownTrigger implements AfterContentInit, OnDestroy {
      * KBQ_OPTION_ACTION_PARENT contract, which an `OutputEmitterRef` does not support — see #DS-5079.
      */
     readonly dropdownClosed: EventEmitter<void>;
+    /** Emits `true` when the dropdown opens and `false` when it closes. Part of the `KbqSiblingPopup` contract. */
+    readonly openedChange: Observable<boolean>;
     openedBy: Exclude<FocusOrigin, 'program' | null> | undefined;
     /** The text direction of the containing app. */
     get dir(): Direction;
     /** Whether the dropdown is open. */
     get opened(): boolean;
+    /**
+     * Whether the dropdown overlay is currently attached. Part of the `KbqSiblingPopup` contract.
+     *
+     * `opened` is set synchronously right after the overlay is attached and, on close, only once the exit
+     * animation is done — i.e. it stays `true` for the whole time the trigger is busy with its panel,
+     * including the moment `destroy()` restores focus to the trigger.
+     */
+    get isAttached(): boolean;
     private _opened;
     private portal;
     private overlayRef;
     private closeSubscription;
     private hoverSubscription;
+    private widthLockSubscription;
     private classAddedToOverlayContainer;
     constructor();
     ngAfterContentInit(): void;
@@ -276,6 +436,11 @@ declare class KbqDropdownTrigger implements AfterContentInit, OnDestroy {
     focus(origin?: FocusOrigin, options?: FocusOptions): void;
     /** Handles mouse presses on the trigger. */
     handleMousedown(event: MouseEvent): void;
+    /**
+     * Starts safe-area protection when the pointer leaves a trigger whose submenu is open, so a
+     * sibling item crossed on the way to the submenu doesn't prematurely close it.
+     */
+    handleMouseLeave(event: MouseEvent): void;
     /** Handles key presses on the trigger. */
     handleKeydown(event: KeyboardEvent): void;
     /** Handles click events on the trigger. */
@@ -303,6 +468,8 @@ declare class KbqDropdownTrigger implements AfterContentInit, OnDestroy {
      * OverlayRef so that it can be attached to the DOM when open is called.
      */
     private createOverlay;
+    /** Whether the panel should be at least as wide as its trigger. */
+    private get shouldMatchTriggerWidth();
     /**
      * This method builds the configuration object needed to create the overlay, the OverlayState.
      * @returns OverlayConfig
@@ -328,7 +495,15 @@ declare class KbqDropdownTrigger implements AfterContentInit, OnDestroy {
     private handleHover;
     /** Gets the portal that should be attached to the overlay. */
     private getPortal;
-    private getWidth;
+    private getOverlaySize;
+    /**
+     * When the panel hosts a search field, its content-sized width would jump as the field's cleaner
+     * appears or options are filtered. Freeze the width at the opened (empty) state so it stays stable
+     * — mirrors `KbqAbstractSelect.lockOverlayWidthForSearch`.
+     */
+    private lockOverlayWidthForSearch;
+    /** Freezes the overlay pane at its rendered width. */
+    private pinOverlayWidth;
     private addClassToOverlayContainer;
     private removeClassFromOverlayContainer;
     static ɵfac: i0.ɵɵFactoryDeclaration<KbqDropdownTrigger, never>;
@@ -338,15 +513,39 @@ declare class KbqDropdownTrigger implements AfterContentInit, OnDestroy {
     static ngAcceptInputType_demoteOverlay: unknown;
 }
 
+/**
+ * Grace period before switching to a different nested trigger hovered while a safe area is
+ * protecting the currently open submenu. Without it, sweeping the pointer down a long list of
+ * nested triggers on the way to the submenu would flicker each row's submenu open and closed.
+ */
+declare const NESTED_HOVER_SWITCH_DELAY = 50;
 declare class KbqDropdownStaticContent {
     static ɵfac: i0.ɵɵFactoryDeclaration<KbqDropdownStaticContent, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<KbqDropdownStaticContent, "[kbqDropdownStaticContent]", never, {}, {}, never, never, true, never>;
 }
+/** Footer that is rendered below the dropdown options panel. */
+declare class KbqDropdownFooter {
+    static ɵfac: i0.ɵɵFactoryDeclaration<KbqDropdownFooter, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<KbqDropdownFooter, "[kbqDropdownFooter], kbq-dropdown-footer", never, {}, {}, never, never, true, never>;
+}
 declare class KbqDropdown implements AfterContentInit, KbqDropdownPanel, OnInit, OnDestroy {
     private elementRef;
     private ngZone;
+    private document;
     private defaultOptions;
+    private readonly destroyRef;
+    private readonly panelFormField;
+    /**
+     * Signal content queries carry `descendants: true`, and a nested panel declared inside this one's
+     * content is part of the same view — so the match has to be narrowed to the fields this panel owns,
+     * the way `updateDirectDescendants` narrows the items.
+     */
+    private readonly searches;
     private readonly search;
+    /** Whether the dropdown projects a search form-field. @docs-private */
+    readonly hasSearch: Signal<boolean>;
+    /** Whether the panel highlights the active item instead of focusing it. @docs-private */
+    readonly inSearchMode: Signal<boolean>;
     readonly navigationWithWrap: i0.InputSignal<boolean>;
     /** Position of the dropdown in the X axis. */
     get xPosition(): KbqDropdownPositionX;
@@ -375,6 +574,10 @@ declare class KbqDropdown implements AfterContentInit, KbqDropdownPanel, OnInit,
     private _overlapTriggerX;
     private _overlapTriggerY;
     private _hasBackdrop;
+    /**
+     * @deprecated Has no effect. Use `KbqDropdownTrigger.widthOrigin` to make the panel match
+     * an element other than the trigger. Will be removed in v21.
+     */
     triggerWidth: string;
     /** Config object to be passed into the dropdown panel's `[class]` binding */
     classList: {
@@ -392,6 +595,35 @@ declare class KbqDropdown implements AfterContentInit, KbqDropdownPanel, OnInit,
     direction: Direction;
     /** Class to be added to the backdrop element. */
     backdropClass: string;
+    /**
+     * Width of the panel. If set to `auto`, the panel will match the trigger width, but will never be
+     * narrower than `panelMinWidth`. If set to null, the panel will grow to match its content.
+     * Any other value is used as an exact width, and `panelMinWidth` is not applied.
+     */
+    readonly panelWidth: i0.InputSignal<KbqPanelWidth>;
+    /**
+     * Minimum width of the panel in pixels. The panel is never narrower than this, nor than its trigger.
+     */
+    readonly panelMinWidth: i0.InputSignalWithTransform<KbqPanelMinWidth, unknown>;
+    /**
+     * Maximum width of the panel in pixels. Caps how far the panel grows with its content — it never makes
+     * the panel narrower than the trigger, and never clamps an explicit `panelWidth`.
+     * When null, the `--kbq-dropdown-size-container-width-max` token applies.
+     */
+    readonly panelMaxWidth: i0.InputSignalWithTransform<KbqPanelMaxWidth, unknown>;
+    /**
+     * Whether nested dropdowns opened from this dropdown's items use a "safe area": while the
+     * pointer moves from a trigger toward its open submenu, sibling items it crosses over on the way
+     * don't prematurely close the submenu.
+     */
+    readonly safeArea: i0.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * `panelMinWidth` rendered as a CSS length for the `--kbq-dropdown-size-container-width-min`
+     * token, so the panel's CSS `min-width` floor tracks the input — mirroring how `panelMaxWidth`
+     * drives `max-width`. Non-finite input (e.g. `null`) leaves the token's static default in place.
+     * @docs-private
+     */
+    protected readonly panelMinWidthToken: Signal<string | null>;
     /** @docs-private */
     templateRef: TemplateRef<any>;
     /**
@@ -407,28 +639,95 @@ declare class KbqDropdown implements AfterContentInit, KbqDropdownPanel, OnInit,
     readonly closed: EventEmitter<void | "click" | "keydown" | "tab">;
     private previousPanelClass;
     private keyManager;
+    private activeDescendantKeyManager?;
+    private focusKeyManager?;
+    private focusOrigin;
     /** Only the direct descendant menu items. */
     private directDescendantItems;
     /** Subscription to tab events on the dropdown panel */
     private tabSubscription;
+    /** Cleans up the safe-area `mousemove` listener. `null` when no safe area is being tracked. */
+    private safeAreaCleanup;
+    /** The nested trigger currently protected by the active safe area, if any. */
+    private safeAreaOwner;
+    /**
+     * The most recently hovered item, tracked independently of the safe area so that leaving it
+     * straight onto a sibling's nested trigger can switch to it immediately instead of waiting for a
+     * `mouseenter` that already happened.
+     */
+    private currentHovered;
+    /** Emits when the pointer reaches the panel the active safe area protects. */
+    private readonly panelReached;
+    /** Emits the sibling trigger that should open once a forced switch has closed the current one. */
+    private readonly switchTarget;
+    /** Watches for a forced switch to a sibling trigger while a safe area is active. */
+    private switchTargetSubscription;
+    constructor();
     ngOnInit(): void;
     ngAfterContentInit(): void;
     ngOnDestroy(): void;
     /** Stream that emits whenever the hovered dropdown item changes. */
     hovered(): Observable<KbqDropdownItem>;
+    /**
+     * Tracks the pointer against `triangle` to protect `owner`'s open submenu, closing it via
+     * `onExit` if the pointer leaves the triangle without first reaching `panelRect`. Meanwhile, if a
+     * different nested trigger is hovered, `switchTarget()` emits it — immediately if it's outside
+     * the triangle, otherwise after a grace period (see `NESTED_HOVER_SWITCH_DELAY`). Replaces any
+     * safe area already being tracked.
+     * @docs-private
+     */
+    activateSafeArea(owner: KbqDropdownItem, triangle: KbqTriangle, panelRect: DOMRect, onExit: () => void): void;
+    /**
+     * Stops tracking the current safe area, if any.
+     * @docs-private
+     */
+    deactivateSafeArea(): void;
+    /**
+     * Whether a safe area is currently being tracked.
+     * @docs-private
+     */
+    isSafeAreaActive(): boolean;
+    /**
+     * Whether `item` is the nested trigger currently protected by an active safe area.
+     * @docs-private
+     */
+    isSafeAreaOwner(item: KbqDropdownItem): boolean;
+    /**
+     * Stream that emits when the pointer reaches the panel the active safe area protects (as opposed
+     * to leaving the safe area, which closes the panel instead).
+     * @docs-private
+     */
+    onPanelReached(): Observable<void>;
+    /**
+     * Stream that emits the sibling trigger that should open once a forced safe-area switch has
+     * closed the trigger it was protecting.
+     * @docs-private
+     */
+    onSwitchTarget(): Observable<KbqDropdownItem>;
     /** Handle a keyboard event from the dropdown, delegating to the appropriate action. */
     handleKeydown(event: KeyboardEvent): void;
     /**
-     * Focus the first item in the dropdown.
+     * Applies the panel's initial focus, see `applyInitialFocus`.
      * @param origin Action from which the focus originated. Used to set the correct styling.
      */
     focusFirstItem(origin?: FocusOrigin): void;
     /**
-     * Applies focus when the dropdown is opened. When opened by mouse or touch, the first item
-     * should not be highlighted, so the panel itself is focused instead — keyboard events still
-     * reach the panel and the first arrow key press will highlight the first item.
+     * Applies focus when the dropdown is opened.
+     *
+     * A projected search field takes the caret for every origin and keeps it: the first arrow key press
+     * only highlights an item. Without one, opening by mouse or touch focuses the panel rather than an
+     * item, so that nothing is highlighted while keyboard events still reach the panel; any other origin
+     * highlights the first item. A submenu of a search panel focuses nothing at all, so that hovering it
+     * does not pull the caret out of the query.
      */
     private applyInitialFocus;
+    /**
+     * Moves focus back into the projected search field, reporting whether there was one. A nested panel
+     * restores focus through this instead of onto its trigger item, which would strand the caret outside
+     * the query.
+     * @docs-private
+     */
+    restoreFocus(): boolean;
     /** Moves DOM focus onto the dropdown panel so that keydown events keep being handled. */
     private focusPanel;
     /**
@@ -452,6 +751,21 @@ declare class KbqDropdown implements AfterContentInit, KbqDropdownPanel, OnInit,
     onAnimationDone(event: AnimationEvent): void;
     onAnimationStart(event: AnimationEvent): void;
     close(): void;
+    /**
+     * With a search field the caret has to stay in the input, so the active item is only highlighted and
+     * typeahead is left off — it would race the query the user is typing.
+     */
+    private initKeyManager;
+    /** Which mode the installed key manager serves; the wanted one is `inSearchMode()`. */
+    private keyManagerInstalledForSearch;
+    private configureKeyManager;
+    private setFocusOrigin;
+    private isActiveItemStale;
+    /**
+     * Reveals the highlighted item, which the browser only does on its own for real focus. Mirrors the
+     * reveal `kbqFocusAndReveal` performs for focused elements.
+     */
+    private revealActiveItem;
     /**
      * Sets up a stream that will keep track of any newly-added menu items and will update the list
      * of direct descendants. We collect the descendants this way, because `items` can include
@@ -460,14 +774,14 @@ declare class KbqDropdown implements AfterContentInit, KbqDropdownPanel, OnInit,
      */
     private updateDirectDescendants;
     static ɵfac: i0.ɵɵFactoryDeclaration<KbqDropdown, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<KbqDropdown, "kbq-dropdown", ["kbqDropdown"], { "navigationWithWrap": { "alias": "navigationWithWrap"; "required": false; "isSignal": true; }; "xPosition": { "alias": "xPosition"; "required": false; }; "yPosition": { "alias": "yPosition"; "required": false; }; "overlapTriggerY": { "alias": "overlapTriggerY"; "required": false; }; "overlapTriggerX": { "alias": "overlapTriggerX"; "required": false; }; "hasBackdrop": { "alias": "hasBackdrop"; "required": false; }; "panelClass": { "alias": "class"; "required": false; }; "backdropClass": { "alias": "backdropClass"; "required": false; }; }, { "closed": "closed"; }, ["search", "lazyContent", "items"], ["*", "[kbqDropdownStaticContent]"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<KbqDropdown, "kbq-dropdown", ["kbqDropdown"], { "navigationWithWrap": { "alias": "navigationWithWrap"; "required": false; "isSignal": true; }; "xPosition": { "alias": "xPosition"; "required": false; }; "yPosition": { "alias": "yPosition"; "required": false; }; "overlapTriggerY": { "alias": "overlapTriggerY"; "required": false; }; "overlapTriggerX": { "alias": "overlapTriggerX"; "required": false; }; "hasBackdrop": { "alias": "hasBackdrop"; "required": false; }; "panelClass": { "alias": "class"; "required": false; }; "backdropClass": { "alias": "backdropClass"; "required": false; }; "panelWidth": { "alias": "panelWidth"; "required": false; "isSignal": true; }; "panelMinWidth": { "alias": "panelMinWidth"; "required": false; "isSignal": true; }; "panelMaxWidth": { "alias": "panelMaxWidth"; "required": false; "isSignal": true; }; "safeArea": { "alias": "safeArea"; "required": false; "isSignal": true; }; }, { "closed": "closed"; }, ["panelFormField", "searches", "lazyContent", "items"], ["*", "[kbqDropdownFooter], kbq-dropdown-footer", "[kbqDropdownStaticContent]"], true, never>;
 }
 
 declare class KbqDropdownModule {
     static ɵfac: i0.ɵɵFactoryDeclaration<KbqDropdownModule, never>;
-    static ɵmod: i0.ɵɵNgModuleDeclaration<KbqDropdownModule, never, [typeof i1.OverlayModule, typeof i2.KbqIconModule, typeof KbqDropdownStaticContent, typeof KbqDropdown, typeof KbqDropdownItem, typeof KbqDropdownTrigger, typeof KbqDropdownContent], [typeof KbqDropdown, typeof KbqDropdownItem, typeof KbqDropdownTrigger, typeof KbqDropdownContent, typeof KbqDropdownStaticContent]>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<KbqDropdownModule, never, [typeof i1.OverlayModule, typeof i2.KbqIconModule, typeof KbqDropdownStaticContent, typeof KbqDropdown, typeof KbqDropdownItem, typeof KbqDropdownItemAction, typeof KbqDropdownTrigger, typeof KbqDropdownContent, typeof KbqDropdownFooter, typeof KbqDropdownSearch], [typeof KbqDropdown, typeof KbqDropdownItem, typeof KbqDropdownItemAction, typeof KbqDropdownTrigger, typeof KbqDropdownContent, typeof KbqDropdownStaticContent, typeof KbqDropdownFooter, typeof KbqDropdownSearch]>;
     static ɵinj: i0.ɵɵInjectorDeclaration<KbqDropdownModule>;
 }
 
-export { KBQ_DROPDOWN_DEFAULT_OPTIONS, KBQ_DROPDOWN_DEFAULT_OPTIONS_FACTORY, KBQ_DROPDOWN_HOST, KBQ_DROPDOWN_PANEL, KBQ_DROPDOWN_SCROLL_STRATEGY, KBQ_DROPDOWN_SCROLL_STRATEGY_FACTORY, KBQ_DROPDOWN_SCROLL_STRATEGY_FACTORY_PROVIDER, KbqDropdown, KbqDropdownContent, KbqDropdownItem, KbqDropdownModule, KbqDropdownStaticContent, KbqDropdownTrigger, NESTED_PANEL_LEFT_PADDING, NESTED_PANEL_TOP_PADDING, fadeInItems, kbqDropdownAnimations, throwKbqDropdownInvalidPositionX, throwKbqDropdownInvalidPositionY, throwKbqDropdownMissingError, transformDropdown };
+export { KBQ_DROPDOWN_DEFAULT_OPTIONS, KBQ_DROPDOWN_DEFAULT_OPTIONS_FACTORY, KBQ_DROPDOWN_HOST, KBQ_DROPDOWN_PANEL, KBQ_DROPDOWN_SCROLL_STRATEGY, KBQ_DROPDOWN_SCROLL_STRATEGY_FACTORY, KBQ_DROPDOWN_SCROLL_STRATEGY_FACTORY_PROVIDER, KbqDropdown, KbqDropdownContent, KbqDropdownFooter, KbqDropdownItem, KbqDropdownItemAction, KbqDropdownModule, KbqDropdownSearch, KbqDropdownStaticContent, KbqDropdownTrigger, NESTED_HOVER_SWITCH_DELAY, NESTED_PANEL_LEFT_PADDING, NESTED_PANEL_TOP_PADDING, fadeInItems, kbqDropdownAnimations, throwKbqDropdownInvalidPositionX, throwKbqDropdownInvalidPositionY, throwKbqDropdownMissingError, throwKbqDropdownSearchMissingInputError, throwKbqDropdownSearchMissingNgControlError, transformDropdown };
 export type { DropdownCloseReason, DropdownPositionX, DropdownPositionY, KbqDropdownDefaultOptions, KbqDropdownPanel, KbqDropdownPositionX, KbqDropdownPositionY };

package/dynamic-translation/index.d.ts

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { TemplateRef, Signal } from '@angular/core';
+import { Signal, TemplateRef } from '@angular/core';
 
 /**
  * @docs-private