import { KbqTimezoneModule } from '@koobiq/components/timezone';

KbqTimezoneOption

componentCopy link to KbqTimezoneOption
@Component({ selector: 'kbq-timezone-option', exportAs: 'kbqTimezoneOption' })
class KbqTimezoneOption extends KbqOption {
    readonly highlightText = input<string | readonly string[]>();
    readonly foldDiacritics = input<boolean>(false);
    timezone = input<KbqTimezoneZone>();
    value = input<any>();
    viewValue = input<string | undefined>();
    readonly selectable = input<boolean>(true);
    readonly userSelect = input<boolean>(false);
    showCheckbox = input<boolean | undefined>();
    disabled = input<boolean>(false);
    readonly tooltipContentWrapper: Signal<ElementRef<HTMLElement>>;
    readonly tooltipContent: Signal<ElementRef<HTMLElement>>;
    get tooltipViewValue(): string;
    readonly group: KbqOptgroup | null;
    get textElement(): ElementRef<HTMLElement> | undefined;
    readonly onSelectionChange: EventEmitter<KbqOptionSelectionChange>;
    readonly stateChanges: Subject<void>;
    get multiple(): boolean;
    get id(): string;
    get selected(): boolean;
    get active(): boolean;
    getLabel(): string;
    select(emitEvent?: boolean): void;
    deselect(emitEvent?: boolean): void;
    focus(): void;
    setActiveStyles(): void;
    setInactiveStyles(): void;
    handleKeydown(event: KeyboardEvent): void;
    selectViaInteraction(): void;
    getTabIndex(): string;
    getHostElement(): HTMLElement;
}
foldDiacriticsinputCopy link to foldDiacriticsboolean

Whether highlightText was matched with diacritic folding (e.g. via createSearchPredicate) — see kbqHighlightBackground.

timezoneinputCopy link to timezoneKbqTimezoneZone

The time zone the option stands for.

valueinputCopy link to valueany

The id of the time zone, unless no time zone is bound.

viewValueinputCopy link to viewValuestring | undefined

The whole zone as one line: the offset, the city and every city the zone covers.

showCheckboxinputCopy link to showCheckboxboolean | undefined

Whether the option renders a checkbox. Follows the multiple selection mode of the parent until bound.

disabledinputCopy link to disabledboolean

Whether the option is disabled, through its own input or its group.

tooltipViewValueCopy link to tooltipViewValuestring

The same line as viewValue, but with the city list narrowed by highlightText exactly as the rendered list is. The overflow tooltip shows this one, so it never lists a city the search has just filtered out of the option under it.

textElementCopy link to textElementElementRef<HTMLElement> | undefined

Element holding the text of the option, measured by kbq-title.

onSelectionChangeCopy link to onSelectionChangeEventEmitter<KbqOptionSelectionChange>

Event emitted when the option is selected or deselected. A stream rather than an output(): it keeps emitting after the option is destroyed, because a select holds on to a selected option that its search or virtual scroll removed.

stateChangesCopy link to stateChangesSubject<void>

Emits when the state of the option changes and any parents have to be notified.

multipleCopy link to multipleboolean

Whether the wrapping component is in multiple selection mode.

activeCopy link to activeboolean

Whether or not the option is currently active and ready to be selected. An active option displays styles as if it is focused, but the focus is actually retained somewhere else. This comes in handy for components like autocomplete where focus must remain on the input.

getLabel()Copy link to getLabel()string

The city, which is what typeahead matches. viewValue opens with the offset, so every option would start with UTC and typing a city's first letters would never move past the first one — and a zone west of UTC is written with U+2212, which a keyboard cannot type at all.

focus()Copy link to focus()void

Moves keyboard focus to this option and reveals it — see kbqFocusAndReveal.

setActiveStyles()Copy link to setActiveStyles()void

This method sets display styles on the option to make it appear active. This is used by the ActiveDescendantKeyManager so key events will display the proper options as active on arrow key events.

setInactiveStyles()Copy link to setInactiveStyles()void

This method removes display styles on the option that made it appear active. This is used by the ActiveDescendantKeyManager so key events will display the proper options as active on arrow key events.

handleKeydown()Copy link to handleKeydown()void

Ensures the option is selected when activated from the keyboard.

selectViaInteraction()Copy link to selectViaInteraction()void

Selects the option while indicating the selection came from the user. Used to determine if the select's view -> model callback should be invoked.

KbqTimezoneSelect

componentCopy link to KbqTimezoneSelect
@Component({ selector: 'kbq-timezone-select', exportAs: 'kbqTimezoneSelect' })
class KbqTimezoneSelect extends KbqSelect {
    readonly hiddenItemsText = input<string>();
    readonly hiddenItemsTextFormatter = input<(hiddenItemsText: string, hiddenItems: number) => string>(
        (hiddenItemsText, hiddenItems) => hiddenItemsText.replace('{{ number }}', hiddenItems.toString())
    );
    readonly ariaLabel = input<string | null>(null, {
        alias: 'aria-label'
    });
    readonly showPreselectedValues = input<boolean>(false);
    readonly triggerValuesLimit = input<number>(0);
    readonly panelClass = input<string | string[] | Set<string> | Record<string, boolean>>();
    readonly backdropClass = input<string>(
        'cdk-overlay-transparent-backdrop'
    );
    readonly errorStateMatcher = input<ErrorStateMatcher>();
    readonly sortComparator = input<(a: KbqOptionBase, b: KbqOptionBase, options: KbqOptionBase[]) => number>();
    readonly multiline = input<boolean>(false);
    readonly multilineOptions = input<boolean>(
        this.defaultOptions?.multilineOptions ?? false
    );
    readonly searchMinOptionsThreshold = input<'auto' | number | undefined>();
    readonly scrolledToBottomOffset = input<number>(0);
    readonly hasBackdrop = input<boolean>(false);
    readonly placeholder = input<string>();
    readonly required = input<boolean>(false);
    multiple = input<boolean>(false);
    readonly compareWith = input<(o1: any, o2: any) => boolean>(
        (o1, o2) => o1 === o2
    );
    readonly virtualOptionFactory = input<(value: any) => KbqVirtualOption>();
    readonly clearPredicate = input<(option: KbqOptionBase) => boolean>(
        this.defaultOptions?.clearPredicate ?? ((option) => !option.disabled)
    );
    readonly selectAllToggle = input<boolean>(false);
    readonly selectAll = input<boolean>(false);
    selectAllHandler = input<((event: KeyboardEvent, select: KbqSelect) => void) | undefined>();
    readonly panelWidth = input<KbqPanelWidth>(
        this.defaultOptions?.panelWidth ?? null
    );
    readonly panelMinWidth = input<KbqPanelMinWidth>(
        this.defaultOptions?.panelMinWidth === undefined
            ? KBQ_PANEL_DEFAULT_MIN_WIDTH
            : this.defaultOptions.panelMinWidth
    );
    readonly panelMaxWidth = input<KbqPanelMaxWidth>(
        this.defaultOptions?.panelMaxWidth === undefined ? null : this.defaultOptions.panelMaxWidth
    );
    readonly panelMaxHeight = input<KbqPanelMaxHeight>(
        this.defaultOptions?.panelMaxHeight === undefined ? null : this.defaultOptions.panelMaxHeight
    );
    readonly value = model<any>();
    readonly id = input<string | undefined>();
    readonly disabled = input<boolean>(false);
    readonly beforeOpened = output<void>();
    readonly selectionChange = output<KbqSelectChange>();
    readonly onSelectAll = output<KbqSelectAllEvent<KbqOption, KbqSelect>>();
    readonly scrolledToBottom = output<void>();
    readonly customTrigger: Signal<KbqTimezoneSelectTrigger | undefined>;
    readonly timezoneLocaleConfiguration: Signal<KbqTimezoneLocaleConfiguration>;
    defaultErrorStateMatcher: ErrorStateMatcher;
    elementRef: ElementRef<HTMLElement>;
    parentForm: NgForm | null;
    parentFormGroup: FormGroupDirective | null;
    ngControl: NgControl | null;
    readonly errorState: Signal<boolean>;
    controlType: string;
    readonly isNativeLabelSupported: false;
    readonly hiddenItems: Signal<number>;
    triggerFontSize: number;
    selectionModel: SelectionModel<KbqOptionBase>;
    previousSelectionModelSelected: KbqOptionBase[];
    keyManager: ActiveDescendantKeyManager<KbqOption>;
    transformOrigin: string;
    panelDoneAnimatingStream: Subject<string>;
    scrollStrategy: ScrollStrategy;
    positions: ConnectedPosition[];
    readonly trigger: Signal<ElementRef<any> | undefined>;
    readonly panel: Signal<ElementRef<any> | undefined>;
    readonly optionsContainer: Signal<ElementRef<any>>;
    readonly selectAllOption: Signal<KbqOption | undefined>;
    readonly footer: Signal<ElementRef<any> | undefined>;
    readonly cdkVirtualForOf: Signal<CdkVirtualForOf<any> | undefined>;
    readonly virtualScrollViewport: Signal<CdkVirtualScrollViewport | undefined>;
    get tags(): QueryList<KbqTag>;
    readonly customMatcher: Signal<KbqSelectMatcher | undefined>;
    readonly customTagTemplateRef: Signal<TemplateRef<any> | undefined>;
    get options(): QueryList<KbqOption>;
    readonly optionGroups: Signal<readonly KbqOptgroup[]>;
    readonly search: Signal<KbqSelectSearch | undefined>;
    readonly searchEmpty: Signal<KbqSelectSearchEmptyResult | undefined>;
    readonly optionSelectionChanges: Observable<KbqOptionSelectionChange>;
    readonly openedChange: EventEmitter<boolean>;
    readonly openedStream: Observable<void>;
    readonly closedStream: Observable<void>;
    readonly focused: Signal<boolean>;
    panelOpen: boolean;
    get isAttached(): boolean;
    withVirtualScroll: boolean;
    get isEmptySearchResult(): boolean;
    get allOptionsSelected(): boolean;
    get selectAllState(): KbqPseudoCheckboxState;
    get selected(): KbqOptionBase | KbqOptionBase[];
    get triggerValue(): string;
    get triggerValues(): KbqOptionBase[];
    readonly empty: Signal<boolean>;
    get noOptions(): boolean;
    get firstSelected(): KbqOptionBase | null;
    get firstFiltered(): boolean;
    get multiSelection(): boolean;
    calculateHiddenItems: () => void;
    updateErrorState(): void;
    resetSearch(): void;
    toggle(): void;
    open(): void;
    openPanel(): void;
    close(): void;
    isRtl(): boolean;
    handleKeydown(event: KeyboardEvent): void;
    onFocus(): void;
    onBlur(): void;
    onAttached(): void;
    getPanelTheme(): string;
    focus(): void;
    onRemoveMatcherItem(option: KbqOptionBase, $event: Event): void;
    getItemHeight(): number;
    handleClick($event: MouseEvent): void;
}
hiddenItemsTextinputCopy link to hiddenItemsTextstring

Template string for the hidden items counter. Supports the {{ number }} placeholder.

Takes precedence over the value the locale service provides, and keeps it for the whole lifetime of the select — switching the locale no longer overwrites what the consumer asked for.

hiddenItemsTextFormatterinputCopy link to hiddenItemsTextFormatter(hiddenItemsText: string, hiddenItems: number) => string

Formats the hidden items counter.

aria-labelinputCopy link to aria-labelstring | null

Accessible name of the trigger and of the option list.

Only needed for a select rendered without a kbq-form-field label — with one, the label names both.

showPreselectedValuesinputCopy link to showPreselectedValuesboolean

Determines whether preselected values are displayed.

triggerValuesLimitinputCopy link to triggerValuesLimitnumber

Specifies the maximum number of trigger values allowed. This constant limits the size of the trigger values array to ensure performance and prevent excessive memory usage. A value of 0 indicates that there is no limit.

panelClassinputCopy link to panelClassstring | string[] | Set<string> | Record<string, boolean>

Classes to be passed to the select panel. Supports the same syntax as the [class] binding.

backdropClassinputCopy link to backdropClassstring

Classes to be passed to the overlay backdrop.

errorStateMatcherinputCopy link to errorStateMatcherErrorStateMatcher

Object used to control when error messages are shown.

sortComparatorinputCopy link to sortComparator(a: KbqOptionBase, b: KbqOptionBase, options: KbqOptionBase[]) => number

Function used to sort the values in a select in multiple mode. Follows the same logic as Array.prototype.sort.

Without one the values are emitted in panel order — the order the options are declared in, not the order they were picked in. A value whose option is not rendered (a KbqVirtualOption under virtual scroll or showPreselectedValues) has no place in that order and sorts after everything that has.

multilineinputCopy link to multilineboolean

Whether to use a multiline matcher or not. Default is false. When true, allows multiple lines of text in the selected value display.

multilineOptionsinputCopy link to multilineOptionsboolean

Whether option text wraps onto multiple lines. When panelWidth is nullish, the panel matches the trigger width; an explicit panelWidth takes precedence. Not supported with cdk-virtual-scroll-viewport: the panel modifier and automatic width fallback are not applied. Defaults to false.

searchMinOptionsThresholdinputCopy link to searchMinOptionsThreshold'auto' | number | undefined

Controls when the search functionality is displayed based on the number of available options.

Automatically enables search hiding if value provided, even if defaultOptions.searchMinOptionsThreshold is provided.

Accepts 'auto', which resolves to KBQ_SELECT_SEARCH_MIN_OPTIONS_THRESHOLD; the getter therefore reports the resolved number, never 'auto'. Defaults to undefined.

scrolledToBottomOffsetinputCopy link to scrolledToBottomOffsetnumber

Distance in pixels from the bottom of the options panel at which scrolledToBottom fires. Default 0 — emits only when the panel is fully scrolled to the bottom.

hasBackdropinputCopy link to hasBackdropboolean

Whether the overlay should have a backdrop. When true, clicking the backdrop will close the select.

placeholderinputCopy link to placeholderstring

Placeholder text to be shown when no value is selected. Displayed in the trigger when the select is closed and no value is selected.

requiredinputCopy link to requiredboolean

Whether the select is required. Affects validation and display of placeholder.

multipleinputCopy link to multipleboolean

Whether multiple options can be selected. Note: This cannot be changed dynamically after initialization.

compareWithinputCopy link to compareWith(o1: any, o2: any) => boolean

Function to compare the option values with the selected values. The first argument is a value from an option. The second is a value from the selection. Should return true if the values match. Defaults to strict equality comparison.

virtualOptionFactoryinputCopy link to virtualOptionFactory(value: any) => KbqVirtualOption

Factory used to construct a KbqVirtualOption for selected values whose KbqOption is not currently rendered (e.g. virtual scroll out of viewport, programmatically set initial value, showPreselectedValues).

Required when option values are objects so the trigger (and tags in multiple mode) can render a human-readable label. Also lets consumers customise per-value disabled state or any future KbqVirtualOption fields without adding new @Inputs.

Defaults to new KbqVirtualOption(value, this.disabled()), which is correct for primitive values where value itself is the display label.

clearPredicateinputCopy link to clearPredicate(option: KbqOptionBase) => boolean

Decides which selected options the projected KbqCleaner removes: return true to clear the option, false to keep it. Disabled options are kept by default. Bind a stable reference — a new function on every change detection re-runs the predicate over the whole selection.

Not consulted by writeValue / reset(), which always clear everything.

selectAllToggleinputCopy link to selectAllToggleboolean

When true, a repeated Ctrl/Cmd+A deselects all options. Off by default (Ctrl+A only selects).

selectAllinputCopy link to selectAllboolean

Whether to render the "select all" master checkbox above the options. Multiple selection only.

The row acts on the options the user can actually toggle — rendered, enabled and selectable. Since search filtering removes options from the DOM, "select all" under an active query selects only the matches. Enabling it also makes Ctrl/Cmd + A a two-way toggle, so the shortcut and the checkbox never disagree (selectAllToggle is implied).

selectAllHandlerinputCopy link to selectAllHandler((event: KeyboardEvent, select: KbqSelect) => void) | undefined

Function for handling the Ctrl + A (select all) keyboard combination. By default, the internal handler selects all options. It is called with the keyboard event that triggered it and a reference to this select component.

panelWidthinputCopy link to panelWidthKbqPanelWidth

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 or an empty string, the panel will grow to match the longest option's text. Any other value is used as an exact width, and panelMinWidth is not applied.

panelMinWidthinputCopy link to panelMinWidthKbqPanelMinWidth

Minimum width of the panel in pixels. If minWidth is larger than window width, it will be ignored.

panelMaxWidthinputCopy link to panelMaxWidthKbqPanelMaxWidth

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-panel-size-width-max token applies.

panelMaxHeightinputCopy link to panelMaxHeightKbqPanelMaxHeight

Maximum height of the panel's scrollable option list, in pixels. Applied as the --kbq-select-panel-size-max-height custom property on the panel, so it also drives the pinned height of a cdk-virtual-scroll-viewport — with virtual scroll the value is an exact height, not a cap.

The search field and the footer sit outside the scrollable area and add to the panel's total height. When null, the token default (256px) applies.

valuemodelCopy link to valueany

Value of the select control. Can be a single value or array of values for multiple selection. Follows [value], the form control and the user's selection. A value set in code selects its options on the next change detection, without emitting valueChange.

idinputCopy link to idstring | undefined

Unique identifier for the select component. Auto-generates an ID if not provided.

disabledinputCopy link to disabledboolean

Whether the select is disabled. When disabled, the select cannot be opened and its value cannot be changed. Also set by the bound form control.

beforeOpenedoutputCopy link to beforeOpenedvoid

Event emitted before the select panel starts opening.

selectionChangeoutputCopy link to selectionChangeKbqSelectChange

Event emitted when the selected value has been changed by the user.

onSelectAlloutputCopy link to onSelectAllKbqSelectAllEvent<KbqOption, KbqSelect>

Event emitted when all options are selected or deselected via the Ctrl/Cmd + A shortcut. Not emitted when a custom selectAllHandler is supplied — the handler owns the behaviour then.

scrolledToBottomoutputCopy link to scrolledToBottomvoid

Emits when the options panel is scrolled to (or within scrolledToBottomOffset of) the bottom.

timezoneLocaleConfigurationCopy link to timezoneLocaleConfigurationSignal<KbqTimezoneLocaleConfiguration>

Strings currently rendered by the select.

errorStateCopy link to errorStateSignal<boolean>

Whether the component is in an error state.

controlTypeCopy link to controlTypestring

A name for this control that can be used by kbq-form-field.

isNativeLabelSupportedCopy link to isNativeLabelSupportedfalse

A kbq-select is not a native labelable element, so the form-field's <label for> cannot associate with it. The select is named through aria-labelledby instead.

hiddenItemsCopy link to hiddenItemsSignal<number>

Number of the selected items that do not fit into the trigger.

triggerFontSizeCopy link to triggerFontSizenumber

The cached font-size of the trigger element in pixels.

selectionModelCopy link to selectionModelSelectionModel<KbqOptionBase>

Deals with the selection logic. Manages selected options and their states.

previousSelectionModelSelectedCopy link to previousSelectionModelSelectedKbqOptionBase[]

Previously selected options before the current selection was made.

keyManagerCopy link to keyManagerActiveDescendantKeyManager<KbqOption>

Manages keyboard events for options in the panel.

transformOriginCopy link to transformOriginstring

The value of the select panel's transform-origin property.

panelDoneAnimatingStreamCopy link to panelDoneAnimatingStreamSubject<string>

Emits once the panel has rendered ('showing') or has been removed ('void').

scrollStrategyCopy link to scrollStrategyScrollStrategy

Strategy that will be used to handle scrolling while the select panel is open.

positionsCopy link to positionsConnectedPosition[]

Opens the panel below the trigger, falling back to above it when it does not fit.

A third position is appended at runtime by updatePanelAnchor: a multiline trigger that has grown taller than the panel gets it anchored to its first row and drawn over the rest of it.

triggerCopy link to triggerSignal<ElementRef<any> | undefined>

Trigger - is a clickable field to open select dropdown panel

panelCopy link to panelSignal<ElementRef<any> | undefined>

Reference to the overlay panel element.

optionsContainerCopy link to optionsContainerSignal<ElementRef<any>>

Reference to the container element that holds the options.

selectAllOptionCopy link to selectAllOptionSignal<KbqOption | undefined>

Reference to the built-in "select all" row, rendered only while selectAll is on.

cdkVirtualForOfCopy link to cdkVirtualForOfSignal<CdkVirtualForOf<any> | undefined>

Reference to the CDK virtual scroll directive for virtual scrolling support.

virtualScrollViewportCopy link to virtualScrollViewportSignal<CdkVirtualScrollViewport | undefined>

Reference to the CDK virtual scroll viewport for tracking scroll position in virtual mode.

tagsCopy link to tagsQueryList<KbqTag>

Query list of tags displayed in multiple selection mode.

customMatcherCopy link to customMatcherSignal<KbqSelectMatcher | undefined>

User-supplied matcher component for custom value matching logic.

customTagTemplateRefCopy link to customTagTemplateRefSignal<TemplateRef<any> | undefined>

Custom template reference for rendering tag content.

optionsCopy link to optionsQueryList<KbqOption>

All of the defined select options.

optionGroupsCopy link to optionGroupsSignal<readonly KbqOptgroup[]>

All of the defined groups of options.

searchEmptyCopy link to searchEmptySignal<KbqSelectSearchEmptyResult | undefined>

Reference to the optional empty search result component.

optionSelectionChangesCopy link to optionSelectionChangesObservable<KbqOptionSelectionChange>

Combined stream of all of the child options' change events.

openedChangeCopy link to openedChangeEventEmitter<boolean>

Event emitted when the select panel has been toggled. Emits true when opened, false when closed. Also serves as the openedChange member of the KbqSiblingPopup contract — a tooltip sharing this element's host reacts to it, so its emission timing (gated on panelDoneAnimatingStream, see ngOnInit) matters beyond this output's original consumers.

openedStreamCopy link to openedStreamObservable<void>

Event emitted when the select has been opened.

closedStreamCopy link to closedStreamObservable<void>

Event emitted when the select has been closed.

focusedCopy link to focusedSignal<boolean>

Whether the select is focused.

panelOpenCopy link to panelOpenboolean

Whether the select panel is currently open.

isAttachedCopy link to isAttachedboolean

Whether the overlay panel is currently on screen. Part of the KbqSiblingPopup contract.

withVirtualScrollCopy link to withVirtualScrollboolean

Whether virtual scrolling is enabled for the options panel.

isEmptySearchResultCopy link to isEmptySearchResultboolean

Whether the search returned no results.

allOptionsSelectedCopy link to allOptionsSelectedboolean

Whether every option "select all" can act on is selected.

selectAllStateCopy link to selectAllStateKbqPseudoCheckboxState

State of the "select all" master checkbox.

selectedCopy link to selectedKbqOptionBase | KbqOptionBase[]

Returns the currently selected option(s). Single value or array for multiple selection.

triggerValueCopy link to triggerValuestring

Returns the display value for the trigger element.

triggerValuesCopy link to triggerValuesKbqOptionBase[]

Returns all selected options in display order.

emptyCopy link to emptySignal<boolean>

Whether no option is currently selected.

noOptionsCopy link to noOptionsboolean

Whether there are no options available.

firstSelectedCopy link to firstSelectedKbqOptionBase | null

Returns the first selected option that is not disabled.

firstFilteredCopy link to firstFilteredboolean

Whether the first selected option is filtered (not visible in the list).

multiSelectionCopy link to multiSelectionboolean

Whether multiple choice is enabled. True if multiple or multiline mode is active.

calculateHiddenItemsCopy link to calculateHiddenItems() => void

Calculates the number of hidden items in multiple selection mode and updates hiddenItems.

updateErrorState()Copy link to updateErrorState()void

Updates the error state based on the error state matcher.

resetSearch()Copy link to resetSearch()void

Resets the search component if present.

toggle()Copy link to toggle()void

Toggles the overlay panel open or closed.

open()Copy link to open()void

Triggers the opening of the panel component. If the component is disabled or the panel is already open, the call is ignored. Otherwise, the (beforeOpened) event is emitted. When no options are available, the panel is opened after a short delay; if options exist, it opens immediately.

openPanel()Copy link to openPanel()void

Internal method to open the panel. Handles overlay positioning and sizing. Sets up the overlay dimensions based on trigger size and configured options.

close()Copy link to close()void

Closes the overlay panel.

isRtl()Copy link to isRtl()boolean

Checks if the current direction is RTL (right-to-left).

Returns
boolean

True if RTL mode is active, false otherwise.

handleKeydown()Copy link to handleKeydown()void

Handles all keyboard events for the select. Delegates to appropriate handler based on panel state.

Parameters
eventKeyboardEvent

The keyboard event to handle.

onFocus()Copy link to onFocus()void

Handles focus event on the select element.

onBlur()Copy link to onBlur()void

Calls the touched callback only if the panel is closed. Otherwise, the trigger will "blur" to the panel when it opens, causing a false positive.

onAttached()Copy link to onAttached()void

Callback that is invoked when the overlay panel has been attached. Sets up position change subscription and closing actions.

getPanelTheme()Copy link to getPanelTheme()string

Returns the theme to be used on the panel based on parent form field color.

focus()Copy link to focus()void

Focuses the select element.

onRemoveMatcherItem()Copy link to onRemoveMatcherItem()void

Handles removal of a matched item in the trigger.

Parameters
optionKbqOptionBase

The option to remove from selection.

$eventEvent

The mouse or keyboard event that triggered the removal.

getItemHeight()Copy link to getItemHeight()number

Gets the height of a single option item.

Returns
number

The height in pixels of the first option, or 0 if no options exist.

handleClick()Copy link to handleClick()void

Handles click events on the select. Closes the panel if click is inside the footer.

Parameters
$eventMouseEvent

The mouse event to handle.

KbqTimezoneOptionTooltip

directiveCopy link to KbqTimezoneOptionTooltip
@Directive({ selector: 'kbq-timezone-option' })
class KbqTimezoneOptionTooltip extends KbqTooltipTrigger {
    readonly ignoreTooltipPointerEvents = input<boolean>(true);
    readonly forDisabledComponent = input<Record<'disabledSignal', WritableSignal<boolean>>>();
    readonly singleInstance = input<boolean>(
        inject(KBQ_TOOLTIP_SINGLE_INSTANCE_DEFAULT),
        { alias: 'kbqTooltipSingleInstance' }
    );
    hideWithTimeout = input<boolean | undefined>();
    tooltipVisible: boolean;
    tooltipPlacement: KbqPopUpPlacementValues;
    relativeToPointer: boolean;
    relativeToCaret: boolean;
    relativeToCaretVertical: KbqCaretVerticalAnchor;
    tooltipPlacementPriority: string | string[] | null;
    content: string | TemplateRef<unknown>;
    disabled: boolean;
    enterDelay: number;
    leaveDelay: number;
    trigger: string;
    customClass: string;
    context: unknown;
    color: KbqComponentColors | string;
    arrow: boolean;
    arrowCentered: boolean;
    offset: number | null;
    readonly placementChange: EventEmitter<KbqPopUpPlacementValues>;
    readonly visibleChange: EventEmitter<boolean>;
    modifier: KbqEnumValues<TooltipModifier>;
    header: string | TemplateRef<unknown>;
    isOpen: boolean;
    get isAttached(): boolean;
    get openedChange(): Observable<boolean>;
    handleElementEnter(): void;
    handleElementLeave(): void;
    show(delay?: number): void;
    hide(delay?: number): void;
    showForMouseEvent(event: MouseEvent): void;
    showForElement(element: HTMLElement): void;
    updateOrigin(origin: KbqOverlayOrigin | null): void;
}
ignoreTooltipPointerEventsinputCopy link to ignoreTooltipPointerEventsboolean

Overrides the tooltip's hoverable default. The overflow hint floats over the neighbouring options of a scrolling list, so a pointer-capturing pane would swallow the click that selects them.

forDisabledComponentinputCopy link to forDisabledComponentRecord<'disabledSignal', WritableSignal<boolean>>

Input for controlling the disabled state of a component.

The input expects a component containing disabledSignal property, which is a writable signal emitting boolean values.

kbqTooltipSingleInstanceinputCopy link to kbqTooltipSingleInstanceboolean

Whether the tooltip takes part in the "only one tooltip is visible at a time" group: showing it hides the previously visible tooltip, and it is hidden when another tooltip is shown.

Defaults to true; the default can be changed application-wide with the KBQ_TOOLTIP_SINGLE_INSTANCE_DEFAULT token.

Tooltips without an interactive kbqTrigger (manual, none, …) never take part in the group, regardless of this input — they are shown imperatively and are expected to stay pinned.

hideWithTimeoutinputCopy link to hideWithTimeoutboolean | undefined

Changes hiding behavior. By default, tooltip is hidden on mouseleave from trigger. Setting hideWithTimeout to true will delay tooltip hiding and will not hide when the mouse moves from trigger to tooltip.

tooltipVisibleCopy link to tooltipVisibleboolean

Input (kbqVisible) that programmatically shows or hides the tooltip; reflects the current visible state.

tooltipPlacementCopy link to tooltipPlacementKbqPopUpPlacementValues

Input (kbqPlacement) that sets the tooltip placement relative to its trigger; reflects the current placement.

relativeToPointerCopy link to relativeToPointerboolean

Positions the tooltip relative to the mouse cursor. Only available for top and bottom kbqPlacement. Does not work with kbqPlacementPriority.

relativeToCaretCopy link to relativeToCaretboolean

Positions the tooltip relative to the text caret of the field it is attached to, following it while the user types, moves the caret and scrolls the field. Anchors to the selection whenever there is one.

Every placement is available, unlike with kbqRelativeToPointer: the caret is anchored as a rectangle, so the usual fallback placements keep the tooltip on screen. Wins when both inputs are enabled.

The field is the host element itself when it is editable, otherwise the first editable it wraps.

relativeToCaretVerticalCopy link to relativeToCaretVerticalKbqCaretVerticalAnchor

What the tooltip is vertically anchored to while kbqRelativeToCaret is enabled.

tooltipPlacementPriorityCopy link to tooltipPlacementPrioritystring | string[] | null

Input (kbqPlacementPriority) that sets the ordered fallback placements; reflects the current placementPriority.

contentCopy link to contentstring | TemplateRef<unknown>

Input (kbqTooltip) with the tooltip content — a string or a template. Updating it refreshes an open tooltip.

disabledCopy link to disabledboolean

Input (kbqTooltipDisabled) controlling whether the tooltip is disabled; setting it to true hides it. undefined leaves the decision to the trigger, like an unset input.

Reads back the effective state, which for triggers that derive one of their own (see derivedDisabledWins) is not necessarily the value that was written.

enterDelayCopy link to enterDelaynumber

Input (kbqEnterDelay) — delay in milliseconds before the tooltip is shown. Defaults to 400.

leaveDelayCopy link to leaveDelaynumber

Input (kbqLeaveDelay) — delay in milliseconds before the tooltip is hidden. Defaults to 0.

triggerCopy link to triggerstring

Input (kbqTrigger) with the comma-separated trigger events. An empty value resets to hover + focus and rebinds listeners.

customClassCopy link to customClassstring

Input (kbqTooltipClass) with an extra CSS class applied to the tooltip; updating it refreshes the class map.

contextCopy link to contextunknown

Input (kbqTooltipContext) with the context object passed to a template tooltip; updating it refreshes the open tooltip.

colorCopy link to colorKbqComponentColors | string

Input (kbqTooltipColor) with the tooltip color theme. Defaults to KbqComponentColors.Contrast.

arrowCopy link to arrowboolean

Input (kbqTooltipArrow) — whether to render the tooltip's arrow/pointer. Defaults to false.

arrowCenteredCopy link to arrowCenteredboolean

Input (kbqTooltipArrowCentered) — centers the arrow on the trigger while preserving the panel placement. Requires a visible arrow. Defaults to false.

offsetCopy link to offsetnumber | null

Input (kbqTooltipOffset) — distance in pixels between the tooltip and its trigger. null keeps the gap of the stylesheet. Defaults to the offset of KBQ_TOOLTIP_DEFAULT_OPTIONS, when a provider in scope set one. Inside a provider scope such as the navbar's, null/undefined restores that inherited default.

placementChangeCopy link to placementChangeEventEmitter<KbqPopUpPlacementValues>

Output (kbqPlacementChange) that emits the new placement whenever the tooltip repositions.

visibleChangeCopy link to visibleChangeEventEmitter<boolean>

Output (kbqVisibleChange) that emits when the tooltip's visibility changes.

modifierCopy link to modifierKbqEnumValues<TooltipModifier>

Visual variant of the tooltip. Accepts 'default' | 'warning' | 'extended'. Replaces the removed KbqWarningTooltipTrigger and KbqExtendedTooltipTrigger subclasses — to render a warning tooltip use kbqTooltipModifier="warning", and kbqTooltipModifier="extended" for the extended variant (combine with kbqTooltipHeader).

headerCopy link to headerstring | TemplateRef<unknown>

Header text or template, rendered above the tooltip content. Only meaningful with kbqTooltipModifier="extended". Replaces the removed KbqExtendedTooltipTrigger.header.

isOpenCopy link to isOpenboolean

Whether the pop-up overlay is currently open.

isAttachedCopy link to isAttachedboolean

Whether the pop-up overlay is currently attached.

Unlike isOpen, which follows the visibility of the pop-up component and therefore lags a task behind show()/hide(), this flips synchronously — it is the window during which the overlay (and its backdrop) is present in the DOM. Part of the KbqSiblingPopup contract.

openedChangeCopy link to openedChangeObservable<boolean>

Emits true when the pop-up opens and false when it closes. Part of the KbqSiblingPopup contract.

show()Copy link to show()void

Shows the tooltip after delay ms. Suppresses showing while a pop-up on the same element holds the anchor or on a focus trigger that did not originate from the keyboard, and applies cursor-relative positioning when relativeToPointer is enabled.

hide()Copy link to hide()void

Hides the tooltip after delay ms and, when the user has genuinely left the host, un-mutes a tooltip that a pop-up on the same element had muted.

mouseleave and blur are the release signals because the base class binds hide to both regardless of whether the tooltip is currently visible. A pop-up that is still attached does not count: its backdrop steals the hover from the trigger while the pointer stands still, and that mouseleave must not be mistaken for the user leaving.

showForMouseEvent()Copy link to showForMouseEvent()void

Shows the tooltip next to the cursor position of the given mouse event, anchoring it to the event's currentTarget instead of the directive's own host element.

Use it when the trigger cannot be declared in the template — for instance for a tooltip shared by the cells of a virtualized table. The directive still has to be created in an injection context.

showForElement()Copy link to showForElement()void

Shows the tooltip anchored to the given element instead of the directive's own host element.

Use it when the trigger cannot be declared in the template. The directive still has to be created in an injection context:

const tooltip = runInInjectionContext(injector, () => new KbqTooltipTrigger());
tooltip.showForElement(element);

Does nothing while the tooltip is disabled or has no content — there is no overlay to anchor then.

updateOrigin()Copy link to updateOrigin()void

Positions the pop-up against origin — an element, or a rectangle in viewport coordinates such as the one kbqCreateCaretOrigin keeps on the caret — instead of the host element; null restores the host element. An open pop-up moves to the new origin at once.

This moves the position origin only. setExternalNativeElement moves the host itself, and with it the trigger's event listeners, its focus target and the scroll containers the pop-up follows.

KbqTimezoneSelectTrigger

directiveCopy link to KbqTimezoneSelectTrigger
@Directive({ selector: 'kbq-timezone-select-trigger' })
class KbqTimezoneSelectTrigger {}

CitiesByFilterPipe

pipeCopy link to CitiesByFilterPipe

Narrows a ', '-joined city list to the entries matching the search pattern(s).

@Pipe({ name: 'citiesByFilter' })
class CitiesByFilterPipe implements PipeTransform {
    transform(
        value: string,
        searchPattern?: string | readonly string[]
    ): string;
}

UtcOffsetPipe

pipeCopy link to UtcOffsetPipe

Splits an HH:MM:SS offset into the UTC prefix and the signed offset, for a two-column layout.

@Pipe({ name: 'utcOffset' })
class UtcOffsetPipe implements PipeTransform {
    transform(value: string): { [UTC: string]: string };
}

collapseOtherCountries

functionCopy link to collapseOtherCountries

Merges every group other than countryCode into one bucket labelled otherCountriesLabel, placed after the country it promotes. The bucket spans countries, so its countryCode is null.

This is the shape a world-wide list is usually rendered in: the user's own country first, everything else collapsed behind one label.

function collapseOtherCountries(
    groups: readonly KbqTimezoneGroup[],
    countryCode: string | null | undefined,
    otherCountriesLabel: string
): KbqTimezoneGroup[];

filterCitiesBySearchString

functionCopy link to filterCitiesBySearchString

Filtering timezone cities by search string. Accepts a single pattern or several (matching a city if it satisfies any one of them) — patterns that look like a bare UTC offset (e.g. +3) are ignored here, since they describe the zone rather than a city name.

function filterCitiesBySearchString(
    cities: string,
    searchPattern?: string | readonly string[]
): string;

getZonesGroupedByCountry

functionCopy link to getZonesGroupedByCountry

Groups zones by KbqTimezoneZone.countryCode — one group per country, ordered by country name, with the zones inside each group ordered by timezonesSortComparator.

Pure: the same input produces the same groups on any machine, which is what makes it safe to run on the server and again in the browser. To put the user's own country first, pass the result through promoteCountry or collapseOtherCountries, and read the country itself with kbqResolveHostCountry.

function getZonesGroupedByCountry(
    data: readonly KbqTimezoneZone[]
): KbqTimezoneGroup[];

kbqResolveHostCountry

functionCopy link to kbqResolveHostCountry

Country code of the zone whose id is the time zone of the machine this runs on, or undefined when data has no row for it.

Reads Intl, so the answer is the host's: on the server that is the server's zone rather than the user's, and the value it produces there will not match the one the browser produces on hydration. It is kept apart from the grouping for exactly that reason — call it where host-dependence is acceptable and pass the result on.

function kbqResolveHostCountry(
    data: readonly KbqTimezoneZone[]
): string | undefined;

offset

functionCopy link to offset

Formats an HH:MM:SS offset as a signed ±HH:MM, with U+2212 for the minus sign.

function offset(value: string): string;

offsetFormatter

functionCopy link to offsetFormatter

Formats an HH:MM:SS offset the way the option renders it: UTC+03:00.

function offsetFormatter(value: string): string;

offsetFormatterAsObject

functionCopy link to offsetFormatterAsObject

The same as offsetFormatter, split into the UTC prefix and the offset for two-column layouts.

function offsetFormatterAsObject(
    value: string
): { [UTC: string]: string };

parseOffset

functionCopy link to parseOffset

Convert string timezone offset (formatted offset) to number (minutes)

function parseOffset(offset: string): number;

promoteCountry

functionCopy link to promoteCountry

Moves the group of countryCode to the front, leaving the rest in their order. Returns a new array; a country the groups do not contain, or no country at all, leaves the order untouched.

function promoteCountry(
    groups: readonly KbqTimezoneGroup[],
    countryCode: string | null | undefined
): KbqTimezoneGroup[];

resolveZoneOffset

functionCopy link to resolveZoneOffset

Offset zone is on at timestamp, written the way KbqTimezoneZone.offset is, or an empty string when the zone identifies neither a fixed offset nor a time zone Intl knows.

A zone that carries an explicit offset keeps that string verbatim. A zone without one has the offset resolved from its IANA id, which is what makes a DST zone read UTC+01:00 in January and UTC+02:00 in July instead of whichever of the two was written into the data.

function resolveZoneOffset(
    zone: KbqTimezoneZone,
    timestamp?: number
): string;

timezonesSortComparator

functionCopy link to timezonesSortComparator

Comparator for timezone sorting. Orders by the offset each zone is on right now, then by city name — the country cannot discriminate here, since every zone reaching this inside a group already shares one.

A zone whose offset resolves to nothing sorts after every zone that has one, rather than as UTC.

function timezonesSortComparator(
    first: KbqTimezoneZone,
    second: KbqTimezoneZone
): number;

KbqTimezoneGroup

interfaceCopy link to KbqTimezoneGroup

A group of zones rendered under one label.

interface KbqTimezoneGroup {
    countryName: string;
    countryCode: string | null;
    zones: KbqTimezoneZone[];
}
countryNameCopy link to countryNamestring

Label of the group: a country name, or the "other countries" label of an aggregate bucket.

countryCodeCopy link to countryCodestring | null

Country the group stands for, or null for an aggregate bucket that spans several countries (the one collapseOtherCountries produces).

zonesCopy link to zonesKbqTimezoneZone[]

Zones of the group, sorted by offset and then by city.

KbqTimezonesByCountry

interfaceCopy link to KbqTimezonesByCountry

Zones bucketed by country code, the intermediate shape of the grouping utilities.

interface KbqTimezonesByCountry {
    [countryCode: string]: KbqTimezoneZone[];
}

KbqTimezoneZone

interfaceCopy link to KbqTimezoneZone

One row of the timezone list: a zone, the city it is named after and the country it belongs to.

interface KbqTimezoneZone {
    id: string;
    offset?: string;
    city: string;
    countryCode: string;
    countryName: string;
    cities: string;
}
idCopy link to idstring

IANA time zone name, e.g. Europe/Berlin. Used as the form value and to resolve the offset.

offsetoptionalCopy link to offsetstring

Fixed offset from UTC, written as HH:MM:SS with an optional leading - (03:00:00, -02:00:00).

Optional, and omitting it is the safer choice: the offset is then resolved from id at render time, so a zone that observes DST is labelled correctly on both sides of the change. A string supplied here is rendered verbatim and never recomputed — the consumer owns keeping it current.

cityCopy link to citystring

Name of the city the zone is displayed under.

countryCodeCopy link to countryCodestring

ISO 3166-1 alpha-2 code of the country the zone belongs to. Matched case-insensitively.

countryNameCopy link to countryNamestring

Display name of the country the zone belongs to.

citiesCopy link to citiesstring

Other cities in the zone, joined with ', '.

kbqTimezoneLocaleConfigurationProvider

constCopy link to kbqTimezoneLocaleConfigurationProvider

Utility provider for KBQ_TIMEZONE_LOCALE_CONFIGURATION. Only the strings you pass are overridden; the rest keep following the active locale.

const kbqTimezoneLocaleConfigurationProvider: (
    configuration: KbqDeepPartial<KbqTimezoneLocaleConfiguration>
) => Provider;
Suggestions for improvement
If you found a mistake or want to improve the article, create an issue on GitHub.