# API of `@koobiq/components/timezone`

Documented on [Timezone](https://koobiq.io/en/components/timezone.md). NgModule: `KbqTimezoneModule`.

## Components

### KbqTimezoneOption (component)

```ts
@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;
}
```

- `[foldDiacritics]`: `boolean` — Whether `highlightText` was matched with diacritic folding (e.g. via `createSearchPredicate`) — see `kbqHighlightBackground`.
- `[timezone]`: `KbqTimezoneZone` — The time zone the option stands for.
- `[value]`: `any` — The id of the time zone, unless no time zone is bound.
- `[viewValue]`: `string | undefined` — The whole zone as one line: the offset, the city and every city the zone covers.
- `[showCheckbox]`: `boolean | undefined` — Whether the option renders a checkbox. Follows the multiple selection mode of the parent until bound.
- `[disabled]`: `boolean` — Whether the option is disabled, through its own input or its group.
- `tooltipViewValue`: `string` — 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.
- `textElement`: `ElementRef<HTMLElement> | undefined` — Element holding the text of the option, measured by `kbq-title`.
- `onSelectionChange`: `EventEmitter<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.
- `stateChanges`: `Subject<void>` — Emits when the state of the option changes and any parents have to be notified.
- `multiple`: `boolean` — Whether the wrapping component is in multiple selection mode.
- `active`: `boolean` — 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()`: `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()`: `void` — Moves keyboard focus to this option and reveals it — see `kbqFocusAndReveal`.
- `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()`: `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()`: `void` — Ensures the option is selected when activated from the keyboard.
- `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 (component)

```ts
@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;
}
```

- `[hiddenItemsText]`: `string` — 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.
- `[hiddenItemsTextFormatter]`: `(hiddenItemsText: string, hiddenItems: number) => string` — Formats the hidden items counter.
- `[aria-label]`: `string | 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.
- `[showPreselectedValues]`: `boolean` — Determines whether preselected values are displayed.
- `[triggerValuesLimit]`: `number` — 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.
- `[panelClass]`: `string | string[] | Set<string> | Record<string, boolean>` — Classes to be passed to the select panel. Supports the same syntax as the `[class]` binding.
- `[backdropClass]`: `string` — Classes to be passed to the overlay backdrop.
- `[errorStateMatcher]`: `ErrorStateMatcher` — Object used to control when error messages are shown.
- `[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.
- `[multiline]`: `boolean` — Whether to use a multiline matcher or not. Default is false.
  When true, allows multiple lines of text in the selected value display.
- `[multilineOptions]`: `boolean` — 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`.
- `[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`.
- `[scrolledToBottomOffset]`: `number` — 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.
- `[hasBackdrop]`: `boolean` — Whether the overlay should have a backdrop.
  When true, clicking the backdrop will close the select.
- `[placeholder]`: `string` — Placeholder text to be shown when no value is selected.
  Displayed in the trigger when the select is closed and no value is selected.
- `[required]`: `boolean` — Whether the select is required. Affects validation and display of placeholder.
- `[multiple]`: `boolean` — Whether multiple options can be selected.
  Note: This cannot be changed dynamically after initialization.
- `[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.
- `[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 `@Input`s.

  Defaults to `new KbqVirtualOption(value, this.disabled())`, which is correct
  for primitive values where `value` itself is the display label.
- `[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.
- `[selectAllToggle]`: `boolean` — When `true`, a repeated Ctrl/Cmd+A deselects all options. Off by default (Ctrl+A only selects).
- `[selectAll]`: `boolean` — 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).
- `[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.
- `[panelWidth]`: `KbqPanelWidth` — 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.
- `[panelMinWidth]`: `KbqPanelMinWidth` — Minimum width of the panel in pixels.
  If minWidth is larger than window width, it will be ignored.
- `[panelMaxWidth]`: `KbqPanelMaxWidth` — 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.
- `[panelMaxHeight]`: `KbqPanelMaxHeight` — 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.
- `[(value)]`: `any` — 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`.
- `[id]`: `string | undefined` — Unique identifier for the select component.
  Auto-generates an ID if not provided.
- `[disabled]`: `boolean` — 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.
- `(beforeOpened)`: `void` — Event emitted before the select panel starts opening.
- `(selectionChange)`: `KbqSelectChange` — Event emitted when the selected value has been changed by the user.
- `(onSelectAll)`: `KbqSelectAllEvent<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.
- `(scrolledToBottom)`: `void` — Emits when the options panel is scrolled to (or within `scrolledToBottomOffset` of) the bottom.
- `timezoneLocaleConfiguration`: `Signal<KbqTimezoneLocaleConfiguration>` — Strings currently rendered by the select.
- `errorState`: `Signal<boolean>` — Whether the component is in an error state.
- `controlType`: `string` — A name for this control that can be used by `kbq-form-field`.
- `isNativeLabelSupported`: `false` — 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.
- `hiddenItems`: `Signal<number>` — Number of the selected items that do not fit into the trigger.
- `triggerFontSize`: `number` — The cached font-size of the trigger element in pixels.
- `selectionModel`: `SelectionModel<KbqOptionBase>` — Deals with the selection logic. Manages selected options and their states.
- `previousSelectionModelSelected`: `KbqOptionBase[]` — Previously selected options before the current selection was made.
- `keyManager`: `ActiveDescendantKeyManager<KbqOption>` — Manages keyboard events for options in the panel.
- `transformOrigin`: `string` — The value of the select panel's transform-origin property.
- `panelDoneAnimatingStream`: `Subject<string>` — Emits once the panel has rendered (`'showing'`) or has been removed (`'void'`).
- `scrollStrategy`: `ScrollStrategy` — Strategy that will be used to handle scrolling while the select panel is open.
- `positions`: `ConnectedPosition[]` — 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.
- `trigger`: `Signal<ElementRef<any> | undefined>` — Trigger - is a clickable field to open select dropdown panel
- `panel`: `Signal<ElementRef<any> | undefined>` — Reference to the overlay panel element.
- `optionsContainer`: `Signal<ElementRef<any>>` — Reference to the container element that holds the options.
- `selectAllOption`: `Signal<KbqOption | undefined>` — Reference to the built-in "select all" row, rendered only while `selectAll` is on.
- `footer`: `Signal<ElementRef<any> | undefined>` — Reference to the optional footer element in the panel.
- `cdkVirtualForOf`: `Signal<CdkVirtualForOf<any> | undefined>` — Reference to the CDK virtual scroll directive for virtual scrolling support.
- `virtualScrollViewport`: `Signal<CdkVirtualScrollViewport | undefined>` — Reference to the CDK virtual scroll viewport for tracking scroll position in virtual mode.
- `tags`: `QueryList<KbqTag>` — Query list of tags displayed in multiple selection mode.
- `customMatcher`: `Signal<KbqSelectMatcher | undefined>` — User-supplied matcher component for custom value matching logic.
- `customTagTemplateRef`: `Signal<TemplateRef<any> | undefined>` — Custom template reference for rendering tag content.
- `options`: `QueryList<KbqOption>` — All of the defined select options.
- `optionGroups`: `Signal<readonly KbqOptgroup[]>` — All of the defined groups of options.
- `search`: `Signal<KbqSelectSearch | undefined>` — Reference to the optional search component.
- `searchEmpty`: `Signal<KbqSelectSearchEmptyResult | undefined>` — Reference to the optional empty search result component.
- `optionSelectionChanges`: `Observable<KbqOptionSelectionChange>` — Combined stream of all of the child options' change events.
- `openedChange`: `EventEmitter<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.
- `openedStream`: `Observable<void>` — Event emitted when the select has been opened.
- `closedStream`: `Observable<void>` — Event emitted when the select has been closed.
- `focused`: `Signal<boolean>` — Whether the select is focused.
- `panelOpen`: `boolean` — Whether the select panel is currently open.
- `isAttached`: `boolean` — Whether the overlay panel is currently on screen. Part of the `KbqSiblingPopup` contract.
- `withVirtualScroll`: `boolean` — Whether virtual scrolling is enabled for the options panel.
- `isEmptySearchResult`: `boolean` — Whether the search returned no results.
- `allOptionsSelected`: `boolean` — Whether every option "select all" can act on is selected.
- `selectAllState`: `KbqPseudoCheckboxState` — State of the "select all" master checkbox.
- `selected`: `KbqOptionBase | KbqOptionBase[]` — Returns the currently selected option(s). Single value or array for multiple selection.
- `triggerValue`: `string` — Returns the display value for the trigger element.
- `triggerValues`: `KbqOptionBase[]` — Returns all selected options in display order.
- `empty`: `Signal<boolean>` — Whether no option is currently selected.
- `noOptions`: `boolean` — Whether there are no options available.
- `firstSelected`: `KbqOptionBase | null` — Returns the first selected option that is not disabled.
- `firstFiltered`: `boolean` — Whether the first selected option is filtered (not visible in the list).
- `multiSelection`: `boolean` — Whether multiple choice is enabled. True if multiple or multiline mode is active.
- `calculateHiddenItems`: `() => void` — Calculates the number of hidden items in multiple selection mode and updates `hiddenItems`.
- `updateErrorState()`: `void` — Updates the error state based on the error state matcher.
- `resetSearch()`: `void` — Resets the search component if present.
- `toggle()`: `void` — Toggles the overlay panel open or closed.
- `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()`: `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()`: `void` — Closes the overlay panel.
- `isRtl()`: `boolean` — Checks if the current direction is RTL (right-to-left).
  - returns `boolean` — True if RTL mode is active, false otherwise.
- `handleKeydown()`: `void` — Handles all keyboard events for the select.
  Delegates to appropriate handler based on panel state.
  - `event`: `KeyboardEvent` — The keyboard event to handle.
- `onFocus()`: `void` — Handles focus event on the select element.
- `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()`: `void` — Callback that is invoked when the overlay panel has been attached.
  Sets up position change subscription and closing actions.
- `getPanelTheme()`: `string` — Returns the theme to be used on the panel based on parent form field color.
- `focus()`: `void` — Focuses the select element.
- `onRemoveMatcherItem()`: `void` — Handles removal of a matched item in the trigger.
  - `option`: `KbqOptionBase` — The option to remove from selection.
  - `$event`: `Event` — The mouse or keyboard event that triggered the removal.
- `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()`: `void` — Handles click events on the select.
  Closes the panel if click is inside the footer.
  - `$event`: `MouseEvent` — The mouse event to handle.

## Directives

### KbqTimezoneOptionTooltip (directive)

```ts
@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;
}
```

- `[ignoreTooltipPointerEvents]`: `boolean` — 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.
- `[forDisabledComponent]`: `Record<'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.
- `[kbqTooltipSingleInstance]`: `boolean` — 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.
- `[hideWithTimeout]`: `boolean | 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.
- `tooltipVisible`: `boolean` — Input (`kbqVisible`) that programmatically shows or hides the tooltip; reflects the current `visible` state.
- `tooltipPlacement`: `KbqPopUpPlacementValues` — Input (`kbqPlacement`) that sets the tooltip placement relative to its trigger; reflects the current `placement`.
- `relativeToPointer`: `boolean` — Positions the tooltip relative to the mouse cursor. Only available for top and bottom kbqPlacement.
  Does not work with kbqPlacementPriority.
- `relativeToCaret`: `boolean` — 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.
- `relativeToCaretVertical`: `KbqCaretVerticalAnchor` — What the tooltip is vertically anchored to while `kbqRelativeToCaret` is enabled.
- `tooltipPlacementPriority`: `string | string[] | null` — Input (`kbqPlacementPriority`) that sets the ordered fallback placements; reflects the current `placementPriority`.
- `content`: `string | TemplateRef<unknown>` — Input (`kbqTooltip`) with the tooltip content — a string or a template. Updating it refreshes an open tooltip.
- `disabled`: `boolean` — 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.
- `enterDelay`: `number` — Input (`kbqEnterDelay`) — delay in milliseconds before the tooltip is shown. Defaults to `400`.
- `leaveDelay`: `number` — Input (`kbqLeaveDelay`) — delay in milliseconds before the tooltip is hidden. Defaults to `0`.
- `trigger`: `string` — Input (`kbqTrigger`) with the comma-separated trigger events. An empty value resets to hover + focus and rebinds listeners.
- `customClass`: `string` — Input (`kbqTooltipClass`) with an extra CSS class applied to the tooltip; updating it refreshes the class map.
- `context`: `unknown` — Input (`kbqTooltipContext`) with the context object passed to a template tooltip; updating it refreshes the open tooltip.
- `color`: `KbqComponentColors | string` — Input (`kbqTooltipColor`) with the tooltip color theme. Defaults to `KbqComponentColors.Contrast`.
- `arrow`: `boolean` — Input (`kbqTooltipArrow`) — whether to render the tooltip's arrow/pointer. Defaults to `false`.
- `arrowCentered`: `boolean` — Input (`kbqTooltipArrowCentered`) — centers the arrow on the trigger while preserving the panel placement.
  Requires a visible arrow. Defaults to `false`.
- `offset`: `number | 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.
- `placementChange`: `EventEmitter<KbqPopUpPlacementValues>` — Output (`kbqPlacementChange`) that emits the new placement whenever the tooltip repositions.
- `visibleChange`: `EventEmitter<boolean>` — Output (`kbqVisibleChange`) that emits when the tooltip's visibility changes.
- `modifier`: `KbqEnumValues<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`).
- `header`: `string | TemplateRef<unknown>` — Header text or template, rendered above the tooltip content. Only meaningful with
  `kbqTooltipModifier="extended"`. Replaces the removed `KbqExtendedTooltipTrigger.header`.
- `isOpen`: `boolean` — Whether the pop-up overlay is currently open.
- `isAttached`: `boolean` — 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.
- `openedChange`: `Observable<boolean>` — Emits `true` when the pop-up opens and `false` when it closes. Part of the `KbqSiblingPopup` contract.
- `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()`: `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()`: `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()`: `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:

  ```ts
  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()`: `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 (directive)

```ts
@Directive({ selector: 'kbq-timezone-select-trigger' })
class KbqTimezoneSelectTrigger {}
```

## Pipes

### CitiesByFilterPipe (pipe)

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

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

### UtcOffsetPipe (pipe)

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

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

## Functions

### collapseOtherCountries (function)

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.

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

### filterCitiesBySearchString (function)

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.

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

### getZonesGroupedByCountry (function)

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`.

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

### kbqResolveHostCountry (function)

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.

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

### offset (function)

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

```ts
function offset(value: string): string;
```

### offsetFormatter (function)

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

```ts
function offsetFormatter(value: string): string;
```

### offsetFormatterAsObject (function)

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

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

### parseOffset (function)

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

```ts
function parseOffset(offset: string): number;
```

### promoteCountry (function)

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.

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

### resolveZoneOffset (function)

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.

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

### timezonesSortComparator (function)

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.

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

## Types

### KbqTimezoneGroup (interface)

A group of zones rendered under one label.

```ts
interface KbqTimezoneGroup {
    countryName: string;
    countryCode: string | null;
    zones: KbqTimezoneZone[];
}
```

- `countryName`: `string` — Label of the group: a country name, or the "other countries" label of an aggregate bucket.
- `countryCode`: `string | null` — Country the group stands for, or `null` for an aggregate bucket that spans several countries
  (the one `collapseOtherCountries` produces).
- `zones`: `KbqTimezoneZone[]` — Zones of the group, sorted by offset and then by city.

### KbqTimezonesByCountry (interface)

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

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

### KbqTimezoneZone (interface)

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

```ts
interface KbqTimezoneZone {
    id: string;
    offset?: string;
    city: string;
    countryCode: string;
    countryName: string;
    cities: string;
}
```

- `id`: `string` — IANA time zone name, e.g. `Europe/Berlin`. Used as the form value and to resolve the offset.
- `offset?`: `string` — 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.
- `city`: `string` — Name of the city the zone is displayed under.
- `countryCode`: `string` — ISO 3166-1 alpha-2 code of the country the zone belongs to. Matched case-insensitively.
- `countryName`: `string` — Display name of the country the zone belongs to.
- `cities`: `string` — Other cities in the zone, joined with `', '`.

## Constants

### kbqTimezoneLocaleConfigurationProvider (const)

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

```ts
const kbqTimezoneLocaleConfigurationProvider: (
    configuration: KbqDeepPartial<KbqTimezoneLocaleConfiguration>
) => Provider;
```
